From da0ddb680bc0c00860e5d814e3d9ae39e6bd2916 Mon Sep 17 00:00:00 2001 From: kseitz Date: Tue, 24 Sep 2002 22:48:32 +0000 Subject: [PATCH] Remove botched merge files --- tcl/doc/CrtWindow.3 | 151 ---- tcl/doc/DeleteImg.3 | 35 - tcl/doc/DrawFocHlt.3 | 40 - tcl/doc/EventHndlr.3 | 79 -- tcl/doc/FindPhoto.3 | 234 ------ tcl/doc/FontId.3 | 95 --- tcl/doc/FreeXId.3 | 52 -- tcl/doc/GeomReq.3 | 97 --- tcl/doc/GetAnchor.3 | 86 --- tcl/doc/GetBitmap.3 | 318 -------- tcl/doc/GetCapStyl.3 | 63 -- tcl/doc/GetClrmap.3 | 73 -- tcl/doc/GetColor.3 | 190 ----- tcl/doc/GetCursor.3 | 246 ------- tcl/doc/GetDash.3 | 70 -- tcl/doc/GetFont.3 | 125 ---- tcl/doc/GetGC.3 | 74 -- tcl/doc/GetHINSTANCE.3 | 25 - tcl/doc/GetHWND.3 | 29 - tcl/doc/GetImage.3 | 135 ---- tcl/doc/GetJoinStl.3 | 62 -- tcl/doc/GetJustify.3 | 93 --- tcl/doc/GetOption.3 | 46 -- tcl/doc/GetPixels.3 | 111 --- tcl/doc/GetPixmap.3 | 56 -- tcl/doc/GetRelief.3 | 83 --- tcl/doc/GetRootCrd.3 | 43 -- tcl/doc/GetScroll.3 | 78 -- tcl/doc/GetSelect.3 | 79 -- tcl/doc/GetUid.3 | 50 -- tcl/doc/GetVRoot.3 | 49 -- tcl/doc/GetVisual.3 | 98 --- tcl/doc/Grab.3 | 65 -- tcl/doc/HWNDToWindow.3 | 30 - tcl/doc/HandleEvent.3 | 49 -- tcl/doc/IdToWindow.3 | 36 - tcl/doc/ImgChanged.3 | 69 -- tcl/doc/InternAtom.3 | 58 -- tcl/doc/MainLoop.3 | 32 - tcl/doc/MainWin.3 | 46 -- tcl/doc/MaintGeom.3 | 103 --- tcl/doc/ManageGeom.3 | 94 --- tcl/doc/MapWindow.3 | 53 -- tcl/doc/MeasureChar.3 | 137 ---- tcl/doc/MoveToplev.3 | 55 -- tcl/doc/Name.3 | 82 --- tcl/doc/NameOfImg.3 | 34 - tcl/doc/OwnSelect.3 | 52 -- tcl/doc/ParseArgv.3 | 351 --------- tcl/doc/QWinEvent.3 | 53 -- tcl/doc/Restack.3 | 49 -- tcl/doc/RestrictEv.3 | 81 --- tcl/doc/SetAppName.3 | 65 -- tcl/doc/SetCaret.3 | 40 - tcl/doc/SetClass.3 | 61 -- tcl/doc/SetClassProcs.3 | 91 --- tcl/doc/SetGrid.3 | 67 -- tcl/doc/SetOptions.3 | 653 ----------------- tcl/doc/SetVisual.3 | 54 -- tcl/doc/StrictMotif.3 | 41 -- tcl/doc/TextLayout.3 | 280 ------- tcl/doc/TkInitStubs.3 | 77 -- tcl/doc/Tk_Init.3 | 88 --- tcl/doc/Tk_Main.3 | 61 -- tcl/doc/WindowId.3 | 186 ----- tcl/doc/bell.n | 35 - tcl/doc/bind.n | 531 -------------- tcl/doc/bindtags.n | 81 --- tcl/doc/bitmap.n | 114 --- tcl/doc/button.n | 198 ----- tcl/doc/canvas.n | 1750 -------------------------------------------- tcl/doc/checkbutton.n | 260 ------- tcl/doc/chooseColor.n | 49 -- tcl/doc/chooseDirectory.n | 52 -- tcl/doc/clipboard.n | 94 --- tcl/doc/colors.n | 782 -------------------- tcl/doc/console.n | 142 ---- tcl/doc/cursors.n | 154 ---- tcl/doc/destroy.n | 34 - tcl/doc/dialog.n | 65 -- tcl/doc/entry.n | 549 -------------- tcl/doc/event.n | 366 ---------- tcl/doc/focus.n | 113 --- tcl/doc/focusNext.n | 60 -- tcl/doc/font.n | 287 -------- tcl/doc/frame.n | 136 ---- tcl/doc/getOpenFile.n | 171 ----- tcl/doc/grab.n | 122 ---- tcl/doc/grid.n | 379 ---------- tcl/doc/image.n | 98 --- tcl/doc/keysyms.n | 930 ------------------------ tcl/doc/label.n | 114 --- tcl/doc/labelframe.n | 147 ---- tcl/doc/listbox.n | 556 -------------- tcl/doc/loadTk.n | 76 -- tcl/doc/lower.n | 38 - tcl/doc/menu.n | 784 -------------------- tcl/doc/menubar.n | 33 - tcl/doc/menubutton.n | 203 ------ tcl/doc/message.n | 149 ---- tcl/doc/messageBox.n | 89 --- tcl/doc/option.n | 91 --- tcl/doc/optionMenu.n | 40 - tcl/doc/options.n | 333 --------- tcl/doc/pack-old.n | 196 ----- tcl/doc/pack.n | 268 ------- tcl/doc/palette.n | 73 -- tcl/doc/panedwindow.n | 246 ------- tcl/doc/photo.n | 443 ----------- tcl/doc/place.n | 250 ------- tcl/doc/popup.n | 33 - tcl/doc/radiobutton.n | 256 ------- tcl/doc/raise.n | 38 - tcl/doc/scale.n | 247 ------- tcl/doc/scrollbar.n | 341 --------- tcl/doc/selection.n | 136 ---- tcl/doc/send.n | 97 --- tcl/doc/spinbox.n | 582 --------------- tcl/doc/text.n | 1776 --------------------------------------------- tcl/doc/tk.n | 104 --- tcl/doc/tkerror.n | 38 - tcl/doc/tkvars.n | 80 -- tcl/doc/tkwait.n | 51 -- tcl/doc/toplevel.n | 161 ---- tcl/doc/winfo.n | 332 --------- tcl/doc/wish.1 | 186 ----- tcl/doc/wm.n | 556 -------------- 127 files changed, 23053 deletions(-) delete mode 100644 tcl/doc/CrtWindow.3 delete mode 100644 tcl/doc/DeleteImg.3 delete mode 100644 tcl/doc/DrawFocHlt.3 delete mode 100644 tcl/doc/EventHndlr.3 delete mode 100644 tcl/doc/FindPhoto.3 delete mode 100644 tcl/doc/FontId.3 delete mode 100644 tcl/doc/FreeXId.3 delete mode 100644 tcl/doc/GeomReq.3 delete mode 100644 tcl/doc/GetAnchor.3 delete mode 100644 tcl/doc/GetBitmap.3 delete mode 100644 tcl/doc/GetCapStyl.3 delete mode 100644 tcl/doc/GetClrmap.3 delete mode 100644 tcl/doc/GetColor.3 delete mode 100644 tcl/doc/GetCursor.3 delete mode 100644 tcl/doc/GetDash.3 delete mode 100644 tcl/doc/GetFont.3 delete mode 100644 tcl/doc/GetGC.3 delete mode 100644 tcl/doc/GetHINSTANCE.3 delete mode 100644 tcl/doc/GetHWND.3 delete mode 100644 tcl/doc/GetImage.3 delete mode 100644 tcl/doc/GetJoinStl.3 delete mode 100644 tcl/doc/GetJustify.3 delete mode 100644 tcl/doc/GetOption.3 delete mode 100644 tcl/doc/GetPixels.3 delete mode 100644 tcl/doc/GetPixmap.3 delete mode 100644 tcl/doc/GetRelief.3 delete mode 100644 tcl/doc/GetRootCrd.3 delete mode 100644 tcl/doc/GetScroll.3 delete mode 100644 tcl/doc/GetSelect.3 delete mode 100644 tcl/doc/GetUid.3 delete mode 100644 tcl/doc/GetVRoot.3 delete mode 100644 tcl/doc/GetVisual.3 delete mode 100644 tcl/doc/Grab.3 delete mode 100644 tcl/doc/HWNDToWindow.3 delete mode 100644 tcl/doc/HandleEvent.3 delete mode 100644 tcl/doc/IdToWindow.3 delete mode 100644 tcl/doc/ImgChanged.3 delete mode 100644 tcl/doc/InternAtom.3 delete mode 100644 tcl/doc/MainLoop.3 delete mode 100644 tcl/doc/MainWin.3 delete mode 100644 tcl/doc/MaintGeom.3 delete mode 100644 tcl/doc/ManageGeom.3 delete mode 100644 tcl/doc/MapWindow.3 delete mode 100644 tcl/doc/MeasureChar.3 delete mode 100644 tcl/doc/MoveToplev.3 delete mode 100644 tcl/doc/Name.3 delete mode 100644 tcl/doc/NameOfImg.3 delete mode 100644 tcl/doc/OwnSelect.3 delete mode 100644 tcl/doc/ParseArgv.3 delete mode 100644 tcl/doc/QWinEvent.3 delete mode 100644 tcl/doc/Restack.3 delete mode 100644 tcl/doc/RestrictEv.3 delete mode 100644 tcl/doc/SetAppName.3 delete mode 100644 tcl/doc/SetCaret.3 delete mode 100644 tcl/doc/SetClass.3 delete mode 100644 tcl/doc/SetClassProcs.3 delete mode 100644 tcl/doc/SetGrid.3 delete mode 100644 tcl/doc/SetOptions.3 delete mode 100644 tcl/doc/SetVisual.3 delete mode 100644 tcl/doc/StrictMotif.3 delete mode 100644 tcl/doc/TextLayout.3 delete mode 100644 tcl/doc/TkInitStubs.3 delete mode 100644 tcl/doc/Tk_Init.3 delete mode 100644 tcl/doc/Tk_Main.3 delete mode 100644 tcl/doc/WindowId.3 delete mode 100644 tcl/doc/bell.n delete mode 100644 tcl/doc/bind.n delete mode 100644 tcl/doc/bindtags.n delete mode 100644 tcl/doc/bitmap.n delete mode 100644 tcl/doc/button.n delete mode 100644 tcl/doc/canvas.n delete mode 100644 tcl/doc/checkbutton.n delete mode 100644 tcl/doc/chooseColor.n delete mode 100644 tcl/doc/chooseDirectory.n delete mode 100644 tcl/doc/clipboard.n delete mode 100644 tcl/doc/colors.n delete mode 100644 tcl/doc/console.n delete mode 100644 tcl/doc/cursors.n delete mode 100644 tcl/doc/destroy.n delete mode 100644 tcl/doc/dialog.n delete mode 100644 tcl/doc/entry.n delete mode 100644 tcl/doc/event.n delete mode 100644 tcl/doc/focus.n delete mode 100644 tcl/doc/focusNext.n delete mode 100644 tcl/doc/font.n delete mode 100644 tcl/doc/frame.n delete mode 100644 tcl/doc/getOpenFile.n delete mode 100644 tcl/doc/grab.n delete mode 100644 tcl/doc/grid.n delete mode 100644 tcl/doc/image.n delete mode 100644 tcl/doc/keysyms.n delete mode 100644 tcl/doc/label.n delete mode 100644 tcl/doc/labelframe.n delete mode 100644 tcl/doc/listbox.n delete mode 100644 tcl/doc/loadTk.n delete mode 100644 tcl/doc/lower.n delete mode 100644 tcl/doc/menu.n delete mode 100644 tcl/doc/menubar.n delete mode 100644 tcl/doc/menubutton.n delete mode 100644 tcl/doc/message.n delete mode 100644 tcl/doc/messageBox.n delete mode 100644 tcl/doc/option.n delete mode 100644 tcl/doc/optionMenu.n delete mode 100644 tcl/doc/options.n delete mode 100644 tcl/doc/pack-old.n delete mode 100644 tcl/doc/pack.n delete mode 100644 tcl/doc/palette.n delete mode 100644 tcl/doc/panedwindow.n delete mode 100644 tcl/doc/photo.n delete mode 100644 tcl/doc/place.n delete mode 100644 tcl/doc/popup.n delete mode 100644 tcl/doc/radiobutton.n delete mode 100644 tcl/doc/raise.n delete mode 100644 tcl/doc/scale.n delete mode 100644 tcl/doc/scrollbar.n delete mode 100644 tcl/doc/selection.n delete mode 100644 tcl/doc/send.n delete mode 100644 tcl/doc/spinbox.n delete mode 100644 tcl/doc/text.n delete mode 100644 tcl/doc/tk.n delete mode 100644 tcl/doc/tkerror.n delete mode 100644 tcl/doc/tkvars.n delete mode 100644 tcl/doc/tkwait.n delete mode 100644 tcl/doc/toplevel.n delete mode 100644 tcl/doc/winfo.n delete mode 100644 tcl/doc/wish.1 delete mode 100644 tcl/doc/wm.n diff --git a/tcl/doc/CrtWindow.3 b/tcl/doc/CrtWindow.3 deleted file mode 100644 index 2e7ff4d72b..0000000000 --- a/tcl/doc/CrtWindow.3 +++ /dev/null @@ -1,151 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_CreateWindow 3 4.2 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_CreateWindow, Tk_CreateWindowFromPath, Tk_DestroyWindow, Tk_MakeWindowExist \- create or delete window -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -Tk_Window -\fBTk_CreateWindow\fR(\fIinterp, parent, name, topLevScreen\fR) -.sp -Tk_Window -\fBTk_CreateAnonymousWindow\fR(\fIinterp, parent, topLevScreen\fR) -.sp -Tk_Window -\fBTk_CreateWindowFromPath\fR(\fIinterp, tkwin, pathName, topLevScreen\fR) -.sp -\fBTk_DestroyWindow\fR(\fItkwin\fR) -.sp -\fBTk_MakeWindowExist\fR(\fItkwin\fR) -.SH ARGUMENTS -.AS Tcl_Interp *topLevScreen -.AP Tcl_Interp *interp out -Tcl interpreter to use for error reporting. If no error occurs, -then \fI*interp\fR isn't modified. -.AP Tk_Window parent in -Token for the window that is to serve as the logical parent of -the new window. -.AP "CONST char" *name in -Name to use for this window. Must be unique among all children of -the same \fIparent\fR. -.AP "CONST char" *topLevScreen in -Has same format as \fIscreenName\fR. If NULL, then new window is -created as an internal window. If non-NULL, new window is created as -a top-level window on screen \fItopLevScreen\fR. If \fItopLevScreen\fR -is an empty string (``'') then new -window is created as top-level window of \fIparent\fR's screen. -.AP Tk_Window tkwin in -Token for window. -.AP "CONST char" *pathName in -Name of new window, specified as path name within application -(e.g. \fB.a.b.c\fR). -.BE - -.SH DESCRIPTION -.PP -The procedures \fBTk_CreateWindow\fR, -.VS -\fBTk_CreateAnonymousWindow\fR, and \fBTk_CreateWindowFromPath\fR -are used to create new windows for -use in Tk-based applications. Each of the procedures returns a token -that can be used to manipulate the window in other calls to the Tk -library. If the window couldn't be created successfully, then NULL -is returned and \fIinterp->result\fR is modified to hold an error -message. -.PP -Tk supports two different kinds of windows: internal -windows and top-level windows. -.VE -An internal window is an interior window of a Tk application, such as a -scrollbar or menu bar or button. A top-level window is one that is -created as a child of a screen's root window, rather than as an -interior window, but which is logically part of some existing main -window. Examples of top-level windows are pop-up menus and dialog boxes. -.PP -New windows may be created by calling -\fBTk_CreateWindow\fR. If the \fItopLevScreen\fR argument is -NULL, then the new window will be an internal window. If -\fItopLevScreen\fR is non-NULL, then the new window will be a -top-level window: \fItopLevScreen\fR indicates the name of -a screen and the new window will be created as a child of the -root window of \fItopLevScreen\fR. In either case Tk will -consider the new window to be the logical child of \fIparent\fR: -the new window's path name will reflect this fact, options may -be specified for the new window under this assumption, and so on. -The only difference is that new X window for a top-level window -will not be a child of \fIparent\fR's X window. For example, a pull-down -menu's \fIparent\fR would be the button-like window used to invoke it, -which would in turn be a child of the menu bar window. A dialog box might -have the application's main window as its parent. -.PP -\fBTk_CreateAnonymousWindow\fR differs from \fBTk_CreateWindow\fR in -that it creates an unnamed window. This window will be manipulable -only using C interfaces, and will not be visible to Tcl scripts. Both -interior windows and top-level windows may be created with -\fBTk_CreateAnonymousWindow\fR. -.PP -\fBTk_CreateWindowFromPath\fR offers an alternate way of specifying -new windows. In \fBTk_CreateWindowFromPath\fR the new -window is specified with a token for any window in the target -application (\fItkwin\fR), plus a path name for the new window. -It produces the same effect as \fBTk_CreateWindow\fR and allows -both top-level and internal windows to be created, depending on -the value of \fItopLevScreen\fR. In calls to \fBTk_CreateWindowFromPath\fR, -as in calls to \fBTk_CreateWindow\fR, the parent of the new window -must exist at the time of the call, but the new window must not -already exist. -.PP -The window creation procedures don't -actually issue the command to X to create a window. -Instead, they create a local data structure associated with -the window and defer the creation of the X window. -The window will actually be created by the first call to -\fBTk_MapWindow\fR. Deferred window creation allows various -aspects of the window (such as its size, background color, -etc.) to be modified after its creation without incurring -any overhead in the X server. When the window is finally -mapped all of the window attributes can be set while creating -the window. -.PP -The value returned by a window-creation procedure is not the -X token for the window (it can't be, since X hasn't been -asked to create the window yet). Instead, it is a token -for Tk's local data structure for the window. Most -of the Tk library procedures take Tk_Window tokens, rather -than X identifiers. The actual -X window identifier can be retrieved from the local -data structure using the \fBTk_WindowId\fR macro; see -the manual entry for \fBTk_WindowId\fR for details. -.PP -\fBTk_DestroyWindow\fR deletes a window and all the data -structures associated with it, including any event handlers -created with \fBTk_CreateEventHandler\fR. In addition, -\fBTk_DestroyWindow\fR will delete any children of \fItkwin\fR -recursively (where children are defined in the Tk sense, consisting -of all windows that were created with the given window as \fIparent\fR). -If \fItkwin\fR is an internal window, then event -handlers interested in destroy events -are invoked immediately. If \fItkwin\fR is a top-level or main window, -then the event handlers will be invoked later, after X has seen -the request and returned an event for it. -.PP -If a window has been created -but hasn't been mapped, so no X window exists, it is -possible to force the creation of the X window by -calling \fBTk_MakeWindowExist\fR. This procedure issues -the X commands to instantiate the window given by \fItkwin\fR. - -.SH KEYWORDS -create, deferred creation, destroy, display, internal window, -screen, top-level window, window diff --git a/tcl/doc/DeleteImg.3 b/tcl/doc/DeleteImg.3 deleted file mode 100644 index 6cdbffd6aa..0000000000 --- a/tcl/doc/DeleteImg.3 +++ /dev/null @@ -1,35 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_DeleteImage 3 4.0 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_DeleteImage \- Destroy an image. -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -\fBTk_DeleteImage\fR(\fIinterp, name\fR) -.SH ARGUMENTS -.AS Tcl_Interp *interp -.AP Tcl_Interp *interp in -Interpreter for which the image was created. -.AP "CONST char" *name in -Name of the image. -.BE - -.SH DESCRIPTION -.PP -\fBTk_DeleteImage\fR deletes the image given by \fIinterp\fR -and \fIname\fR, if there is one. All instances of that image -will redisplay as empty regions. If the given image does not -exist then the procedure has no effect. - -.SH KEYWORDS -delete image, image manager diff --git a/tcl/doc/DrawFocHlt.3 b/tcl/doc/DrawFocHlt.3 deleted file mode 100644 index d659933b08..0000000000 --- a/tcl/doc/DrawFocHlt.3 +++ /dev/null @@ -1,40 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_DrawFocusHighlight 3 4.0 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_DrawFocusHighlight \- draw the traversal highlight ring for a widget -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -\fBTk_DrawFocusHighlight(\fItkwin, gc, width, drawable\fB)\fR -.SH ARGUMENTS -.AS "Tcl_Interp" *joinPtr -.AP Tk_Window tkwin in -Window for which the highlight is being drawn. Used to retrieve -the window's dimensions, among other things. -.AP GC gc in -Graphics context to use for drawing the highlight. -.AP int width in -Width of the highlight ring, in pixels. -.AP Drawable drawable in -Drawable in which to draw the highlight; usually an offscreen -pixmap for double buffering. -.BE - -.SH DESCRIPTION -.PP -\fBTk_DrawFocusHighlight\fR is a utility procedure that draws the -traversal highlight ring for a widget. -It is typically invoked by widgets during redisplay. - -.SH KEYWORDS -focus, traversal highlight diff --git a/tcl/doc/EventHndlr.3 b/tcl/doc/EventHndlr.3 deleted file mode 100644 index 234daea0f0..0000000000 --- a/tcl/doc/EventHndlr.3 +++ /dev/null @@ -1,79 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_CreateEventHandler 3 "" Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_CreateEventHandler, Tk_DeleteEventHandler \- associate procedure callback with an X event -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -\fBTk_CreateEventHandler\fR(\fItkwin, mask, proc, clientData\fR) -.sp -\fBTk_DeleteEventHandler\fR(\fItkwin, mask, proc, clientData\fR) -.SH ARGUMENTS -.AS "unsigned long" clientData -.AP Tk_Window tkwin in -Token for window in which events may occur. -.AP "unsigned long" mask in -Bit-mask of events (such as \fBButtonPressMask\fR) -for which \fIproc\fR should be called. -.AP Tk_EventProc *proc in -Procedure to invoke whenever an event in \fImask\fR occurs -in the window given by \fItkwin\fR. -.AP ClientData clientData in -Arbitrary one-word value to pass to \fIproc\fR. -.BE - -.SH DESCRIPTION -.PP -\fBTk_CreateEventHandler\fR arranges for \fIproc\fR to be -invoked in the future whenever one of the event types specified -by \fImask\fR occurs in the window specified by \fItkwin\fR. -The callback to \fIproc\fR will be made by \fBTk_HandleEvent\fR; -this mechanism only works in programs that dispatch events -through \fBTk_HandleEvent\fR (or through other Tk procedures that -call \fBTk_HandleEvent\fR, such as \fBTk_DoOneEvent\fR or -\fBTk_MainLoop\fR). -.PP -\fIProc\fR should have arguments and result that match the -type \fBTk_EventProc\fR: -.CS -typedef void Tk_EventProc( - ClientData \fIclientData\fR, - XEvent *\fIeventPtr\fR); -.CE -The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR -argument given to \fBTk_CreateEventHandler\fR when the callback -was created. Typically, \fIclientData\fR points to a data -structure containing application-specific information about -the window in which the event occurred. \fIEventPtr\fR is -a pointer to the X event, which will be one of the ones -specified in the \fImask\fR argument to \fBTk_CreateEventHandler\fR. -.PP -\fBTk_DeleteEventHandler\fR may be called to delete a -previously-created event handler: it deletes the first handler -it finds that is associated with \fItkwin\fR and matches the -\fImask\fR, \fIproc\fR, and \fIclientData\fR arguments. If -no such handler exists, then \fBTk_HandleEvent\fR returns -without doing anything. Although Tk supports it, it's probably -a bad idea to have more than one callback with the same \fImask\fR, -\fIproc\fR, and \fIclientData\fR arguments. -When a window is deleted all of its handlers will be deleted -automatically; in this case there is no need to call -\fBTk_DeleteEventHandler\fR. -.PP -If multiple handlers are declared for the same type of X event -on the same window, then the handlers will be invoked in the -order they were created. - -.SH KEYWORDS -bind, callback, event, handler diff --git a/tcl/doc/FindPhoto.3 b/tcl/doc/FindPhoto.3 deleted file mode 100644 index 60a0fdb970..0000000000 --- a/tcl/doc/FindPhoto.3 +++ /dev/null @@ -1,234 +0,0 @@ -'\" -'\" Copyright (c) 1994 The Australian National University -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" Author: Paul Mackerras (paulus@cs.anu.edu.au), -'\" Department of Computer Science, -'\" Australian National University. -'\" -'\" RCS: @(#) $Id$ -'\" -.so man.macros -.TH Tk_FindPhoto 3 8.0 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_FindPhoto, Tk_PhotoPutBlock, Tk_PhotoPutZoomedBlock, Tk_PhotoGetImage, Tk_PhotoBlank, Tk_PhotoExpand, Tk_PhotoGetSize, Tk_PhotoSetSize \- manipulate the image data stored in a photo image. -.SH SYNOPSIS -.nf -\fB#include \fR -\fB#include \fR -.sp -Tk_PhotoHandle -.VS 8.0 br -\fBTk_FindPhoto\fR(\fIinterp, imageName\fR) -.VE -.sp -void -\fBTk_PhotoPutBlock\fR(\fIhandle, blockPtr, x, y, width, height, compRule\fR) -.sp -void -\fBTk_PhotoPutZoomedBlock\fR(\fIhandle, blockPtr, x, y, width, height,\ -zoomX, zoomY, subsampleX, subsampleY, compRule\fR) -.sp -int -\fBTk_PhotoGetImage\fR(\fIhandle, blockPtr\fR) -.sp -void -\fBTk_PhotoBlank\fR(\fIhandle\fR) -.sp -void -\fBTk_PhotoExpand\fR(\fIhandle, width, height\fR) -.sp -void -\fBTk_PhotoGetSize\fR(\fIhandle, widthPtr, heightPtr\fR) -.sp -void -\fBTk_PhotoSetSize\fR(\fIhandle, width, height\fR) -.SH ARGUMENTS -.AS Tk_PhotoImageBlock window_path -.AP Tcl_Interp *interp in -.VS -Interpreter in which image was created. -.VE -.AP "CONST char" *imageName in -Name of the photo image. -.AP Tk_PhotoHandle handle in -Opaque handle identifying the photo image to be affected. -.AP Tk_PhotoImageBlock *blockPtr in -Specifies the address and storage layout of image data. -.AP int x in -Specifies the X coordinate where the top-left corner of the block is -to be placed within the image. -.AP int y in -Specifies the Y coordinate where the top-left corner of the block is -to be placed within the image. -.AP int width in -Specifies the width of the image area to be affected (for -\fBTk_PhotoPutBlock\fR) or the desired image width (for -\fBTk_PhotoExpand\fR and \fBTk_PhotoSetSize\fR). -.VS 8.4 -.AP int compRule in -Specifies the compositing rule used when combining transparent pixels -in a block of data with a photo image. Must be one of -TK_PHOTO_COMPOSITE_OVERLAY (which puts the block of data over the top -of the existing photo image, with the previous contents showing -through in the transparent bits) or TK_PHOTO_COMPOSITE_SET (which -discards the existing photo image contents in the rectangle covered by -the data block.) -.VE 8.4 -.AP int height in -Specifies the height of the image area to be affected (for -\fBTk_PhotoPutBlock\fR) or the desired image height (for -\fBTk_PhotoExpand\fR and \fBTk_PhotoSetSize\fR). -.AP int *widthPtr out -Pointer to location in which to store the image width. -.AP int *heightPtr out -Pointer to location in which to store the image height. -.AP int subsampleX in -Specifies the subsampling factor in the X direction for input -image data. -.AP int subsampleY in -Specifies the subsampling factor in the Y direction for input -image data. -.AP int zoomX in -Specifies the zoom factor to be applied in the X direction to pixels -being written to the photo image. -.AP int zoomY in -Specifies the zoom factor to be applied in the Y direction to pixels -being written to the photo image. -.BE - -.SH DESCRIPTION -.PP -\fBTk_FindPhoto\fR returns an opaque handle that is used to identify a -particular photo image to the other procedures. The parameter is the -name of the image, that is, the name specified to the \fBimage create -photo\fR command, or assigned by that command if no name was specified. -.PP -\fBTk_PhotoPutBlock\fR is used to supply blocks of image data to be -displayed. The call affects an area of the image of size -\fIwidth\fR x \fIheight\fR pixels, with its top-left corner at -coordinates (\fIx\fR,\fIy\fR). All of \fIwidth\fR, \fIheight\fR, -\fIx\fR, and \fIy\fR must be non-negative. -If part of this area lies outside the -current bounds of the image, the image will be expanded to include the -area, unless the user has specified an explicit image size with the -\fB\-width\fR and/or \fB\-height\fR widget configuration options -(see photo(n)); in that -case the area is silently clipped to the image boundaries. -.PP -The \fIblock\fR parameter is a pointer to a -\fBTk_PhotoImageBlock\fR structure, defined as follows: -.CS -typedef struct { - unsigned char *\fIpixelPtr\fR; - int \fIwidth\fR; - int \fIheight\fR; - int \fIpitch\fR; - int \fIpixelSize\fR; - int \fIoffset[4]\fR; -} Tk_PhotoImageBlock; -.CE -The \fIpixelPtr\fR field points to the first pixel, that is, the -top-left pixel in the block. -The \fIwidth\fR and \fIheight\fR fields specify the dimensions of the -block of pixels. The \fIpixelSize\fR field specifies the address -difference between two horizontally adjacent pixels. Often it is 3 -or 4, but it can have any value. The \fIpitch\fR field specifies the -address difference between two vertically adjacent pixels. The -\fIoffset\fR array contains the offsets from the address of a pixel -to the addresses of the bytes containing the red, green, blue and alpha -(transparency) components. These are normally 0, 1, 2 and 3, but can -have other values, e.g., for images that are stored as separate red, -green and blue planes. -.PP -.VS 8.4 -The \fIcompRule\fR parameter to \fBTk_PhotoPutBlock\fR specifies a -compositing rule that says what to do with transparent pixels. The -value TK_PHOTO_COMPOSITE_OVERLAY says that the previous contents of -the photo image should show through, and the value -TK_PHOTO_COMPOSITE_SET says that the previous contents of the photo -image should be completely ignored, and the values from the block be -copied directly across. The behavior in Tk8.3 and earlier was -equivalent to having TK_PHOTO_COMPOSITE_OVERLAY as a compositing rule. -.VE 8.4 -.PP -The value given for the \fIwidth\fR and \fIheight\fR parameters to -\fBTk_PhotoPutBlock\fR do not have to correspond to the values specified -in \fIblock\fR. If they are smaller, \fBTk_PhotoPutBlock\fR extracts a -sub-block from the image data supplied. If they are larger, the data -given are replicated (in a tiled fashion) to fill the specified area. -These rules operate independently in the horizontal and vertical -directions. -.PP -\fBTk_PhotoPutZoomedBlock\fR works like \fBTk_PhotoPutBlock\fR except that -the image can be reduced or enlarged for display. The -\fIsubsampleX\fR and \fIsubsampleY\fR parameters allow the size of the -image to be reduced by subsampling. -\fBTk_PhotoPutZoomedBlock\fR will use only pixels from the input image -whose X coordinates are multiples of \fIsubsampleX\fR, and whose Y -coordinates are multiples of \fIsubsampleY\fR. For example, an image -of 512x512 pixels can be reduced to 256x256 by setting -\fIsubsampleX\fR and \fIsubsampleY\fR to 2. -.PP -The \fIzoomX\fR and \fIzoomY\fR parameters allow the image to be -enlarged by pixel replication. Each pixel of the (possibly subsampled) -input image will be written to a block \fIzoomX\fR pixels wide and -\fIzoomY\fR pixels high of the displayed image. Subsampling and -zooming can be used together for special effects. -.PP -\fBTk_PhotoGetImage\fR can be used to retrieve image data from a photo -image. \fBTk_PhotoGetImage\fR fills -in the structure pointed to by the \fIblockPtr\fR parameter with values -that describe the address and layout of the image data that the -photo image has stored internally. The values are valid -until the image is destroyed or its size is changed. -\fBTk_PhotoGetImage\fR returns 1 for compatibility with the -corresponding procedure in the old photo widget. -.PP -\fBTk_PhotoBlank\fR blanks the entire area of the -photo image. Blank areas of a photo image are transparent. -.PP -\fBTk_PhotoExpand\fR requests that the widget's image be expanded to be -at least \fIwidth\fR x \fIheight\fR pixels in size. The width and/or -height are unchanged if the user has specified an explicit image width -or height with the \fB\-width\fR and/or \fB\-height\fR configuration -options, respectively. -If the image data -are being supplied in many small blocks, it is more efficient to use -\fBTk_PhotoExpand\fR or \fBTk_PhotoSetSize\fR at the beginning rather than -allowing the image to expand in many small increments as image blocks -are supplied. -.PP -\fBTk_PhotoSetSize\fR specifies the size of the image, as if the user -had specified the given \fIwidth\fR and \fIheight\fR values to the -\fB\-width\fR and \fB\-height\fR configuration options. A value of -zero for \fIwidth\fR or \fIheight\fR does not change the image's width -or height, but allows the width or height to be changed by subsequent -calls to \fBTk_PhotoPutBlock\fR, \fBTk_PhotoPutZoomedBlock\fR or -\fBTk_PhotoExpand\fR. -.PP -\fBTk_PhotoGetSize\fR returns the dimensions of the image in -*\fIwidthPtr\fR and *\fIheightPtr\fR. - -.SH PORTABILITY -.VS 8.4 -.PP -In Tk 8.3 and earlier, \fBTk_PhotoPutBlock\fR and -\fBTk_PhotoPutZoomedBlock\fR had different signatures. If you want to -compile code that uses the old interface against 8.4 without updating -your code, compile it with the flag --DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK. Code linked using Stubs against -older versions of Tk will continue to work. -.VE 8.4 - -.SH CREDITS -.PP -The code for the photo image type was developed by Paul Mackerras, -based on his earlier photo widget code. - -.SH KEYWORDS -photo, image diff --git a/tcl/doc/FontId.3 b/tcl/doc/FontId.3 deleted file mode 100644 index 2c55153e4f..0000000000 --- a/tcl/doc/FontId.3 +++ /dev/null @@ -1,95 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_FontId 3 8.0 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_FontId, Tk_GetFontMetrics, Tk_PostscriptFontName \- accessor functions for -fonts -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -Font -\fBTk_FontId(\fItkfont\fB)\fR -.sp -void -\fBTk_GetFontMetrics(\fItkfont, fmPtr\fB)\fR -.sp -int -\fBTk_PostscriptFontName(\fItkfont, dsPtr\fB)\fR - -.SH ARGUMENTS -.AS Tk_FontMetrics *dsPtr -.AP Tk_Font tkfont in -Opaque font token being queried. Must have been returned by a previous -call to \fBTk_GetFont\fR. -.AP Tk_FontMetrics *fmPtr out -Pointer to structure in which the font metrics for \fItkfont\fR will -be stored. -.AP Tcl_DString *dsPtr out -Pointer to an initialized \fBTcl_DString\fR to which the name of the -Postscript font that corresponds to \fItkfont\fR will be appended. -.BE - -.SH DESCRIPTION -.PP -Given a \fItkfont\fR, \fBTk_FontId\fR returns the token that should be -selected into an XGCValues structure in order to construct a graphics -context that can be used to draw text in the specified font. -.PP -\fBTk_GetFontMetrics\fR computes the ascent, descent, and linespace of the -\fItkfont\fR in pixels and stores those values in the structure pointer to by -\fIfmPtr\fR. These values can be used in computations such as to space -multiple lines of text, to align the baselines of text in different -fonts, and to vertically align text in a given region. See the -documentation for the \fBfont\fR command for definitions of the terms -ascent, descent, and linespace, used in font metrics. -.PP -\fBTk_PostscriptFontName\fR maps a \fItkfont\fR to the corresponding -Postcript font name that should be used when printing. The return value -is the size in points of the \fItkfont\fR and the Postscript font name is -appended to \fIdsPtr\fR. \fIDsPtr\fR must refer to an initialized -\fBTcl_DString\fR. Given a ``reasonable'' Postscript printer, the -following screen font families should print correctly: -.IP -\fBAvant Garde\fR, \fBArial\fR, \fBBookman\fR, \fBCourier\fR, -\fBCourier New\fR, \fBGeneva\fR, \fBHelvetica\fR, \fBMonaco\fR, -\fBNew Century Schoolbook\fR, \fBNew York\fR, \fBPalatino\fR, \fBSymbol\fR, -\fBTimes\fR, \fBTimes New Roman\fR, \fBZapf Chancery\fR, and -\fBZapf Dingbats\fR. -.PP -Any other font families may not print correctly because the computed -Postscript font name may be incorrect or not exist on the printer. -.VS 8.0 br -.SH "DATA STRUCTURES" -The Tk_FontMetrics data structure is used by Tk_GetFontMetrics to return -information about a font and is defined as follows: -.CS -typedef struct Tk_FontMetrics { - int ascent; - int descent; - int linespace; -} Tk_FontMetrics; -.CE -The \fIlinespace\fR field is the amount in pixels that the tallest -letter sticks up above the baseline, plus any extra blank space added -by the designer of the font. -.PP -The \fIdescent\fR is the largest amount in pixels that any letter -sticks below the baseline, plus any extra blank space added by the -designer of the font. -.PP -The \fIlinespace\fR is the sum of the ascent and descent. How far -apart two lines of text in the same font should be placed so that none -of the characters in one line overlap any of the characters in the -other line. -.VE -.SH KEYWORDS -font diff --git a/tcl/doc/FreeXId.3 b/tcl/doc/FreeXId.3 deleted file mode 100644 index 3f8419c737..0000000000 --- a/tcl/doc/FreeXId.3 +++ /dev/null @@ -1,52 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_FreeXId 3 4.0 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_FreeXId \- make X resource identifier available for reuse -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -\fBTk_FreeXId(\fIdisplay, id\fB)\fR -.SH ARGUMENTS -.AS Display *display out -.AP Display *display in -Display for which \fIid\fR was allocated. -.AP XID id in -Identifier of X resource (window, font, pixmap, cursor, graphics -context, or colormap) that is no longer in use. -.BE - -.SH DESCRIPTION -.PP -The default allocator for resource identifiers provided by Xlib is very -simple-minded and does not allow resource identifiers to be re-used. -If a long-running application reaches the end of the resource id -space, it will generate an X protocol error and crash. -Tk replaces the default id allocator with its own allocator, which -allows identifiers to be reused. -In order for this to work, \fBTk_FreeXId\fR must be called to -tell the allocator about resources that have been freed. -Tk automatically calls \fBTk_FreeXId\fR whenever it frees a -resource, so if you use procedures like \fBTk_GetFont\fR, -\fBTk_GetGC\fR, and \fBTk_GetPixmap\fR then you need not call -\fBTk_FreeXId\fR. -However, if you allocate resources directly from Xlib, for example -by calling \fBXCreatePixmap\fR, then you should call \fBTk_FreeXId\fR -when you call the corresponding Xlib free procedure, such as -\fBXFreePixmap\fR. -If you don't call \fBTk_FreeXId\fR then the resource identifier will -be lost, which could cause problems if the application runs long enough -to lose all of the available identifiers. - -.SH KEYWORDS -resource identifier diff --git a/tcl/doc/GeomReq.3 b/tcl/doc/GeomReq.3 deleted file mode 100644 index 71278f3ae8..0000000000 --- a/tcl/doc/GeomReq.3 +++ /dev/null @@ -1,97 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_GeometryRequest 3 "8.4" Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_GeometryRequest, Tk_SetMinimumRequestSize, Tk_SetInternalBorder, Tk_SetInternalBorderEx \- specify desired geometry or internal border for a window -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -\fBTk_GeometryRequest\fR(\fItkwin, reqWidth, reqHeight\fR) -.sp -\fBTk_SetMinimumRequestSize\fR(\fItkwin, minWidth, minHeight\fR) -.sp -\fBTk_SetInternalBorder\fR(\fItkwin, width\fR) -.sp -\fBTk_SetInternalBorderEx\fR(\fItkwin, left, right, top, bottom\fR) -.SH ARGUMENTS -.AS baseHeight clientData -.AP Tk_Window tkwin in -Window for which geometry is being requested. -.AP int reqWidth in -Desired width for \fItkwin\fR, in pixel units. -.AP int reqHeight in -Desired height for \fItkwin\fR, in pixel units. -.AP int minWidth in -Desired minimum requested width for \fItkwin\fR, in pixel units. -.AP int minHeight in -Desired minimum requested height for \fItkwin\fR, in pixel units. -.AP int width in -Space to leave for internal border for \fItkwin\fR, in pixel units. -.AP int left in -Space to leave for left side of internal border for \fItkwin\fR, in pixel units. -.AP int right in -Space to leave for right side of internal border for \fItkwin\fR, in pixel units. -.AP int top in -Space to leave for top side of internal border for \fItkwin\fR, in pixel units. -.AP int bottom in -Space to leave for bottom side of internal border for \fItkwin\fR, in pixel units. -.BE - -.SH DESCRIPTION -.PP -\fBTk_GeometryRequest\fR is called by widget code to indicate its -preference for the dimensions of a particular window. The arguments -to \fBTk_GeometryRequest\fR are made available to the geometry -manager for the window, which then decides on the actual geometry -for the window. Although geometry managers generally try to satisfy -requests made to \fBTk_GeometryRequest\fR, there is no guarantee that -this will always be possible. Widget code should not assume that -a geometry request will be satisfied until it receives a -\fBConfigureNotify\fR event indicating that the geometry change has -occurred. Widget code should never call procedures like -\fBTk_ResizeWindow\fR directly. Instead, it should invoke -\fBTk_GeometryRequest\fR and leave the final geometry decisions to -the geometry manager. -.PP -If \fItkwin\fR is a top-level window, then the geometry information -will be passed to the window manager using the standard ICCCM protocol. -.PP -\fBTk_SetInternalBorder\fR is called by widget code to indicate that -the widget has an internal border. This means that the widget draws -a decorative border inside the window instead of using the standard -X borders, which are external to the window's area. For example, -internal borders are used to draw 3-D effects. \fIWidth\fR -specifies the width of the border in pixels. Geometry managers will -use this information to avoid placing any children of \fItkwin\fR -overlapping the outermost \fIwidth\fR pixels of \fItkwin\fR's area. -.PP -\fBTk_SetInternalBorderEx\fR works like \fBTk_SetInternalBorder\fR -but lets you specify different widths for different sides of the window. -.PP -\fBTk_SetMinimumRequestSize\fR is called by widget code to indicate -that a geometry manager should request at least this size for the -widget. This allows a widget to have some control over its size when -a propagating geometry manager is used inside it. -.PP -The information specified in calls to \fBTk_GeometryRequest\fR, -\fBTk_SetMinimumRequestSize\fR, \fBTk_SetInternalBorder\fR and -\fBTk_SetInternalBorderEx\fR can be retrieved using the macros -\fBTk_ReqWidth\fR, \fBTk_ReqHeight\fR, \fBTk_MinReqWidth\fR, -\fBTk_MinReqHeight\fR, \fBTk_MinReqWidth\fR, \fBTk_InternalBorderLeft\fR, -\fBTk_InternalBorderRight\fR, \fBTk_InternalBorderTop\fR and -\fBTk_InternalBorderBottom\fR. -See the \fBTk_WindowId\fR manual entry for details. - -.SH KEYWORDS -geometry, request diff --git a/tcl/doc/GetAnchor.3 b/tcl/doc/GetAnchor.3 deleted file mode 100644 index a245349ba7..0000000000 --- a/tcl/doc/GetAnchor.3 +++ /dev/null @@ -1,86 +0,0 @@ -'\" -'\" 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$ -'\" -.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 \fR -.sp -.VS 8.1 -int -\fBTk_GetAnchorFromObj(\fIinterp, objPtr, anchorPtr\fB)\fR -.VE -.sp -int -\fBTk_GetAnchor(\fIinterp, string, anchorPtr\fB)\fR -.sp -CONST 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 "CONST 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. - -.SH KEYWORDS -anchor position diff --git a/tcl/doc/GetBitmap.3 b/tcl/doc/GetBitmap.3 deleted file mode 100644 index b0da2f2638..0000000000 --- a/tcl/doc/GetBitmap.3 +++ /dev/null @@ -1,318 +0,0 @@ -'\" -'\" 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$ -'\" -.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 \- maintain database of single-plane pixmaps -.SH SYNOPSIS -.nf -\fB#include \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 -CONST 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 "CONST 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 -a call to \fBTk_DefineBitmap\fR. The following names are pre-defined -by Tk: -.RS -.TP 12 -\fBerror\fR -The international "don't" symbol: a circle with a diagonal line -across it. -.VS "" br -.TP 12 -\fBgray75\fR -75% gray: a checkerboard pattern where three out of four bits are on. -.VE -.TP 12 -\fBgray50\fR -50% gray: a checkerboard pattern where every other bit is on. -.VS "" br -.TP 12 -\fBgray25\fR -25% gray: a checkerboard pattern where one out of every four bits is on. -.VE -.TP 12 -\fBgray12\fR -12.5% gray: a pattern where one-eighth of the bits are on, consisting of -every fourth pixel in every other row. -.TP 12 -\fBhourglass\fR -An hourglass symbol. -.TP 12 -\fBinfo\fR -A large letter ``i''. -.TP 12 -\fBquesthead\fR -The silhouette of a human head, with a question mark in it. -.TP 12 -\fBquestion\fR -A large question-mark. -.TP 12 -\fBwarning\fR -A large exclamation point. -.PP -In addition, the following pre-defined names are available only on the -\fBMacintosh\fR platform: -.TP 12 -\fBdocument\fR -A generic document. -.TP 12 -\fBstationery\fR -Document stationery. -.TP 12 -\fBedition\fR -The \fIedition\fR symbol. -.TP 12 -\fBapplication\fR -Generic application icon. -.TP 12 -\fBaccessory\fR -A desk accessory. -.TP 12 -\fBfolder\fR -Generic folder icon. -.TP 12 -\fBpfolder\fR -A locked folder. -.TP 12 -\fBtrash\fR -A trash can. -.TP 12 -\fBfloppy\fR -A floppy disk. -.TP 12 -\fBramdisk\fR -A floppy disk with chip. -.TP 12 -\fBcdrom\fR -A cd disk icon. -.TP 12 -\fBpreferences\fR -A folder with prefs symbol. -.TP 12 -\fBquerydoc\fR -A database document icon. -.TP 12 -\fBstop\fR -A stop sign. -.TP 12 -\fBnote\fR -A face with ballon words. -.TP 12 -\fBcaution\fR -A triangle with an exclamation point. -.RE -.LP -.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 diff --git a/tcl/doc/GetCapStyl.3 b/tcl/doc/GetCapStyl.3 deleted file mode 100644 index 5a88045a82..0000000000 --- a/tcl/doc/GetCapStyl.3 +++ /dev/null @@ -1,63 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_GetCapStyle 3 "" Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_GetCapStyle, Tk_NameOfCapStyle \- translate between strings and cap styles -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -int -\fBTk_GetCapStyle(\fIinterp, string, capPtr\fB)\fR -.sp -CONST char * -\fBTk_NameOfCapStyle(\fIcap\fB)\fR -.SH ARGUMENTS -.AS "Tcl_Interp" *capPtr -.AP Tcl_Interp *interp in -Interpreter to use for error reporting. -.AP "CONST char" *string in -String containing name of cap style: one of ```butt'', ``projecting'', -or ``round''. -.AP int *capPtr out -Pointer to location in which to store X cap style corresponding to -\fIstring\fR. -.AP int cap in -Cap style: one of \fBCapButt\fR, \fBCapProjecting\fR, or \fBCapRound\fR. -.BE - -.SH DESCRIPTION -.PP -\fBTk_GetCapStyle\fR places in \fI*capPtr\fR the X cap style -corresponding to \fIstring\fR. -This will be one of the values -\fBCapButt\fR, \fBCapProjecting\fR, or \fBCapRound\fR. -Cap styles are typically used in X graphics contexts to indicate -how the end-points of lines should be capped. -See the X documentation for information on what each style -implies. -.PP -Under normal circumstances the return value is \fBTCL_OK\fR and -\fIinterp\fR is unused. -If \fIstring\fR doesn't contain a valid cap style -or an abbreviation of one of these names, then an error message is -stored in \fIinterp->result\fR, \fBTCL_ERROR\fR is returned, and -\fI*capPtr\fR is unmodified. -.PP -\fBTk_NameOfCapStyle\fR is the logical inverse of \fBTk_GetCapStyle\fR. -Given a cap style such as \fBCapButt\fR it returns a -statically-allocated string corresponding to \fIcap\fR. -If \fIcap\fR isn't a legal cap style, then -``unknown cap style'' is returned. - -.SH KEYWORDS -butt, cap style, projecting, round diff --git a/tcl/doc/GetClrmap.3 b/tcl/doc/GetClrmap.3 deleted file mode 100644 index 490ef78010..0000000000 --- a/tcl/doc/GetClrmap.3 +++ /dev/null @@ -1,73 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_GetColormap 3 4.0 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_GetColormap, Tk_FreeColormap \- allocate and free colormaps -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -Colormap -\fBTk_GetColormap(\fIinterp, tkwin, string\fB)\fR -.sp -\fBTk_FreeColormap(\fIdisplay, colormap\fB)\fR -.SH ARGUMENTS -.AS "Colormap" colormap -.AP Tcl_Interp *interp in -Interpreter to use for error reporting. -.AP Tk_Window tkwin in -Token for window in which colormap will be used. -.AP "CONST char" *string in -Selects a colormap: either \fBnew\fR or the name of a window -with the same screen and visual as \fItkwin\fR. -.AP Display *display in -Display for which \fIcolormap\fR was allocated. -.AP Colormap colormap in -Colormap to free; must have been returned by a previous -call to \fBTk_GetColormap\fR or \fBTk_GetVisual\fR. -.BE - -.SH DESCRIPTION -.PP -These procedures are used to manage colormaps. -\fBTk_GetColormap\fR returns a colormap suitable for use in \fItkwin\fR. -If its \fIstring\fR argument is \fBnew\fR then a new colormap is -created; otherwise \fIstring\fR must be the name of another window -with the same screen and visual as \fItkwin\fR, and the colormap from that -window is returned. -If \fIstring\fR doesn't make sense, or if it refers to a window on -a different screen from \fItkwin\fR or with -a different visual than \fItkwin\fR, then \fBTk_GetColormap\fR returns -\fBNone\fR and leaves an error message in \fIinterp->result\fR. -.PP -\fBTk_FreeColormap\fR should be called when a colormap returned by -\fBTk_GetColormap\fR is no longer needed. -Tk maintains a reference count for each colormap returned by -\fBTk_GetColormap\fR, so there should eventually be one call to -\fBTk_FreeColormap\fR for each call to \fBTk_GetColormap\fR. -When a colormap's reference count becomes zero, Tk releases the -X colormap. -.PP -\fBTk_GetVisual\fR and \fBTk_GetColormap\fR work together, in that -a new colormap created by \fBTk_GetVisual\fR may later be returned -by \fBTk_GetColormap\fR. -The reference counting mechanism for colormaps includes both procedures, -so callers of \fBTk_GetVisual\fR must also call \fBTk_FreeColormap\fR -to release the colormap. -If \fBTk_GetColormap\fR is called with a \fIstring\fR value of -\fBnew\fR then the resulting colormap will never -be returned by \fBTk_GetVisual\fR; however, it can be used in other -windows by calling \fBTk_GetColormap\fR with the original window's -name as \fIstring\fR. - -.SH KEYWORDS -colormap diff --git a/tcl/doc/GetColor.3 b/tcl/doc/GetColor.3 deleted file mode 100644 index cd67e41ec0..0000000000 --- a/tcl/doc/GetColor.3 +++ /dev/null @@ -1,190 +0,0 @@ -'\" -'\" 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$ -'\" -.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 \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 -CONST 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 diff --git a/tcl/doc/GetCursor.3 b/tcl/doc/GetCursor.3 deleted file mode 100644 index ab1d103fa8..0000000000 --- a/tcl/doc/GetCursor.3 +++ /dev/null @@ -1,246 +0,0 @@ -'\" -'\" 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$ -'\" -.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 \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 -CONST 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 "CONST char" *source in -Data for cursor cursor, in standard cursor format. -.AP "CONST 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. -.TP -\fB@\fIsourceName\fR -This form only works on Windows, and will load a Windows system -cursor (\fB.ani\fR or \fB.cur\fR) from the file specified in -\fIsourceName\fR. -.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 diff --git a/tcl/doc/GetDash.3 b/tcl/doc/GetDash.3 deleted file mode 100644 index c9cc357f19..0000000000 --- a/tcl/doc/GetDash.3 +++ /dev/null @@ -1,70 +0,0 @@ -'\" -'\" Copyright (c) 1989-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$ -'\" -.so man.macros -.TH Tk_GetDash 3 8.3 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_GetDash \- convert from string to valid dash structure. -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -int -\fBTk_GetDash\fR(\fIinterp, string, dashPtr\fR) -.SH ARGUMENTS -.AS Tk_Dash *dashPtr -.AP Tcl_Interp *interp in -Interpreter to use for error reporting. -.AP "CONST char *" string in -Textual value to be converted. -.AP Tk_Dash *dashPtr out -Points to place to store the dash pattern -value converted from \fIstring\fR. -.BE - -.SH DESCRIPTION -.PP -These procedure parses the string and fills in the result in the -Tk_Dash structure. The string can be a list of integers or a -character string containing only \fB[.,-_]\fR or spaces. If all -goes well, TCL_OK is returned. If \fIstring\fR doesn't have the -proper syntax then TCL_ERROR is returned, an error message is left -in the interpreter's result, and nothing is stored at *\fIdashPtr\fR. -.PP -The first possible syntax is a list of integers. Each element -represents the number of pixels of a line segment. Only the odd -segments are drawn using the "outline" color. The other segments -are drawn transparent. -.PP -The second possible syntax is a character list containing only -5 possible characters \fB[.,-_ ]\fR. The space can be used -to enlarge the space between other line elements, and can not -occur as the first posibion in the string. Some examples: - -dash . = -dash {2 4} - -dash - = -dash {6 4} - -dash -. = -dash {6 4 2 4} - -dash -.. = -dash {6 4 2 4 2 4} - -dash {. } = -dash {2 8} - -dash , = -dash {4 4} -.PP -The main difference of this syntax with the previous is that it -it shape-conserving. This means that all values in the dash -list will be multiplied by the line width before display. This -assures that "." will always be displayed as a dot and "-" -always as a dash regardless of the line width. -.PP -On systems where only a limited set of dash patterns, the dash -pattern will be displayed as the most close dash pattern that -is available. For example, on Windows only the first 4 of the -above examples are available. The last 2 examples will be -displayed identically as the first one. - -.SH KEYWORDS -dash, conversion diff --git a/tcl/doc/GetFont.3 b/tcl/doc/GetFont.3 deleted file mode 100644 index 259b8fa1f8..0000000000 --- a/tcl/doc/GetFont.3 +++ /dev/null @@ -1,125 +0,0 @@ -'\" -'\" 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$ -'\" -.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 \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 -CONST 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_GetFontMetrics\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 "SEE ALSO" -Tk_FontId(3) - -.SH KEYWORDS -font diff --git a/tcl/doc/GetGC.3 b/tcl/doc/GetGC.3 deleted file mode 100644 index 53e120663c..0000000000 --- a/tcl/doc/GetGC.3 +++ /dev/null @@ -1,74 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_GetGC 3 "" Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_GetGC, Tk_FreeGC \- maintain database of read-only graphics contexts -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -GC -\fBTk_GetGC\fR(\fItkwin, valueMask, valuePtr\fR) -.sp -\fBTk_FreeGC(\fIdisplay, gc\fR) -.SH ARGUMENTS -.AS "unsigned long" valueMask -.AP Tk_Window tkwin in -Token for window in which the graphics context will be used. -.AP "unsigned long" valueMask in -Mask of bits (such as \fBGCForeground\fR or \fBGCStipple\fR) -indicating which fields of \fI*valuePtr\fR are valid. -.AP XGCValues *valuePtr in -Pointer to structure describing the desired values for the -graphics context. -.AP Display *display in -Display for which \fIgc\fR was allocated. -.AP GC gc in -X identifier for graphics context that is no longer needed. -Must have been allocated by \fBTk_GetGC\fR. -.BE - -.SH DESCRIPTION -.PP -\fBTk_GetGC\fR and \fBTk_FreeGC\fR manage a collection of graphics contexts -being used by an application. The procedures allow graphics contexts to be -shared, thereby avoiding the server overhead that would be incurred -if a separate GC were created for each use. \fBTk_GetGC\fR takes arguments -describing the desired graphics context and returns an X identifier -for a GC that fits the description. The graphics context that is returned -will have default values in all of the fields not specified explicitly -by \fIvalueMask\fR and \fIvaluePtr\fR. -.PP -\fBTk_GetGC\fR maintains a -database of all the graphics contexts it has created. Whenever possible, -a call to \fBTk_GetGC\fR will -return an existing graphics context rather than creating a new one. This -approach can substantially reduce server overhead, so \fBTk_GetGC\fR -should generally be used in preference to the Xlib procedure -\fBXCreateGC\fR, which creates a new graphics context on each call. -.PP -Since the return values of \fBTk_GetGC\fR -are shared, callers should never modify the graphics contexts -returned by \fBTk_GetGC\fR. -If a graphics context must be modified dynamically, then it should be -created by calling \fBXCreateGC\fR instead of \fBTk_GetGC\fR. -.PP -When a graphics context -is no longer needed, \fBTk_FreeGC\fR should be called to release it. -There should be exactly one call to \fBTk_FreeGC\fR for -each call to \fBTk_GetGC\fR. -When a graphics context is no longer in use anywhere (i.e. it has -been freed as many times as it has been gotten) \fBTk_FreeGC\fR -will release it to the X server and delete it from the database. - -.SH KEYWORDS -graphics context diff --git a/tcl/doc/GetHINSTANCE.3 b/tcl/doc/GetHINSTANCE.3 deleted file mode 100644 index 587ce151c0..0000000000 --- a/tcl/doc/GetHINSTANCE.3 +++ /dev/null @@ -1,25 +0,0 @@ -'\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. -'\" All rights reserved. -'\" -'\" RCS: @(#) $Id$ -'\" -.so man.macros -.TH Tk_GetHISTANCE 3 "" Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_GetHINSTANCE \- retrieve the global application instance handle -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -HINSTANCE -\fBTk_GetHINSTANCE\fR() - -.SH DESCRIPTION -.PP -\fBTk_GetHINSTANCE\fR returns the Windows application instance handle -for the Tk application. This function is only available on Windows platforms. - -.SH KEYWORDS -identifier, instance diff --git a/tcl/doc/GetHWND.3 b/tcl/doc/GetHWND.3 deleted file mode 100644 index 5ed1b22ca4..0000000000 --- a/tcl/doc/GetHWND.3 +++ /dev/null @@ -1,29 +0,0 @@ -'\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. -'\" All rights reserved. -'\" -'\" RCS: @(#) $Id$ -'\" -'\" -.so man.macros -.TH Tk_GetHWND 3 "" Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_GetHWND \- retrieve the Windows handle for an X window -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -HWND -\fBTk_GetHWND\fR(\fIwindow\fR) -.SH ARGUMENTS -.AP Window window in -X token for window. -.BE -.SH DESCRIPTION -.PP -\fBTk_GetHWND\fR returns the Windows HWND identifier for X Windows -window given by \fIwindow\fR. - -.SH KEYWORDS -identifier, window diff --git a/tcl/doc/GetImage.3 b/tcl/doc/GetImage.3 deleted file mode 100644 index da3f751d2f..0000000000 --- a/tcl/doc/GetImage.3 +++ /dev/null @@ -1,135 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_GetImage 3 4.0 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_GetImage, Tk_RedrawImage, Tk_SizeOfImage, Tk_FreeImage \- use an image in a widget -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -Tk_Image -\fBTk_GetImage\fR(\fIinterp, tkwin, name, changeProc, clientData\fR) -.sp -\fBTk_RedrawImage\fR(\fIimage, imageX, imageY, width, height, drawable, drawableX, drawableY\fR) -.sp -\fBTk_SizeOfImage\fR(\fIimage, widthPtr, heightPtr\fR) -.sp -\fBTk_FreeImage\fR(\fIimage\fR) -.SH ARGUMENTS -.AS Tk_ImageChangedProc *changeProc -.AP Tcl_Interp *interp in -Place to leave error message. -.AP Tk_Window tkwin in -Window in which image will be used. -.AP "CONST char" *name in -Name of image. -.AP Tk_ImageChangedProc *changeProc in -Procedure for Tk to invoke whenever image content or size changes. -.AP ClientData clientData in -One-word value for Tk to pass to \fIchangeProc\fR. -.AP Tk_Image image in -Token for image instance; must have been returned by a previous -call to \fBTk_GetImage\fR. -.AP int imageX in -X-coordinate of upper-left corner of region of image to redisplay -(measured in pixels from the image's upper-left corner). -.AP int imageY in -Y-coordinate of upper-left corner of region of image to redisplay -(measured in pixels from the image's upper-left corner). -.AP "int" width (in) -Width of region of image to redisplay. -.AP "int" height (in) -Height of region of image to redisplay. -.AP Drawable drawable in -Where to display image. Must either be window specified to -\fBTk_GetImage\fR or a pixmap compatible with that window. -.AP int drawableX in -Where to display image in \fIdrawable\fR: this is the x-coordinate -in \fIdrawable\fR where x-coordinate \fIimageX\fR of the image -should be displayed. -.AP int drawableY in -Where to display image in \fIdrawable\fR: this is the y-coordinate -in \fIdrawable\fR where y-coordinate \fIimageY\fR of the image -should be displayed. -.AP "int" widthPtr out -Store width of \fIimage\fR (in pixels) here. -.AP "int" heightPtr out -Store height of \fIimage\fR (in pixels) here. -.BE - -.SH DESCRIPTION -.PP -These procedures are invoked by widgets that wish to display images. -\fBTk_GetImage\fR is invoked by a widget when it first decides to -display an image. -\fIname\fR gives the name of the desired image and \fItkwin\fR -identifies the window where the image will be displayed. -\fBTk_GetImage\fR looks up the image in the table of existing -images and returns a token for a new instance of the image. -If the image doesn't exist then \fBTk_GetImage\fR returns NULL -and leaves an error message in \fIinterp->result\fR. -.PP -When a widget wishes to actually display an image it must -call \fBTk_RedrawImage\fR, identifying the image (\fIimage\fR), -a region within the image to redisplay (\fIimageX\fR, \fIimageY\fR, -\fIwidth\fR, and \fIheight\fR), and a place to display the -image (\fIdrawable\fR, \fIdrawableX\fR, and \fIdrawableY\fR). -Tk will then invoke the appropriate image manager, which will -display the requested portion of the image before returning. -.PP -A widget can find out the dimensions of an image by calling -\fBTk_SizeOfImage\fR: the width and height will be stored -in the locations given by \fIwidthPtr\fR and \fIheightPtr\fR, -respectively. -.PP -When a widget is finished with an image (e.g., the widget is -being deleted or it is going to use a different image instead -of the current one), it must call \fBTk_FreeImage\fR to -release the image instance. -The widget should never again use the image token after passing -it to \fBTk_FreeImage\fR. -There must be exactly one call to \fBTk_FreeImage\fR for each -call to \fBTk_GetImage\fR. -.PP -If the contents or size of an image changes, then any widgets -using the image will need to find out about the changes so that -they can redisplay themselves. -The \fIchangeProc\fR and \fIclientData\fR arguments to -\fBTk_GetImage\fR are used for this purpose. -\fIchangeProc\fR will be called by Tk whenever a change occurs -in the image; it must match the following prototype: -.CS -typedef void Tk_ImageChangedProc( - ClientData \fIclientData\fR, - int \fIx\fR, - int \fIy\fR, - int \fIwidth\fR, - int \fIheight\fR, - int \fIimageWidth\fR, - int \fIimageHeight\fR); -.CE -The \fIclientData\fR argument to \fIchangeProc\fR is the same as the -\fIclientData\fR argument to \fBTk_GetImage\fR. -It is usually a pointer to the widget record for the widget or -some other data structure managed by the widget. -The arguments \fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR -identify a region within the image that must be redisplayed; -they are specified in pixels measured from the upper-left -corner of the image. -The arguments \fIimageWidth\fR and \fIimageHeight\fR give -the image's (new) size. - -.SH "SEE ALSO" -Tk_CreateImageType - -.SH KEYWORDS -images, redisplay diff --git a/tcl/doc/GetJoinStl.3 b/tcl/doc/GetJoinStl.3 deleted file mode 100644 index 44f6777cd5..0000000000 --- a/tcl/doc/GetJoinStl.3 +++ /dev/null @@ -1,62 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_GetJoinStyle 3 "" Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_GetJoinStyle, Tk_NameOfJoinStyle \- translate between strings and join styles -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -int -\fBTk_GetJoinStyle(\fIinterp, string, joinPtr\fB)\fR -.sp -CONST char * -\fBTk_NameOfJoinStyle(\fIjoin\fB)\fR -.SH ARGUMENTS -.AS "Tcl_Interp" *joinPtr -.AP Tcl_Interp *interp in -Interpreter to use for error reporting. -.AP "CONST char" *string in -String containing name of join style: one of ``bevel'', ``miter'', -or ``round''. -.AP int *joinPtr out -Pointer to location in which to store X join style corresponding to -\fIstring\fR. -.AP int join in -Join style: one of \fBJoinBevel\fR, \fBJoinMiter\fR, \fBJoinRound\fR. -.BE - -.SH DESCRIPTION -.PP -\fBTk_GetJoinStyle\fR places in \fI*joinPtr\fR the X join style -corresponding to \fIstring\fR, which will be one of -\fBJoinBevel\fR, \fBJoinMiter\fR, or \fBJoinRound\fR. -Join styles are typically used in X graphics contexts to indicate -how adjacent line segments should be joined together. -See the X documentation for information on what each style -implies. -.PP -Under normal circumstances the return value is \fBTCL_OK\fR and -\fIinterp\fR is unused. -If \fIstring\fR doesn't contain a valid join style -or an abbreviation of one of these names, then an error message is -stored in \fIinterp->result\fR, \fBTCL_ERROR\fR is returned, and -\fI*joinPtr\fR is unmodified. -.PP -\fBTk_NameOfJoinStyle\fR is the logical inverse of \fBTk_GetJoinStyle\fR. -Given a join style such as \fBJoinBevel\fR it returns a -statically-allocated string corresponding to \fIjoin\fR. -If \fIjoin\fR isn't a legal join style, then -``unknown join style'' is returned. - -.SH KEYWORDS -bevel, join style, miter, round diff --git a/tcl/doc/GetJustify.3 b/tcl/doc/GetJustify.3 deleted file mode 100644 index 3604c3e028..0000000000 --- a/tcl/doc/GetJustify.3 +++ /dev/null @@ -1,93 +0,0 @@ -'\" -'\" 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$ -'\" -.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 \fR -.sp -.VS 8.1 -int -\fBTk_GetJustifyFromObj(\fIinterp, objPtr, justifyPtr\fB)\fR -.sp -int -\fBTk_GetJustify(\fIinterp, string, justifyPtr\fB)\fR -.sp -CONST 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 "CONST 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. - -.SH KEYWORDS -center, fill, justification, string diff --git a/tcl/doc/GetOption.3 b/tcl/doc/GetOption.3 deleted file mode 100644 index 775d59215c..0000000000 --- a/tcl/doc/GetOption.3 +++ /dev/null @@ -1,46 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_GetOption 3 "" Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_GetOption \- retrieve an option from the option database -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -Tk_Uid -\fBTk_GetOption\fR(\fItkwin, name, class\fR) -.SH ARGUMENTS -.AS Tk_Window *class -.AP Tk_Window tkwin in -Token for window. -.AP "CONST char" *name in -Name of desired option. -.AP "CONST char" *class in -Class of desired option. Null means there is no class for -this option; do lookup based on name only. -.BE - -.SH DESCRIPTION -.PP -This procedure is invoked to retrieve an option from the database -associated with \fItkwin\fR's main window. If there is an option -for \fItkwin\fR that matches the given \fIname\fR or \fIclass\fR, -then it is returned in the form of a Tk_Uid. If multiple options -match \fIname\fR and \fIclass\fR, then the highest-priority one -is returned. If no option matches, then NULL is returned. -.PP -\fBTk_GetOption\fR caches options related to \fItkwin\fR so that -successive calls for the same \fItkwin\fR will execute much more -quickly than successive calls for different windows. - -.SH KEYWORDS -class, name, option, retrieve diff --git a/tcl/doc/GetPixels.3 b/tcl/doc/GetPixels.3 deleted file mode 100644 index 6ec9f57ac7..0000000000 --- a/tcl/doc/GetPixels.3 +++ /dev/null @@ -1,111 +0,0 @@ -'\" -'\" 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$ -'\" -.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 \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 "CONST 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 - -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 diff --git a/tcl/doc/GetPixmap.3 b/tcl/doc/GetPixmap.3 deleted file mode 100644 index 777ba33e48..0000000000 --- a/tcl/doc/GetPixmap.3 +++ /dev/null @@ -1,56 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_GetPixmap 3 4.0 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_GetPixmap, Tk_FreePixmap \- allocate and free pixmaps -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -Pixmap -\fBTk_GetPixmap(\fIdisplay, d, width, height, depth\fB)\fR -.sp -\fBTk_FreePixmap(\fIdisplay, pixmap\fB)\fR -.SH ARGUMENTS -.AS "Drawable" *pixelPtr -.AP Display *display in -X display for the pixmap. -.AP Drawable d in -Pixmap or window where the new pixmap will be used for drawing. -.AP "int" width in -Width of pixmap. -.AP "int" height in -Height of pixmap. -.AP "int" depth in -Number of bits per pixel in pixmap. -.AP Pixmap pixmap in -Pixmap to destroy. -.BE - -.SH DESCRIPTION -.PP -These procedures are identical to the Xlib procedures \fBXCreatePixmap\fR -and \fBXFreePixmap\fR, except that they have extra code to manage X -resource identifiers so that identifiers for deleted pixmaps can be -reused in the future. -It is important for Tk applications to use these procedures rather -than \fBXCreatePixmap\fR and \fBXFreePixmap\fR; otherwise long-running -applications may run out of resource identifiers. -.PP -\fBTk_GetPixmap\fR creates a pixmap suitable for drawing in \fId\fR, -with dimensions given by \fIwidth\fR, \fIheight\fR, and \fIdepth\fR, -and returns its identifier. -\fBTk_FreePixmap\fR destroys the pixmap given by \fIpixmap\fR and makes -its resource identifier available for reuse. - -.SH KEYWORDS -pixmap, resource identifier diff --git a/tcl/doc/GetRelief.3 b/tcl/doc/GetRelief.3 deleted file mode 100644 index 28532e6fe4..0000000000 --- a/tcl/doc/GetRelief.3 +++ /dev/null @@ -1,83 +0,0 @@ -'\" -'\" 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$ -'\" -.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 \fR -.sp -.VS 8.1 -int -\fBTk_GetReliefFromObj(\fIinterp, objPtr, reliefPtr\fB)\fR -.VE -.sp -int -\fBTk_GetRelief(\fIinterp, name, reliefPtr\fB)\fR -.sp -CONST 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 "CONST char" *name -Name of the relief. -.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 diff --git a/tcl/doc/GetRootCrd.3 b/tcl/doc/GetRootCrd.3 deleted file mode 100644 index 9726a382b5..0000000000 --- a/tcl/doc/GetRootCrd.3 +++ /dev/null @@ -1,43 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_GetRootCoords 3 "" Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_GetRootCoords \- Compute root-window coordinates of window -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -\fBTk_GetRootCoords\fR(\fItkwin, xPtr, yPtr\fR) -.SH ARGUMENTS -.AS Tk_Window tkwin -.AP Tk_Window tkwin in -Token for window. -.AP int *xPtr out -Pointer to location in which to store root-window x-coordinate -corresponding to left edge of \fItkwin\fR's border. -.AP int *yPtr out -Pointer to location in which to store root-window y-coordinate -corresponding to top edge of \fItkwin\fR's border. -.BE - -.SH DESCRIPTION -.PP -This procedure scans through the structural information maintained -by Tk to compute the root-window coordinates corresponding to -the upper-left corner of \fItkwin\fR's border. If \fItkwin\fR has -no border, then \fBTk_GetRootCoords\fR returns the root-window -coordinates corresponding to location (0,0) in \fItkwin\fR. -\fBTk_GetRootCoords\fR is relatively efficient, since it doesn't have to -communicate with the X server. - -.SH KEYWORDS -coordinates, root window diff --git a/tcl/doc/GetScroll.3 b/tcl/doc/GetScroll.3 deleted file mode 100644 index 985d2c1bab..0000000000 --- a/tcl/doc/GetScroll.3 +++ /dev/null @@ -1,78 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_GetScrollInfo 3 8.0 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_GetScrollInfo, Tk_GetScrollInfoObj \- parse arguments for scrolling commands -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -int -\fBTk_GetScrollInfo(\fIinterp, argc, argv, dblPtr, intPtr\fB)\fR -.sp -int -\fBTk_GetScrollInfoObj(\fIinterp, objc, objv, dblPtr, intPtr\fB)\fR -.SH ARGUMENTS -.AS "Tcl_Interp" *dblPtr -.AP Tcl_Interp *interp in -Interpreter to use for error reporting. -.AP int argc in -Number of strings in \fIargv\fR array. -.AP "CONST char" *argv[] in -Argument strings. These represent the entire widget command, of -which the first word is typically the widget name and the second -word is typically \fBxview\fR or \fByview\fR. -.AP int objc in -Number of Tcl_Obj's in \fIobjv\fR array. -.AP "Tcl_Obj *CONST" objv[] in -Argument objects. These represent the entire widget command, of -which the first word is typically the widget name and the second -word is typically \fBxview\fR or \fByview\fR. -.AP double *dblPtr out -Filled in with fraction from \fBmoveto\fR option, if any. -.AP int *intPtr out -Filled in with line or page count from \fBscroll\fR option, if any. -The value may be negative. -.BE - -.SH DESCRIPTION -.PP -\fBTk_GetScrollInfo\fR parses the arguments expected by widget -scrolling commands such as \fBxview\fR and \fByview\fR. -It receives the entire list of words that make up a widget command -and parses the words starting with \fIargv\fR[2]. -The words starting with \fIargv\fR[2] must have one of the following forms: -.CS -\fBmoveto \fIfraction\fR -\fBscroll \fInumber\fB units\fR -\fBscroll \fInumber\fB pages\fR -.CE -.LP -Any of the \fBmoveto\fR, \fBscroll\fR, \fBunits\fR, and \fBpages\fR -keywords may be abbreviated. -If \fIargv\fR has the \fBmoveto\fR form, \fBTK_SCROLL_MOVETO\fR -is returned as result and \fI*dblPtr\fR is filled in with the -\fIfraction\fR argument to the command, which must be a proper real -value. -If \fIargv\fR has the \fBscroll\fR form, \fBTK_SCROLL_UNITS\fR -or \fBTK_SCROLL_PAGES\fR is returned and \fI*intPtr\fR is filled -in with the \fInumber\fR value, which must be a proper integer. -If an error occurs in parsing the arguments, \fBTK_SCROLL_ERROR\fR -is returned and an error message is left in \fIinterp->result\fR. -.PP -\fBTk_GetScrollInfoObj\fR is identical in function to -\fBTk_GetScrollInfo\fR. However, \fBTk_GetScrollInfoObj\fR accepts -Tcl_Obj style arguments, making it more appropriate for use with new -development. - -.SH KEYWORDS -parse, scrollbar, scrolling command, xview, yview diff --git a/tcl/doc/GetSelect.3 b/tcl/doc/GetSelect.3 deleted file mode 100644 index 92c03eb6f1..0000000000 --- a/tcl/doc/GetSelect.3 +++ /dev/null @@ -1,79 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_GetSelection 3 4.0 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_GetSelection \- retrieve the contents of a selection -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -int -\fBTk_GetSelection\fR(\fIinterp, tkwin, selection, target, proc, clientData\fR) -.SH ARGUMENTS -.AS Tk_GetSelProc clientData -.AP Tcl_Interp *interp in -Interpreter to use for reporting errors. -.AP Tk_Window tkwin in -Window on whose behalf to retrieve the selection (determines -display from which to retrieve). -.AP Atom selection in -The name of the selection to be retrieved. -.AP Atom target in -Form in which to retrieve selection. -.AP Tk_GetSelProc *proc in -Procedure to invoke to process pieces of the selection as they -are retrieved. -.AP ClientData clientData in -Arbitrary one-word value to pass to \fIproc\fR. -.BE - -.SH DESCRIPTION -.PP -\fBTk_GetSelection\fR retrieves the selection specified by the atom -\fIselection\fR in the format specified by \fItarget\fR. The -selection may actually be retrieved in several pieces; as each piece -is retrieved, \fIproc\fR is called to process the piece. \fIProc\fR -should have arguments and result that match the type -\fBTk_GetSelProc\fR: -.CS -typedef int Tk_GetSelProc( - ClientData \fIclientData\fR, - Tcl_Interp *\fIinterp\fR, - char *\fIportion\fR); -.CE -The \fIclientData\fR and \fIinterp\fR parameters to \fIproc\fR -will be copies of the corresponding arguments to -\fBTk_GetSelection\fR. \fIPortion\fR will be a pointer to -a string containing part or all of the selection. For large -selections, \fIproc\fR will be called several times with successive -portions of the selection. The X Inter-Client Communication -Conventions Manual allows a selection to be returned in formats -other than strings, e.g. as an array of atoms or integers. If -this happens, Tk converts the selection back into a string -before calling \fIproc\fR. If a selection is returned as an -array of atoms, Tk converts it to a string containing the atom names -separated by white space. For any other format besides string, -Tk converts a selection to a string containing hexadecimal -values separated by white space. -.PP -\fBTk_GetSelection\fR returns to its caller when the selection has -been completely retrieved and processed by \fIproc\fR, or when a -fatal error has occurred (e.g. the selection owner didn't respond -promptly). \fBTk_GetSelection\fR normally returns TCL_OK; if -an error occurs, it returns TCL_ERROR and leaves an error message -in \fIinterp->result\fR. \fIProc\fR should also return either -TCL_OK or TCL_ERROR. If \fIproc\fR encounters an error in dealing with the -selection, it should leave an error message in \fIinterp->result\fR -and return TCL_ERROR; this will abort the selection retrieval. - -.SH KEYWORDS -format, get, selection retrieval diff --git a/tcl/doc/GetUid.3 b/tcl/doc/GetUid.3 deleted file mode 100644 index 77e896771d..0000000000 --- a/tcl/doc/GetUid.3 +++ /dev/null @@ -1,50 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_GetUid 3 "" Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_GetUid, Tk_Uid \- convert from string to unique identifier -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -\fB#typedef char *Tk_Uid\fR -.sp -Tk_Uid -\fBTk_GetUid\fR(\fIstring\fR) -.SH ARGUMENTS -.AP char *string in -String for which the corresponding unique identifier is -desired. -.BE - -.SH DESCRIPTION -.PP -\fBTk_GetUid\fR returns the unique identifier corresponding -to \fIstring\fR. -Unique identifiers are similar to atoms in Lisp, and are used -in Tk to speed up comparisons and -searches. A unique identifier (type Tk_Uid) is a string pointer -and may be used anywhere that a variable of type ``char *'' -could be used. However, there is guaranteed to be exactly -one unique identifier for any given string value. If \fBTk_GetUid\fR -is called twice, once with string \fIa\fR and once with string -\fIb\fR, and if \fIa\fR and \fIb\fR have the same string value -(strcmp(a, b) == 0), then \fBTk_GetUid\fR will return exactly -the same Tk_Uid value for each call (Tk_GetUid(a) == Tk_GetUid(b)). -This means that variables of type -Tk_Uid may be compared directly (x == y) without having to call -\fBstrcmp\fR. -In addition, the return value from \fBTk_GetUid\fR will have the -same string value as its argument (strcmp(Tk_GetUid(a), a) == 0). - -.SH KEYWORDS -atom, unique identifier diff --git a/tcl/doc/GetVRoot.3 b/tcl/doc/GetVRoot.3 deleted file mode 100644 index 9cf7d1bd0f..0000000000 --- a/tcl/doc/GetVRoot.3 +++ /dev/null @@ -1,49 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_GetVRootGeometry 3 4.0 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_GetVRootGeometry \- Get location and size of virtual root for window -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -\fBTk_GetVRootGeometry(\fItkwin, xPtr, yPtr, widthPtr, heightPtr\fB)\fR -.SH ARGUMENTS -.AS Tk_Window heightPtr -.AP Tk_Window tkwin in -Token for window whose virtual root is to be queried. -.AP int xPtr out -Points to word in which to store x-offset of virtual root. -.AP int yPtr out -Points to word in which to store y-offset of virtual root. -.AP "int" widthPtr out -Points to word in which to store width of virtual root. -.AP "int" heightPtr out -Points to word in which to store height of virtual root. -.BE - -.SH DESCRIPTION -.PP -\fBTkGetVRootGeometry\fR returns geometry information about the virtual -root window associated with \fItkwin\fR. The ``associated'' virtual -root is the one in which \fItkwin\fR's nearest top-level ancestor (or -\fItkwin\fR itself if it is a top-level window) has -been reparented by the window manager. This window is identified by -a \fB__SWM_ROOT\fR or \fB__WM_ROOT\fR property placed on the top-level -window by the window manager. -If \fItkwin\fR is not associated with a virtual root (e.g. -because the window manager doesn't use virtual roots) then *\fIxPtr\fR and -*\fIyPtr\fR will be set to 0 and *\fIwidthPtr\fR and *\fIheightPtr\fR -will be set to the dimensions of the screen containing \fItkwin\fR. - -.SH KEYWORDS -geometry, height, location, virtual root, width, window manager diff --git a/tcl/doc/GetVisual.3 b/tcl/doc/GetVisual.3 deleted file mode 100644 index 943dad7559..0000000000 --- a/tcl/doc/GetVisual.3 +++ /dev/null @@ -1,98 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_GetVisual 3 4.0 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_GetVisual \- translate from string to visual -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -Visual * -\fBTk_GetVisual(\fIinterp, tkwin, string, depthPtr, colormapPtr\fB)\fR -.SH ARGUMENTS -.AS "Tcl_Interp" *colormapPtr -.AP Tcl_Interp *interp in -Interpreter to use for error reporting. -.AP Tk_Window tkwin in -Token for window in which the visual will be used. -.AP "CONST char" *string in -String that identifies the desired visual. See below for -valid formats. -.AP int *depthPtr out -Depth of returned visual gets stored here. -.AP Colormap *colormapPtr out -If non-NULL then a suitable colormap for visual is found and its -identifier is stored here. -.BE - -.SH DESCRIPTION -.PP -\fBTk_GetVisual\fR takes a string description of a visual and -finds a suitable X Visual for use in \fItkwin\fR, if there is one. -It returns a pointer to the X Visual structure for the visual -and stores the number of bits per pixel for it at \fI*depthPtr\fR. -If \fIstring\fR is unrecognizable or if no suitable visual could -be found, then NULL is returned and \fBTk_GetVisual\fR leaves -an error message in \fIinterp->result\fR. -If \fIcolormap\fR is non-NULL then \fBTk_GetVisual\fR -also locates an appropriate colormap for use with the result visual -and stores its X identifier at \fI*colormapPtr\fR. -.PP -The \fIstring\fR argument specifies the desired visual in one -of the following ways: -.TP 15 -\fIclass depth\fR -The string consists of a class name followed by an integer depth, -with any amount of white space (including none) in between. -\fIclass\fR selects what sort of visual is desired and must be one of -\fBdirectcolor\fR, \fBgrayscale\fR, \fBgreyscale\fR, \fBpseudocolor\fR, -\fBstaticcolor\fR, \fBstaticgray\fR, \fBstaticgrey\fR, or -\fBtruecolor\fR, or a unique abbreviation. -\fIdepth\fR specifies how many bits per pixel are needed for the -visual. -If possible, \fBTk_GetVisual\fR will return a visual with this depth; -if there is no visual of the desired depth then \fBTk_GetVisual\fR -looks first for a visual with greater depth, then one with less -depth. -.TP 15 -\fBdefault\fR -Use the default visual for \fItkwin\fR's screen. -.TP 15 -\fIpathName\fR -Use the visual for the window given by \fIpathName\fR. -\fIpathName\fR must be the name of a window on the same screen -as \fItkwin\fR. -.TP 15 -\fInumber\fR -Use the visual whose X identifier is \fInumber\fR. -.TP 15 -\fBbest\fR ?\fIdepth\fR? -Choose the ``best possible'' visual, using the following rules, in -decreasing order of priority: -(a) a visual that has exactly the desired depth is best, followed -by a visual with greater depth than requested (but as little extra -as possible), followed by a visual with less depth than requested -(but as great a depth as possible); -(b) if no \fIdepth\fR is specified, then the deepest available visual -is chosen; -(c) \fBpseudocolor\fR is better than \fBtruecolor\fR or \fBdirectcolor\fR, -which are better than \fBstaticcolor\fR, which is better than -\fBstaticgray\fR or \fBgrayscale\fR; -(d) the default visual for the screen is better than any other visual. - -.SH CREDITS -.PP -The idea for \fBTk_GetVisual\fR, and the first implementation, came -from Paul Mackerras. - -.SH KEYWORDS -colormap, screen, visual diff --git a/tcl/doc/Grab.3 b/tcl/doc/Grab.3 deleted file mode 100644 index d9ea162be7..0000000000 --- a/tcl/doc/Grab.3 +++ /dev/null @@ -1,65 +0,0 @@ -'\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. -'\" All rights reserved. -'\" -'\" RCS: @(#) $Id$ -'\" -.so man.macros -.TH Tk_Grab 3 "" Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_Grab, Tk_Ungrab \- manipulate grab state in an application -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -int -\fBTk_Grab\fR(\fIinterp, tkwin, grabGlobal\fR) -.sp -void -\fBTk_Ungrab\fR(\fItkwin\fR) - -.SH ARGUMENTS -.AP Tcl_Interp *interp in -Interpreter to use for error reporting -.AP Tk_Window tkwin in -Window on whose behalf the pointer is to be grabbed or released -.AP int grabGlobal in -Boolean indicating whether the grab is global or application local -.BE - -.SH DESCRIPTION -.PP -These functions are used to set or release a global or -application local grab. When a grab is set on a particular window -in a Tk application, mouse and keyboard events can only be received by -that window and its descendants. Mouse and keyboard events for -windows outside the tree rooted at \fItkwin\fR will be redirected to -\fItkwin\fR. If the grab is global, then all mouse and keyboard -events for windows outside the tree rooted at \fItkwin\fR (even those -intended for windows in other applications) will be redirected to -\fItkwin\fR. If the grab is application local, only mouse and -keyboard events intended for a windows within the same application -(but outside the tree rooted at \fItkwin\fR) will be redirected. - -.PP -\fBTk_Grab\fR sets a grab on a particular window. \fITkwin\fR -specifies the window on whose behalf the pointer is to be grabbed. -\fIGrabGlobal\fR indicates whether the grab should be global or -application local; if it is non-zero, it means the grab should be -global. Normally, \fBTk_Grab\fR returns TCL_OK; if an error occurs -and the grab cannot be set, TCL_ERROR is returned and an error message -is left if \fIinterp\fR's result. Once this call completes -successfully, no window outside the tree rooted at \fItkwin\fR will -receive pointer- or keyboard-related events until the next call to -Tk_Ungrab. If a previous grab was in effect within the application, -then it is replaced with a new one. - -.PP -\fBTcl_Ungrab\fR releases a grab on the mouse pointer and keyboard, if -there is one set on the window given by \fItkwin\fR. Once a grab is -released, pointer and keyboard events will start being delivered to -other windows again. - -.SH KEYWORDS -grab, window diff --git a/tcl/doc/HWNDToWindow.3 b/tcl/doc/HWNDToWindow.3 deleted file mode 100644 index 34baf022a1..0000000000 --- a/tcl/doc/HWNDToWindow.3 +++ /dev/null @@ -1,30 +0,0 @@ -'\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. -'\" All rights reserved. -'\" -'\" RCS: @(#) $Id$ -'\" -.so man.macros -.TH Tk_HWNDToWindow 3 "" Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_HWNDToWindow \- Find Tk's window information for a Windows window -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -Tk_Window -\fBTk_HWNDToWindow\fR(\fIhwnd\fR) -.SH ARGUMENTS -.AP HWND hwnd in -Windows handle for the window. -.BE - -.SH DESCRIPTION -.PP -Given a Windows HWND window identifier, this procedure returns the -corresponding Tk_Window handle. If there is no Tk_Window corresponding -to \fIhwnd\fR then NULL is returned. - -.SH KEYWORDS -Windows window id diff --git a/tcl/doc/HandleEvent.3 b/tcl/doc/HandleEvent.3 deleted file mode 100644 index 26b75278be..0000000000 --- a/tcl/doc/HandleEvent.3 +++ /dev/null @@ -1,49 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_HandleEvent 3 "" Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_HandleEvent \- invoke event handlers for window system events -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -\fBTk_HandleEvent\fR(\fIeventPtr\fR) -.SH ARGUMENTS -.AS XEvent *eventPtr -.AP XEvent *eventPtr in -Pointer to X event to dispatch to relevant handler(s). -.BE - -.SH DESCRIPTION -.PP -\fBTk_HandleEvent\fR is a lower-level procedure that deals with window -events. It is called by \fBTcl_ServiceEvent\fR (and indirectly by -\fBTk_DoOneEvent\fR), and in a few other cases within Tk. -It makes callbacks to any window event -handlers (created by calls to \fBTk_CreateEventHandler\fR) -that match \fIeventPtr\fR and then returns. In some cases -it may be useful for an application to bypass the Tk event -queue and call \fBTk_HandleEvent\fR directly instead of -calling \fBTcl_QueueEvent\fR followed by -\fBTcl_ServiceEvent\fR. -.PP -This procedure may be invoked recursively. For example, -it is possible to invoke \fBTk_HandleEvent\fR recursively -from a handler called by \fBTk_HandleEvent\fR. This sort -of operation is useful in some modal situations, such -as when a -notifier has been popped up and an application wishes to -wait for the user to click a button in the notifier before -doing anything else. - -.SH KEYWORDS -callback, event, handler, window diff --git a/tcl/doc/IdToWindow.3 b/tcl/doc/IdToWindow.3 deleted file mode 100644 index 0755f35bbb..0000000000 --- a/tcl/doc/IdToWindow.3 +++ /dev/null @@ -1,36 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_IdToWindow 3 4.0 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_IdToWindow \- Find Tk's window information for an X window -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -Tk_Window -\fBTk_IdToWindow\fR(\fIdisplay, window\fR) -.SH ARGUMENTS -.AS Tk_Window display -.AP Display *display in -X display containing the window. -.AP Window window in -X id for window. -.BE - -.SH DESCRIPTION -.PP -Given an X window identifier and the X display it corresponds to, -this procedure returns the corresponding Tk_Window handle. -If there is no Tk_Window corresponding to \fIwindow\fR then -NULL is returned. - -.SH KEYWORDS -X window id diff --git a/tcl/doc/ImgChanged.3 b/tcl/doc/ImgChanged.3 deleted file mode 100644 index 7588fb8cc4..0000000000 --- a/tcl/doc/ImgChanged.3 +++ /dev/null @@ -1,69 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_ImageChanged 3 4.0 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_ImageChanged \- notify widgets that image needs to be redrawn -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -\fBTk_ImageChanged\fR(\fIimageMaster, x, y, width, height, imageWidth, imageHeight\fR) -.SH ARGUMENTS -.AS Tk_ImageMaster imageHeight -.AP Tk_ImageMaster imageMaster in -Token for image, which was passed to image's \fIcreateProc\fR when -the image was created. -.AP int x in -X-coordinate of upper-left corner of region that needs redisplay (measured -from upper-left corner of image). -.AP int y in -Y-coordinate of upper-left corner of region that needs redisplay (measured -from upper-left corner of image). -.AP "int" width in -Width of region that needs to be redrawn, in pixels. -.AP "int" height in -Height of region that needs to be redrawn, in pixels. -.AP "int" imageWidth in -Current width of image, in pixels. -.AP "int" imageHeight in -Current height of image, in pixels. -.BE - -.SH DESCRIPTION -.PP -An image manager calls \fBTk_ImageChanged\fR for an image -whenever anything happens that requires the image to be redrawn. -As a result of calling \fBTk_ImageChanged\fR, any widgets using -the image are notified so that they can redisplay themselves -appropriately. -The \fIimageMaster\fR argument identifies the image, and -\fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR -specify a rectangular region within the image that needs to -be redrawn. -\fIimageWidth\fR and \fIimageHeight\fR specify the image's (new) size. -.PP -An image manager should call \fBTk_ImageChanged\fR during -its \fIcreateProc\fR to specify the image's initial size and to -force redisplay if there are existing instances for the image. -If any of the pixel values in the image should change later on, -\fBTk_ImageChanged\fR should be called again with \fIx\fR, \fIy\fR, -\fIwidth\fR, and \fIheight\fR values that cover all the pixels -that changed. -If the size of the image should change, then \fBTk_ImageChanged\fR -must be called to indicate the new size, even if no pixels -need to be redisplayed. - -.SH "SEE ALSO" -Tk_CreateImageType - -.SH KEYWORDS -images, redisplay, image size changes diff --git a/tcl/doc/InternAtom.3 b/tcl/doc/InternAtom.3 deleted file mode 100644 index 6264a265d5..0000000000 --- a/tcl/doc/InternAtom.3 +++ /dev/null @@ -1,58 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_InternAtom 3 "" Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_InternAtom, Tk_GetAtomName \- manage cache of X atoms -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -Atom -\fBTk_InternAtom(\fItkwin, name\fR) -.sp -CONST char * -\fBTk_GetAtomName(\fItkwin, atom\fR) -.SH ARGUMENTS -.AS Tk_Window parent -.AP Tk_Window tkwin in -Token for window. Used to map atom or name relative to a particular display. -.AP "CONST char" *name in -String name for which atom is desired. -.AP Atom atom in -Atom for which corresponding string name is desired. -.BE - -.SH DESCRIPTION -.PP -These procedures are similar to the Xlib procedures -\fBXInternAtom\fR and \fBXGetAtomName\fR. \fBTk_InternAtom\fR -returns the atom identifier associated with string given by -\fIname\fR; the atom identifier is only valid for the display -associated with \fItkwin\fR. -\fBTk_GetAtomName\fR returns the string associated -with \fIatom\fR on \fItkwin\fR's display. The string returned -by \fBTk_GetAtomName\fR is in Tk's storage: the caller need -not free this space when finished with the string, and the caller -should not modify the contents of the returned string. -If there is no atom \fIatom\fR on \fItkwin\fR's display, -then \fBTk_GetAtomName\fR returns the string ``?bad atom?''. -.PP -Tk caches -the information returned by \fBTk_InternAtom\fR and \fBTk_GetAtomName\fR -so that future calls -for the same information can be serviced from the cache without -contacting the server. Thus \fBTk_InternAtom\fR and \fBTk_GetAtomName\fR -are generally much faster than their Xlib counterparts, and they -should be used in place of the Xlib procedures. - -.SH KEYWORDS -atom, cache, display diff --git a/tcl/doc/MainLoop.3 b/tcl/doc/MainLoop.3 deleted file mode 100644 index 2cbe3c9d06..0000000000 --- a/tcl/doc/MainLoop.3 +++ /dev/null @@ -1,32 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_MainLoop 3 "" Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_MainLoop \- loop for events until all windows are deleted -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -\fBTk_MainLoop\fR() -.BE - -.SH DESCRIPTION -.PP -\fBTk_MainLoop\fR is a procedure that loops repeatedly calling -\fBTcl_DoOneEvent\fR. It returns only when there are no applications -left in this process (i.e. no main windows exist anymore). Most -windowing applications will call \fBTk_MainLoop\fR after -initialization; the main execution of the application will consist -entirely of callbacks invoked via \fBTcl_DoOneEvent\fR. - -.SH KEYWORDS -application, event, main loop diff --git a/tcl/doc/MainWin.3 b/tcl/doc/MainWin.3 deleted file mode 100644 index b409509b93..0000000000 --- a/tcl/doc/MainWin.3 +++ /dev/null @@ -1,46 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_MainWindow 3 7.0 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_MainWindow, Tk_GetNumMainWindows \- functions for querying main -window information -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -Tk_Window -\fBTk_MainWindow\fR(\fIinterp\fR) -.sp -int -\fBTk_GetNumMainWindows\fR() - -.SH ARGUMENTS -.AS Tcl_Interp *pathName -.AP Tcl_Interp *interp in/out -Interpreter associated with the application. -.BE - -.SH DESCRIPTION -.PP -A main window is a special kind of toplevel window used as the -outermost window in an application. -.PP -If \fIinterp\fR is associated with a Tk application then \fBTk_MainWindow\fR -returns the application's main window. If there is no Tk application -associated with \fIinterp\fR then \fBTk_MainWindow\fR returns NULL and -leaves an error message in \fIinterp->result\fR. -.PP -\fBTk_GetNumMainWindows\fR returns a count of the number of main -windows currently open in the process. - -.SH KEYWORDS -application, main window diff --git a/tcl/doc/MaintGeom.3 b/tcl/doc/MaintGeom.3 deleted file mode 100644 index 7137973f48..0000000000 --- a/tcl/doc/MaintGeom.3 +++ /dev/null @@ -1,103 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_MaintainGeometry 3 4.0 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_MaintainGeometry, Tk_UnmaintainGeometry \- maintain geometry of one window relative to another -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -\fBTk_MaintainGeometry\fR(\fIslave, master, x, y, width, height\fR) -.sp -\fBTk_UnmaintainGeometry\fR(\fIslave, master\fR) -.SH ARGUMENTS -.AS Tk_Window master -.AP Tk_Window slave in -Window whose geometry is to be controlled. -.AP Tk_Window master in -Window relative to which \fIslave\fR's geometry will be controlled. -.AP int x in -Desired x-coordinate of \fIslave\fR in \fImaster\fR, measured in pixels -from the inside of \fImaster\fR's left border to the outside of -\fIslave\fR's left border. -.AP int y in -Desired y-coordinate of \fIslave\fR in \fImaster\fR, measured in pixels -from the inside of \fImaster\fR's top border to the outside of -\fIslave\fR's top border. -.AP int width in -Desired width for \fIslave\fR, in pixels. -.AP int height in -Desired height for \fIslave\fR, in pixels. -.BE - -.SH DESCRIPTION -.PP -\fBTk_MaintainGeometry\fR and \fBTk_UnmaintainGeometry\fR make it -easier for geometry managers to deal with slaves whose masters are not -their parents. -Three problems arise if the master for a slave is not its parent: -.IP [1] -The x- and y-position of the slave must be translated from the -coordinate system of the master to that of the parent before -positioning the slave. -.IP [2] -If the master window, or any of its ancestors up to the slave's -parent, is moved, then the slave must be repositioned within its -parent in order to maintain the correct position relative to the -master. -.IP [3] -If the master or one of its ancestors is mapped or unmapped, then -the slave must be mapped or unmapped to correspond. -.LP -None of these problems is an issue if the parent and master are -the same. For example, if the master or one of its ancestors -is unmapped, the slave is automatically removed by the screen -by X. -.PP -\fBTk_MaintainGeometry\fR deals with these problems for slaves -whose masters aren't their parents, as well as handling the simpler -case of slaves whose masters are their parents. -\fBTk_MaintainGeometry\fR is typically called by a window manager -once it has decided where a slave should be positioned relative -to its master. -\fBTk_MaintainGeometry\fR translates the coordinates to the -coordinate system of \fIslave\fR's parent and then moves and -resizes the slave appropriately. -Furthermore, it remembers the desired position and creates event -handlers to monitor the master and all of its ancestors up -to (but not including) the slave's parent. -If any of these windows is moved, mapped, or unmapped, -the slave will be adjusted so that it is mapped only when the -master is mapped and its geometry relative to the master -remains as specified by \fIx\fR, \fIy\fR, \fIwidth\fR, and -\fIheight\fR. -.PP -When a window manager relinquishes control over a window, or -if it decides that it does not want the window to appear on the -screen under any conditions, it calls \fBTk_UnmaintainGeometry\fR. -\fBTk_UnmaintainGeometry\fR unmaps the window and cancels any -previous calls to \fBTk_MaintainGeometry\fR for the -\fImaster\fR\-\fIslave\fR pair, so that the slave's -geometry and mapped state are no longer maintained -automatically. -\fBTk_UnmaintainGeometry\fR need not be called by a geometry -manager if the slave, the master, or any of the master's ancestors -is destroyed: Tk will call it automatically. -.PP -If \fBTk_MaintainGeometry\fR is called repeatedly for the same -\fImaster\fR\-\fIslave\fR pair, the information from the most -recent call supersedes any older information. -If \fBTk_UnmaintainGeometry\fR is called for a \fImaster\fR\-\fIslave\fR -pair that is isn't currently managed, the call has no effect. - -.SH KEYWORDS -geometry manager, map, master, parent, position, slave, unmap diff --git a/tcl/doc/ManageGeom.3 b/tcl/doc/ManageGeom.3 deleted file mode 100644 index 50e0c7aa68..0000000000 --- a/tcl/doc/ManageGeom.3 +++ /dev/null @@ -1,94 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_ManageGeometry 3 4.0 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_ManageGeometry \- arrange to handle geometry requests for a window -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -\fBTk_ManageGeometry\fR(\fItkwin, mgrPtr, clientData\fR) -.SH ARGUMENTS -.AS Tk_GeometryProc clientData -.AP Tk_Window tkwin in -Token for window to be managed. -.AP Tk_GeomMgr *mgrPtr in -Pointer to data structure containing information about the -geometry manager, or NULL to indicate that \fItkwin\fR's geometry -shouldn't be managed anymore. -The data structure pointed to by \fImgrPtr\fR must be static: -Tk keeps a reference to it as long as the window is managed. -.AP ClientData clientData in -Arbitrary one-word value to pass to geometry manager callbacks. -.BE - -.SH DESCRIPTION -.PP -\fBTk_ManageGeometry\fR arranges for a particular geometry manager, -described by the \fImgrPtr\fR argument, to control the geometry -of a particular slave window, given by \fItkwin\fR. -If \fItkwin\fR was previously managed by some other geometry manager, -the previous manager loses control in favor of the new one. -If \fImgrPtr\fR is NULL, geometry management is cancelled for -\fItkwin\fR. -.PP -The structure pointed to by \fImgrPtr\fR contains information about -the geometry manager: -.CS -typedef struct { - char *\fIname\fR; - Tk_GeomRequestProc *\fIrequestProc\fR; - Tk_GeomLostSlaveProc *\fIlostSlaveProc\fR; -} Tk_GeomMgr; -.CE -The \fIname\fR field is the textual name for the geometry manager, -such as \fBpack\fR or \fBplace\fR; this value will be returned -by the command \fBwinfo manager\fR. -.PP -\fIrequestProc\fR is a procedure in the geometry manager that -will be invoked whenever \fBTk_GeometryRequest\fR is called by the -slave to change its desired geometry. -\fIrequestProc\fR should have arguments and results that match the -type \fBTk_GeomRequestProc\fR: -.CS -typedef void Tk_GeomRequestProc( - ClientData \fIclientData\fR, - Tk_Window \fItkwin\fR); -.CE -The parameters to \fIrequestProc\fR will be identical to the -corresponding parameters passed to \fBTk_ManageGeometry\fR. -\fIclientData\fR usually points to a data -structure containing application-specific information about -how to manage \fItkwin\fR's geometry. -.PP -The \fIlostSlaveProc\fR field of \fImgrPtr\fR points to another -procedure in the geometry manager. -Tk will invoke \fIlostSlaveProc\fR if some other manager -calls \fBTk_ManageGeometry\fR to claim -\fItkwin\fR away from the current geometry manager. -\fIlostSlaveProc\fR is not invoked if \fBTk_ManageGeometry\fR is -called with a NULL value for \fImgrPtr\fR (presumably the current -geometry manager has made this call, so it already knows that the -window is no longer managed), nor is it called if \fImgrPtr\fR -is the same as the window's current geometry manager. -\fIlostSlaveProc\fR should have -arguments and results that match the following prototype: -.CS -typedef void Tk_GeomLostSlaveProc( - ClientData \fIclientData\fR, - Tk_Window \fItkwin\fR); -.CE -The parameters to \fIlostSlaveProc\fR will be identical to the -corresponding parameters passed to \fBTk_ManageGeometry\fR. - -.SH KEYWORDS -callback, geometry, managed, request, unmanaged diff --git a/tcl/doc/MapWindow.3 b/tcl/doc/MapWindow.3 deleted file mode 100644 index b23cee7a14..0000000000 --- a/tcl/doc/MapWindow.3 +++ /dev/null @@ -1,53 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_MapWindow 3 "" Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_MapWindow, Tk_UnmapWindow \- map or unmap a window -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -Tk_Window -\fBTk_MapWindow\fR(\fItkwin\fR) -.sp -\fBTk_UnmapWindow\fR(\fItkwin\fR) -.SH ARGUMENTS -.AS Tk_Window parent -.AP Tk_Window tkwin in -Token for window. -.BE - -.SH DESCRIPTION -.PP -These procedures may be used to map and unmap windows -managed by Tk. \fBTk_MapWindow\fR maps the window given -by \fItkwin\fR, and also creates an X window corresponding -to \fItkwin\fR if it doesn't already exist. See the -\fBTk_CreateWindow\fR manual entry for information on -deferred window creation. -\fBTk_UnmapWindow\fR unmaps \fItkwin\fR's window -from the screen. -.PP -If \fItkwin\fR is a child window (i.e. \fBTk_CreateWindow\fR was -used to create a child window), then event handlers interested in map -and unmap events are invoked immediately. If \fItkwin\fR isn't an -internal window, then the event handlers will be invoked later, after -X has seen the request and returned an event for it. -.PP -These procedures should be used in place of the X procedures -\fBXMapWindow\fR and \fBXUnmapWindow\fR, since they update -Tk's local data structure for \fItkwin\fR. Applications -using Tk should not invoke \fBXMapWindow\fR and \fBXUnmapWindow\fR -directly. - -.SH KEYWORDS -map, unmap, window diff --git a/tcl/doc/MeasureChar.3 b/tcl/doc/MeasureChar.3 deleted file mode 100644 index 38cbf75415..0000000000 --- a/tcl/doc/MeasureChar.3 +++ /dev/null @@ -1,137 +0,0 @@ -'\" -'\" 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$ -'\" -.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 \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 >= 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 -space in pixels the given \fIstring\fR needs. -.PP -\fBTk_DrawChars\fR draws the \fIstring\fR at the given location in the -given \fIdrawable\fR. -.PP -\fBTk_UnderlineChars\fR underlines the given range of characters in the -given \fIstring\fR. It doesn't draw the characters (which are assumed to -have been displayed previously by \fBTk_DrawChars\fR); it just draws the -underline. This procedure is used to underline a few characters without -having to construct an underlined font. To produce natively underlined -text, the appropriate underlined font should be constructed and used. - -.SH KEYWORDS -font diff --git a/tcl/doc/MoveToplev.3 b/tcl/doc/MoveToplev.3 deleted file mode 100644 index b0b076f4ad..0000000000 --- a/tcl/doc/MoveToplev.3 +++ /dev/null @@ -1,55 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_MoveToplevelWindow 3 "" Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_MoveToplevelWindow \- Adjust the position of a top-level window -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -\fBTk_MoveToplevelWindow(\fItkwin, x, y\fB)\fR -.SH ARGUMENTS -.AS Tk_Window tkwin -.AP Tk_Window tkwin in -Token for top-level window to move. -.AP int x in -New x-coordinate for the top-left pixel of \fItkwin\fR's border, or the -top-left pixel of the decorative border supplied for \fItkwin\fR by the -window manager, if there is one. -.AP int y in -New y-coordinate for the top-left pixel of \fItkwin\fR's border, or the -top-left pixel of the decorative border supplied for \fItkwin\fR by the -window manager, if there is one. -.BE - -.SH DESCRIPTION -.PP -In general, a window should never set its own position; this should be -done only by the geometry manger that is responsible for the window. -For top-level windows the window manager is effectively the geometry -manager; Tk provides interface code between the application and the -window manager to convey the application's desires to the geometry -manager. The desired size for a top-level window is conveyed using -the usual \fBTk_GeometryRequest\fR mechanism. The procedure -\fBTk_MoveToplevelWindow\fR may be used by an application to request -a particular position for a top-level window; this procedure is -similar in function to the \fBwm geometry\fR Tcl command except that -negative offsets cannot be specified. It is invoked by widgets such as -menus that want to appear at a particular place on the screen. -.PP -When \fBTk_MoveToplevelWindow\fR is called it doesn't immediately -pass on the new desired location to the window manager; it defers -this action until all other outstanding work has been completed, -using the \fBTk_DoWhenIdle\fR mechanism. - -.SH KEYWORDS -position, top-level window, window manager diff --git a/tcl/doc/Name.3 b/tcl/doc/Name.3 deleted file mode 100644 index d4a2dbed7b..0000000000 --- a/tcl/doc/Name.3 +++ /dev/null @@ -1,82 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_Name 3 "" Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_Name, Tk_PathName, Tk_NameToWindow \- convert between names and window tokens -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -Tk_Uid -\fBTk_Name\fR(\fItkwin\fR) -.sp -char * -\fBTk_PathName\fR(\fItkwin\fR) -.sp -Tk_Window -\fBTk_NameToWindow\fR(\fIinterp, pathName, tkwin\fR) -.SH ARGUMENTS -.AS Tcl_Interp *pathName -.AP Tk_Window tkwin in -Token for window. -.AP Tcl_Interp *interp out -Interpreter to use for error reporting. -.AP "CONST char" *pathName in -Character string containing path name of window. -.BE - -.SH DESCRIPTION -.PP -Each window managed by Tk has two names, a short name that identifies -a window among children of the same parent, and a path name that -identifies the window uniquely among all the windows belonging to the -same main window. The path name is used more often in Tk than the -short name; many commands, like \fBbind\fR, expect path names as -arguments. -.PP -The \fBTk_Name\fR macro returns a window's -short name, which is the same as the \fIname\fR argument -passed to \fBTk_CreateWindow\fR when -the window was created. The value is returned -as a Tk_Uid, which may be used just like a string pointer but also has -the properties of a unique identifier (see the manual entry for -\fBTk_GetUid\fR for details). -.PP -The \fBTk_PathName\fR macro returns a -hierarchical name for \fItkwin\fR. -Path names have a structure similar to file names in Unix but with -dots between elements instead of slashes: the main window for -an application has the path name ``.''; its children have names like -``.a'' and ``.b''; their children have names like ``.a.aa'' and -``.b.bb''; and so on. A window is considered to be be a child of -another window for naming purposes if the second window was named -as the first window's \fIparent\fR when the first window was created. -This is not always the same as the X window hierarchy. For -example, a pop-up -is created as a child of the root window, but its logical parent will -usually be a window within the application. -.PP -The procedure \fBTk_NameToWindow\fR returns the token for a window -given its path name (the \fIpathName\fR argument) and another window -belonging to the same main window (\fItkwin\fR). It normally -returns a token for the named window, but if no such window exists -\fBTk_NameToWindow\fR leaves an error message in \fIinterp->result\fR -and returns NULL. The \fItkwin\fR argument to \fBTk_NameToWindow\fR -is needed because path names are only unique within a single -application hierarchy. If, for example, a single process has opened -two main windows, each will have a separate naming hierarchy and the -same path name might appear in each of the hierarchies. Normally -\fItkwin\fR is the main window of the desired hierarchy, but this -need not be the case: any window in the desired hierarchy may be used. - -.SH KEYWORDS -name, path name, token, window diff --git a/tcl/doc/NameOfImg.3 b/tcl/doc/NameOfImg.3 deleted file mode 100644 index fdc71f52b9..0000000000 --- a/tcl/doc/NameOfImg.3 +++ /dev/null @@ -1,34 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_NameOfImage 3 4.0 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_NameOfImage \- Return name of image. -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -CONST char * -\fBTk_NameOfImage\fR(\fItypePtr\fR) -.SH ARGUMENTS -.AS Tk_ImageMaster *masterPtr -.AP Tk_ImageMaster *masterPtr in -Token for image, which was passed to image manager's \fIcreateProc\fR when -the image was created. -.BE - -.SH DESCRIPTION -.PP -This procedure is invoked by image managers to find out the name -of an image. Given the token for the image, it returns the -string name for the image. - -.SH KEYWORDS -image manager, image name diff --git a/tcl/doc/OwnSelect.3 b/tcl/doc/OwnSelect.3 deleted file mode 100644 index 9b2e59d1e1..0000000000 --- a/tcl/doc/OwnSelect.3 +++ /dev/null @@ -1,52 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_OwnSelection 3 4.0 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_OwnSelection \- make a window the owner of the primary selection -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -\fBTk_OwnSelection\fR(\fItkwin, selection, proc, clientData\fR) -.SH ARGUMENTS -.AS Tk_LostSelProc clientData -.AP Tk_Window tkwin in -Window that is to become new selection owner. -.AP Atom selection in -The name of the selection to be owned, such as XA_PRIMARY. -.AP Tk_LostSelProc *proc in -Procedure to invoke when \fItkwin\fR loses selection ownership later. -.AP ClientData clientData in -Arbitrary one-word value to pass to \fIproc\fR. -.BE - -.SH DESCRIPTION -.PP -\fBTk_OwnSelection\fR arranges for \fItkwin\fR to become the -new owner of the selection specified by the atom -\fIselection\fR. After this call completes, future requests -for the selection will be directed to handlers created for -\fItkwin\fR using \fBTk_CreateSelHandler\fR. When \fItkwin\fR -eventually loses the selection ownership, \fIproc\fR will be -invoked so that the window can clean itself up (e.g. by -unhighlighting the selection). \fIProc\fR should have arguments and -result that match the type \fBTk_LostSelProc\fR: -.CS -typedef void Tk_LostSelProc(ClientData \fIclientData\fR); -.CE -The \fIclientData\fR parameter to \fIproc\fR is a copy of the -\fIclientData\fR argument given to \fBTk_OwnSelection\fR, and is -usually a pointer to a data structure containing application-specific -information about \fItkwin\fR. - -.SH KEYWORDS -own, selection owner diff --git a/tcl/doc/ParseArgv.3 b/tcl/doc/ParseArgv.3 deleted file mode 100644 index 4fc886d2fe..0000000000 --- a/tcl/doc/ParseArgv.3 +++ /dev/null @@ -1,351 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_ParseArgv 3 "" Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_ParseArgv \- process command-line options -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -int -\fBTk_ParseArgv\fR(\fIinterp, tkwin, argcPtr, argv, argTable, flags\fR) -.SH ARGUMENTS -.AS Tk_ArgvInfo *argTable -.AP Tcl_Interp *interp in -Interpreter to use for returning error messages. -.AP Tk_Window tkwin in -Window to use when arguments specify Tk options. If NULL, then -no Tk options will be processed. -.AP int argcPtr in/out -Pointer to number of arguments in argv; gets modified to hold -number of unprocessed arguments that remain after the call. -.AP "CONST char" **argv in/out -Command line arguments passed to main program. Modified to -hold unprocessed arguments that remain after the call. -.AP Tk_ArgvInfo *argTable in -Array of argument descriptors, terminated by element with -type TK_ARGV_END. -.AP int flags in -If non-zero, then it specifies one or more flags that control the -parsing of arguments. Different flags may be OR'ed together. -The flags currently defined are TK_ARGV_DONT_SKIP_FIRST_ARG, -TK_ARGV_NO_ABBREV, TK_ARGV_NO_LEFTOVERS, and TK_ARGV_NO_DEFAULTS. -.BE -.SH DESCRIPTION -.PP -\fBTk_ParseArgv\fR processes an array of command-line arguments according -to a table describing the kinds of arguments that are expected. -Each of the arguments in \fIargv\fR is processed in turn: if it matches -one of the entries in \fIargTable\fR, the argument is processed -according to that entry and discarded. The arguments that do not -match anything in \fIargTable\fR are copied down to the beginning -of \fIargv\fR (retaining their original order) and returned to -the caller. At the end of the call -\fBTk_ParseArgv\fR sets \fI*argcPtr\fR to hold the number of -arguments that are left in \fIargv\fR, and \fIargv[*argcPtr]\fR -will hold the value NULL. Normally, \fBTk_ParseArgv\fR -assumes that \fIargv[0]\fR is a command name, so it is treated like -an argument that doesn't match \fIargTable\fR and returned to the -caller; however, if the TK_ARGV_DONT_SKIP_FIRST_ARG bit is set in -\fIflags\fR then \fIargv[0]\fR will be processed just like the other -elements of \fIargv\fR. -.PP -\fBTk_ParseArgv\fR normally returns the value TCL_OK. If an error -occurs while parsing the arguments, then TCL_ERROR is returned and -\fBTk_ParseArgv\fR will leave an error message in \fIinterp->result\fR -in the standard Tcl fashion. In -the event of an error return, \fI*argvPtr\fR will not have been -modified, but \fIargv\fR could have been partially modified. The -possible causes of errors are explained below. -.PP -The \fIargTable\fR array specifies the kinds of arguments that are -expected; each of its entries has the following structure: -.CS -typedef struct { - char *\fIkey\fR; - int \fItype\fR; - char *\fIsrc\fR; - char *\fIdst\fR; - char *\fIhelp\fR; -} Tk_ArgvInfo; -.CE -The \fIkey\fR field is a string such as ``\-display'' or ``\-bg'' -that is compared with the values in \fIargv\fR. \fIType\fR -indicates how to process an argument that matches \fIkey\fR -(more on this below). \fISrc\fR and \fIdst\fR are additional -values used in processing the argument. Their exact usage -depends on \fItype\fR, but typically \fIsrc\fR indicates -a value and \fIdst\fR indicates where to store the -value. The \fBchar *\fR declarations for \fIsrc\fR and \fIdst\fR -are placeholders: the actual types may be different. Lastly, -\fIhelp\fR is a string giving a brief description -of this option; this string is printed when users ask for help -about command-line options. -.PP -When processing an argument in \fIargv\fR, \fBTk_ParseArgv\fR -compares the argument to each of the \fIkey\fR's in \fIargTable\fR. -\fBTk_ParseArgv\fR selects the first specifier whose \fIkey\fR matches -the argument exactly, if such a specifier exists. Otherwise -\fBTk_ParseArgv\fR selects a specifier for which the argument -is a unique abbreviation. If the argument is a unique abbreviation -for more than one specifier, then an error is returned. If there -is no matching entry in \fIargTable\fR, then the argument is -skipped and returned to the caller. -.PP -Once a matching argument specifier is found, \fBTk_ParseArgv\fR -processes the argument according to the \fItype\fR field of the -specifier. The argument that matched \fIkey\fR is called ``the matching -argument'' in the descriptions below. As part of the processing, -\fBTk_ParseArgv\fR may also use the next argument in \fIargv\fR -after the matching argument, which is called ``the following -argument''. The legal values for \fItype\fR, and the processing -that they cause, are as follows: -.TP -\fBTK_ARGV_END\fR -Marks the end of the table. The last entry in \fIargTable\fR -must have this type; all of its other fields are ignored and it -will never match any arguments. -.TP -\fBTK_ARGV_CONSTANT\fR -\fISrc\fR is treated as an integer and \fIdst\fR is treated -as a pointer to an integer. \fISrc\fR is stored at \fI*dst\fR. -The matching argument is discarded. -.TP -\fBTK_ARGV_INT\fR -The following argument must contain an -integer string in the format accepted by \fBstrtol\fR (e.g. ``0'' -and ``0x'' prefixes may be used to specify octal or hexadecimal -numbers, respectively). \fIDst\fR is treated as a pointer to an -integer; the following argument is converted to an integer value -and stored at \fI*dst\fR. \fISrc\fR is ignored. The matching -and following arguments are discarded from \fIargv\fR. -.TP -\fBTK_ARGV_FLOAT\fR -The following argument must contain a floating-point number in -the format accepted by \fBstrtol\fR. -\fIDst\fR is treated as the address of an double-precision -floating point value; the following argument is converted to a -double-precision value and stored at \fI*dst\fR. The matching -and following arguments are discarded from \fIargv\fR. -.TP -\fBTK_ARGV_STRING\fR -In this form, \fIdst\fR is treated as a pointer to a (char *); -\fBTk_ParseArgv\fR stores at \fI*dst\fR a pointer to the following -argument, and discards the matching and following arguments from -\fIargv\fR. \fISrc\fR is ignored. -.TP -\fBTK_ARGV_UID\fR -This form is similar to TK_ARGV_STRING, except that the argument -is turned into a Tk_Uid by calling \fBTk_GetUid\fR. -\fIDst\fR is treated as a pointer to a -Tk_Uid; \fBTk_ParseArgv\fR stores at \fI*dst\fR the Tk_Uid -corresponding to the following -argument, and discards the matching and following arguments from -\fIargv\fR. \fISrc\fR is ignored. -.TP -\fBTK_ARGV_CONST_OPTION\fR -This form causes a Tk option to be set (as if the \fBoption\fR -command had been invoked). The \fIsrc\fR field is treated as a -pointer to a string giving the value of an option, and \fIdst\fR -is treated as a pointer to the name of the option. The matching -argument is discarded. If \fItkwin\fR is NULL, then argument -specifiers of this type are ignored (as if they did not exist). -.TP -\fBTK_ARGV_OPTION_VALUE\fR -This form is similar to TK_ARGV_CONST_OPTION, except that the -value of the option is taken from the following argument instead -of from \fIsrc\fR. \fIDst\fR is used as the name of the option. -\fISrc\fR is ignored. The matching and following arguments -are discarded. If \fItkwin\fR is NULL, then argument -specifiers of this type are ignored (as if they did not exist). -.TP -\fBTK_ARGV_OPTION_NAME_VALUE\fR -In this case the following argument is taken as the name of a Tk -option and the argument after that is taken as the value for that -option. Both \fIsrc\fR and \fIdst\fR are ignored. All three -arguments are discarded from \fIargv\fR. If \fItkwin\fR is NULL, -then argument -specifiers of this type are ignored (as if they did not exist). -.TP -\fBTK_ARGV_HELP\fR -When this kind of option is encountered, \fBTk_ParseArgv\fR uses the -\fIhelp\fR fields of \fIargTable\fR to format a message describing -all the valid arguments. The message is placed in \fIinterp->result\fR -and \fBTk_ParseArgv\fR returns TCL_ERROR. When this happens, the -caller normally prints the help message and aborts. If the \fIkey\fR -field of a TK_ARGV_HELP specifier is NULL, then the specifier will -never match any arguments; in this case the specifier simply provides -extra documentation, which will be included when some other -TK_ARGV_HELP entry causes help information to be returned. -.TP -\fBTK_ARGV_REST\fR -This option is used by programs or commands that allow the last -several of their options to be the name and/or options for some -other program. If a \fBTK_ARGV_REST\fR argument is found, then -\fBTk_ParseArgv\fR doesn't process any -of the remaining arguments; it returns them all at -the beginning of \fIargv\fR (along with any other unprocessed arguments). -In addition, \fBTk_ParseArgv\fR treats \fIdst\fR as the address of an -integer value, and stores at \fI*dst\fR the index of the first of the -\fBTK_ARGV_REST\fR options in the returned \fIargv\fR. This allows the -program to distinguish the \fBTK_ARGV_REST\fR options from other -unprocessed options that preceded the \fBTK_ARGV_REST\fR. -.TP -\fBTK_ARGV_FUNC\fR -For this kind of argument, \fIsrc\fR is treated as the address of -a procedure, which is invoked to process the following argument. -The procedure should have the following structure: -.RS -.CS -int -\fIfunc\fR(\fIdst\fR, \fIkey\fR, \fInextArg\fR) - char *\fIdst\fR; - char *\fIkey\fR; - char *\fInextArg\fR; -{ -} -.CE -The \fIdst\fR and \fIkey\fR parameters will contain the -corresponding fields from the \fIargTable\fR entry, and -\fInextArg\fR will point to the following argument from \fIargv\fR -(or NULL if there aren't any more arguments left in \fIargv\fR). -If \fIfunc\fR uses \fInextArg\fR (so that -\fBTk_ParseArgv\fR should discard it), then it should return 1. Otherwise it -should return 0 and \fBTkParseArgv\fR will process the following -argument in the normal fashion. In either event the matching argument -is discarded. -.RE -.TP -\fBTK_ARGV_GENFUNC\fR -This form provides a more general procedural escape. It treats -\fIsrc\fR as the address of a procedure, and passes that procedure -all of the remaining arguments. The procedure should have the following -form: -.RS -.CS -int -\fIgenfunc\fR(dst, interp, key, argc, argv) - char *\fIdst\fR; - Tcl_Interp *\fIinterp\fR; - char *\fIkey\fR; - int \fIargc\fR; - char **\fIargv\fR; -{ -} -.CE -The \fIdst\fR and \fIkey\fR parameters will contain the -corresponding fields from the \fIargTable\fR entry. \fIInterp\fR -will be the same as the \fIinterp\fR argument to \fBTcl_ParseArgv\fR. -\fIArgc\fR and \fIargv\fR refer to all of the options after the -matching one. \fIGenfunc\fR should behave in a fashion similar -to \fBTk_ParseArgv\fR: parse as many of the remaining arguments as it can, -then return any that are left by compacting them to the beginning of -\fIargv\fR (starting at \fIargv\fR[0]). \fIGenfunc\fR -should return a count of how many arguments are left in \fIargv\fR; -\fBTk_ParseArgv\fR will process them. If \fIgenfunc\fR encounters -an error then it should leave an error message in \fIinterp->result\fR, -in the usual Tcl fashion, and return -1; when this happens -\fBTk_ParseArgv\fR will abort its processing and return TCL_ERROR. -.RE - -.SH "FLAGS" -.TP -\fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR -\fBTk_ParseArgv\fR normally treats \fIargv[0]\fR as a program -or command name, and returns it to the caller just as if it -hadn't matched \fIargTable\fR. If this flag is given, then -\fIargv[0]\fR is not given special treatment. -.TP -\fBTK_ARGV_NO_ABBREV\fR -Normally, \fBTk_ParseArgv\fR accepts unique abbreviations for -\fIkey\fR values in \fIargTable\fR. If this flag is given then -only exact matches will be acceptable. -.TP -\fBTK_ARGV_NO_LEFTOVERS\fR -Normally, \fBTk_ParseArgv\fR returns unrecognized arguments to the -caller. If this bit is set in \fIflags\fR then \fBTk_ParseArgv\fR -will return an error if it encounters any argument that doesn't -match \fIargTable\fR. The only exception to this rule is \fIargv[0]\fR, -which will be returned to the caller with no errors as -long as TK_ARGV_DONT_SKIP_FIRST_ARG isn't specified. -.TP -\fBTK_ARGV_NO_DEFAULTS\fR -Normally, \fBTk_ParseArgv\fR searches an internal table of -standard argument specifiers in addition to \fIargTable\fR. If -this bit is set in \fIflags\fR, then \fBTk_ParseArgv\fR will -use only \fIargTable\fR and not its default table. - -.SH EXAMPLE -.PP -Here is an example definition of an \fIargTable\fR and -some sample command lines that use the options. Note the effect -on \fIargc\fR and \fIargv\fR; arguments processed by \fBTk_ParseArgv\fR -are eliminated from \fIargv\fR, and \fIargc\fR -is updated to reflect reduced number of arguments. -.CS -/* - * Define and set default values for globals. - */ -int debugFlag = 0; -int numReps = 100; -char defaultFileName[] = "out"; -char *fileName = defaultFileName; -Boolean exec = FALSE; - -/* - * Define option descriptions. - */ -Tk_ArgvInfo argTable[] = { - {"-X", TK_ARGV_CONSTANT, (char *) 1, (char *) &debugFlag, - "Turn on debugging printfs"}, - {"-N", TK_ARGV_INT, (char *) NULL, (char *) &numReps, - "Number of repetitions"}, - {"-of", TK_ARGV_STRING, (char *) NULL, (char *) &fileName, - "Name of file for output"}, - {"x", TK_ARGV_REST, (char *) NULL, (char *) &exec, - "File to exec, followed by any arguments (must be last argument)."}, - {(char *) NULL, TK_ARGV_END, (char *) NULL, (char *) NULL, - (char *) NULL} -}; - -main(argc, argv) - int argc; - char *argv[]; -{ - \&... - - if (Tk_ParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCL_OK) { - fprintf(stderr, "%s\en", interp->result); - exit(1); - } - - /* - * Remainder of the program. - */ -} -.CE -.PP -Note that default values can be assigned to variables named in -\fIargTable\fR: the variables will only be overwritten if the -particular arguments are present in \fIargv\fR. -Here are some example command lines and their effects. -.CS -prog -N 200 infile # just sets the numReps variable to 200 -prog -of out200 infile # sets fileName to reference "out200" -prog -XN 10 infile # sets the debug flag, also sets numReps -.CE -In all of the above examples, \fIargc\fR will be set by \fBTk_ParseArgv\fR to 2, -\fIargv\fR[0] will be ``prog'', \fIargv\fR[1] will be ``infile'', -and \fIargv\fR[2] will be NULL. - -.SH KEYWORDS -arguments, command line, options diff --git a/tcl/doc/QWinEvent.3 b/tcl/doc/QWinEvent.3 deleted file mode 100644 index 7e58055d46..0000000000 --- a/tcl/doc/QWinEvent.3 +++ /dev/null @@ -1,53 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_QueueWindowEvent 3 7.5 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_CollapseMotionEvents, Tk_QueueWindowEvent \- Add a window event to the Tcl event queue -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -int -\fBTk_CollapseMotionEvents\fR(\fIdisplay, collapse\fR) -.sp -\fBTk_QueueWindowEvent\fR(\fIeventPtr, position\fR) -.SH ARGUMENTS -.AS Tcl_QueuePosition position -.AP Display *display in -Display for which to control motion event collapsing. -.AP int collapse in -Indicates whether motion events should be collapsed or not. -.AP XEvent *eventPtr in -An event to add to the event queue. -.AP Tcl_QueuePosition position in -Where to add the new event in the queue: \fBTCL_QUEUE_TAIL\fR, -\fBTCL_QUEUE_HEAD\fR, or \fBTCL_QUEUE_MARK\fR. -.BE - -.SH DESCRIPTION -.PP -\fBTk_QueueWindowEvent\fR places a window event on Tcl's internal event -queue for eventual servicing. It creates a Tcl_Event structure, copies the -event into that structure, and calls \fBTcl_QueueEvent\fR to add the event -to the queue. When the event is eventually removed from the queue it is -processed just like all window events. -.PP -When multiple motion events are received for the same window in rapid -succession, they are collapsed by default. This behavior can be controlled -with \fBTk_CollapseMotionEvents\fR. \fBTk_CollapseMotionEvents\fR always -returns the previous value for collapse behavior on the \fIdisplay\fR. -.PP -The \fIposition\fR argument to \fBTk_QueueWindowEvent\fR has -the same significance as for \fBTcl_QueueEvent\fR; see the -documentation for \fBTcl_QueueEvent\fR for details. - -.SH KEYWORDS -callback, clock, handler, modal timeout, events diff --git a/tcl/doc/Restack.3 b/tcl/doc/Restack.3 deleted file mode 100644 index 6389d09d36..0000000000 --- a/tcl/doc/Restack.3 +++ /dev/null @@ -1,49 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_RestackWindow 3 "" Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_RestackWindow \- Change a window's position in the stacking order -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -int -\fBTk_RestackWindow\fR(\fItkwin, aboveBelow, other\fR) -.SH ARGUMENTS -.AS Tk_Window aboveBelow -.AP Tk_Window tkwin in -Token for window to restack. -.AP int aboveBelow in -Indicates new position of \fItkwin\fR relative to \fIother\fR; -must be \fBAbove\fR or \fBBelow\fR. -.AP Tk_Window other in -\fITkwin\fR will be repositioned just above or below this window. -Must be a sibling of \fItkwin\fR or a descendant of a sibling. -If NULL then \fItkwin\fR is restacked above or below all siblings. -.BE - -.SH DESCRIPTION -.PP -\fBTk_RestackWindow\fR changes the stacking order of \fIwindow\fR relative -to its siblings. -If \fIother\fR is specified as NULL then \fIwindow\fR is repositioned -at the top or bottom of its stacking order, depending on whether -\fIaboveBelow\fR is \fBAbove\fR or \fBBelow\fR. -If \fIother\fR has a non-NULL value then \fIwindow\fR is repositioned -just above or below \fIother\fR. -.PP -The \fIaboveBelow\fR argument must have one of the symbolic values -\fBAbove\fR or \fBBelow\fR. -Both of these values are defined by the include file . - -.SH KEYWORDS -above, below, obscure, stacking order diff --git a/tcl/doc/RestrictEv.3 b/tcl/doc/RestrictEv.3 deleted file mode 100644 index cb5653fe03..0000000000 --- a/tcl/doc/RestrictEv.3 +++ /dev/null @@ -1,81 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_RestrictEvents 3 "" Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_RestrictEvents \- filter and selectively delay X events -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -Tk_RestrictProc * -\fBTk_RestrictEvents\fR(\fIproc, clientData, prevClientDataPtr\fR) -.SH ARGUMENTS -.AS Tk_RestrictProc **prevClientDataPtr -.AP Tk_RestrictProc *proc in -Predicate procedure to call to filter incoming X events. -NULL means do not restrict events at all. -.AP ClientData clientData in -Arbitrary argument to pass to \fIproc\fR. -.AP ClientData *prevClientDataPtr out -Pointer to place to save argument to previous restrict procedure. -.BE - -.SH DESCRIPTION -.PP -This procedure is useful in certain situations where applications -are only prepared to receive certain X events. After -\fBTk_RestrictEvents\fR is called, \fBTk_DoOneEvent\fR (and -hence \fBTk_MainLoop\fR) will filter X input events through -\fIproc\fR. \fIProc\fR indicates whether a -given event is to be processed immediately, deferred until some -later time (e.g. when the event restriction is lifted), or discarded. -\fIProc\fR -is a procedure with arguments and result that match -the type \fBTk_RestrictProc\fR: -.CS -typedef Tk_RestrictAction Tk_RestrictProc( - ClientData \fIclientData\fR, - XEvent *\fIeventPtr\fR); -.CE -The \fIclientData\fR argument is a copy of the \fIclientData\fR passed -to \fBTk_RestrictEvents\fR; it may be used to provide \fIproc\fR with -information it needs to filter events. The \fIeventPtr\fR points to -an event under consideration. \fIProc\fR returns a restrict action -(enumerated type \fBTk_RestrictAction\fR) that indicates what -\fBTk_DoOneEvent\fR should do with the event. If the return value is -\fBTK_PROCESS_EVENT\fR, then the event will be handled immediately. -If the return value is \fBTK_DEFER_EVENT\fR, then the event will be -left on the event queue for later processing. If the return value is -\fBTK_DISCARD_EVENT\fR, then the event will be removed from the event -queue and discarded without being processed. -.PP -\fBTk_RestrictEvents\fR uses its return value and \fIprevClientDataPtr\fR -to return information about the current event restriction procedure -(a NULL return value means there are currently no restrictions). -These values may be used to restore the previous restriction state -when there is no longer any need for the current restriction. -.PP -There are very few places where \fBTk_RestrictEvents\fR is needed. -In most cases, the best way to restrict events is by changing the -bindings with the \fBbind\fR Tcl command or by calling -\fBTk_CreateEventHandler\fR and \fBTk_DeleteEventHandler\fR from C. -The main place where \fBTk_RestrictEvents\fR must be used is when -performing synchronous actions (for example, if you need to wait -for a particular event to occur on a particular window but you don't -want to invoke any handlers for any other events). The ``obvious'' -solution in these situations is to call \fBXNextEvent\fR or -\fBXWindowEvent\fR, but these procedures cannot be used because -Tk keeps its own event queue that is separate from the X event -queue. Instead, call \fBTk_RestrictEvents\fR to set up a filter, -then call \fBTk_DoOneEvent\fR to retrieve the desired event(s). -.SH KEYWORDS -delay, event, filter, restriction diff --git a/tcl/doc/SetAppName.3 b/tcl/doc/SetAppName.3 deleted file mode 100644 index 293129fd15..0000000000 --- a/tcl/doc/SetAppName.3 +++ /dev/null @@ -1,65 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_SetAppName 3 4.0 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_SetAppName \- Set the name of an application for ``send'' commands -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -CONST char * -\fBTk_SetAppName\fR(\fItkwin, name\fR) -.SH ARGUMENTS -.AS Tk_Window parent -.AP Tk_Window tkwin in -Token for window in application. Used only to select a particular -application. -.AP "CONST char" *name in -Name under which to register the application. -.BE - -.SH DESCRIPTION -.PP -\fBTk_SetAppName\fR associates a name with a given application and -records that association on the display containing with the application's -main window. -After this procedure has been invoked, other applications on the -display will be able to use the \fBsend\fR command to invoke operations -in the application. -If \fIname\fR is already in use by some other application on the -display, then a new name will be generated by appending -``\fB #2\fR'' to \fIname\fR; if this name is also in use, -the number will be incremented until an unused name is found. -The return value from the procedure is a pointer to the name actually -used. -.PP -If the application already has a name when \fBTk_SetAppName\fR is -called, then the new name replaces the old name. -.PP -\fBTk_SetAppName\fR also adds a \fBsend\fR command to the application's -interpreter, which can be used to send commands from this application -to others on any of the displays where the application has windows. -.PP -The application's name registration persists until the interpreter is -deleted or the \fBsend\fR command is deleted from \fIinterp\fR, at which -point the name is automatically unregistered and the application -becomes inaccessible via \fBsend\fR. -The application can be made accessible again by calling \fBTk_SetAppName\fR. -.PP -\fBTk_SetAppName\fR is called automatically by \fBTk_Init\fR, -so applications don't normally need to call it explicitly. -.PP -The command \fBtk appname\fR provides Tcl-level access to the -functionality of \fBTk_SetAppName\fR. - -.SH KEYWORDS -application, name, register, send command diff --git a/tcl/doc/SetCaret.3 b/tcl/doc/SetCaret.3 deleted file mode 100644 index 067ee4a5d9..0000000000 --- a/tcl/doc/SetCaret.3 +++ /dev/null @@ -1,40 +0,0 @@ -'\" -'\" Copyright (c) 2002 ActiveState Corporation. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id$ -'\" -.so man.macros -.TH Tk_SetCaretPos 3 8.4 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_SetCaretPos \- set the display caret location -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -int -\fBTk_SetCaretPos\fR(\fItkwin, x, y, height\fR) -.SH ARGUMENTS -.AP Tk_Window tkwin in -Token for window. -.AP int x in -Window-relative x coordinate. -.AP int y in -Window-relative y coordinate. -.AP int h in -Height of the caret in the window. -.BE - -.SH DESCRIPTION -.PP -\fBTk_SetCaretPos\fR sets the caret location for the display of the -specified Tk_Window \fItkwin\fR. The caret is the per-display cursor -location used for indicating global focus (e.g. to comply with Microsoft -Accessibility guidelines), as well as for location of the over-the-spot XIM -(X Input Methods) or Windows IME windows. - -.SH KEYWORDS -caret, cursor diff --git a/tcl/doc/SetClass.3 b/tcl/doc/SetClass.3 deleted file mode 100644 index 9b2f981472..0000000000 --- a/tcl/doc/SetClass.3 +++ /dev/null @@ -1,61 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_SetClass 3 "" Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_SetClass, Tk_Class \- set or retrieve a window's class -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -\fBTk_SetClass\fR(\fItkwin, class\fR) -.sp -Tk_Uid -\fBTk_Class\fR(\fItkwin\fR) -.SH ARGUMENTS -.AS Tk_Window parent -.AP Tk_Window tkwin in -Token for window. -.AP char *class in -New class name for window. -.BE - -.SH DESCRIPTION -.PP -\fBTk_SetClass\fR is called to associate a class with a particular -window. The \fIclass\fR string identifies the type of the -window; all windows with the same general class of behavior -(button, menu, etc.) should have the same class. By -convention all class names start with a capital letter, and -there exists a Tcl command with the same name as -each class (except all in lower-case) which can be used to -create and manipulate windows of that class. -A window's class string is initialized to NULL -when the window is created. -.PP -For main windows, Tk automatically propagates the name and class -to the WM_CLASS property used by window managers. This happens -either when a main window is actually created (e.g. in -\fBTk_MakeWindowExist\fR), or when \fBTk_SetClass\fR -is called, whichever occurs later. If a main window has not been -assigned a class then Tk will not set the WM_CLASS property for -the window. -.PP -\fBTk_Class\fR is a macro that returns the -current value of \fItkwin\fR's class. The value is returned -as a Tk_Uid, which may be used just like a string pointer but also has -the properties of a unique identifier (see the manual entry for -\fBTk_GetUid\fR for details). -If \fItkwin\fR has not yet been given a class, then -\fBTk_Class\fR will return NULL. - -.SH KEYWORDS -class, unique identifier, window, window manager diff --git a/tcl/doc/SetClassProcs.3 b/tcl/doc/SetClassProcs.3 deleted file mode 100644 index 5b563ee3dc..0000000000 --- a/tcl/doc/SetClassProcs.3 +++ /dev/null @@ -1,91 +0,0 @@ -'\" -'\" Copyright (c) 2000 Ajuba Solutions. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id$ -'\" -.so man.macros -.TH Tk_SetClassProcs 3 8.4 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_SetClassProcs \- register widget specific procedures -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -\fBTk_SetClassProcs\fR(\fItkwin, procs, instanceData\fR) -.SH ARGUMENTS -.AS Tk_ClassProc instanceData -.AP Tk_Window tkwin in -Token for window to modify. -.AP Tk_ClassProcs *procs in -Pointer to data structure containing widget specific procedures. -The data structure pointed to by \fIprocs\fR must be static: -Tk keeps a reference to it as long as the window exists. -.AP ClientData instanceData in -Arbitrary one-word value to pass to widget callbacks. -.BE - -.SH DESCRIPTION -.PP -\fBTk_SetClassProcs\fR is called to register a set of procedures that -are used as callbacks in different places. -.PP -The structure pointed to by \fIprocs\fR contains the following: -.CS -typedef struct Tk_ClassProcs { - unsigned int \fIsize\fR; - Tk_ClassWorldChangedProc *\fIworldChangedProc\fR; - Tk_ClassCreateProc *\fIcreateProc\fR; - Tk_ClassModalProc *\fImodalProc\fR; -} Tk_ClassProcs; -.CE -The \fIsize\fR field is used to simplify future expansion of the -structure. It should always be set to (literally) \fBsizeof(Tk_ClassProcs)\fR. -.PP -\fIworldChangedProc\fR is invoked when the system has altered -in some way that requires some reaction from the widget. For example, -when a font alias (see the \fBfont\fR manual entry) is reconfigured, -widgets configured to use that font alias must update their display -accordingly. \fIworldChangedProc\fR should have arguments and results -that match the type \fBTk_ClassWorldChangedProc\fR: -.CS -typedef void Tk_ClassWorldChangedProc( - ClientData \fIinstanceData\fR); -.CE -The \fIinstanceData\fR parameter passed to the \fIworldChangedProc\fR -will be identical to the \fIinstanceData\fR paramter passed to -\fBTk_SetClassProcs\fR. -.PP -\fIcreateProc\fR is used to create platform-dependant windows. It is -invoked by \fBTk_MakeWindowExist\fR. \fIcreateProc\fR should have -arguments and results that match the type \fBTk_ClassCreateProc\fR: -.CS -typedef Window Tk_ClassCreateProc( - Tk_Window \fItkwin\fR, - Window \fIparent\fR, - ClientData \fIinstanceData\fR); -.CE -The \fItkwin\fR and \fIinstanceData\fR parameters will be identical to -the \fItkwin\fR and \fIinstanceData\fR parameters passed to -\fBTk_SetClassProcs\fR. The \fIparent\fR parameter will be the parent -of the window to be created. The \fIcreateProc\fR should return the -created window. -.PP -\fImodalProc\fR is invoked after all bindings on a widget have been -triggered in order to handle a modal loop. \fImodalProc\fR should -have arguments and results that match the type \fBTk_ClassModalProc\fR: -.CS -typedef void Tk_ClassModalProc( - Tk_Window \fItkwin\fR, - XEvent *\fIeventPtr\fR); -.CE -The \fItkwin\fR parameter to \fImodalProc\fR will be identical to the -\fItkwin\fR parameter passed to \fBTk_SetClassProcs\fR. The -\fIeventPtr\fR parameter will be a pointer to an XEvent structure -describing the event being processed. - -.SH KEYWORDS -callback, class diff --git a/tcl/doc/SetGrid.3 b/tcl/doc/SetGrid.3 deleted file mode 100644 index d867ca4c3e..0000000000 --- a/tcl/doc/SetGrid.3 +++ /dev/null @@ -1,67 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_SetGrid 3 4.0 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_SetGrid, Tk_UnsetGrid \- control the grid for interactive resizing -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -\fBTk_SetGrid\fR(\fItkwin, reqWidth, reqHeight, widthInc, heightInc\fR) -.sp -\fBTk_UnsetGrid\fR(\fItkwin\fR) -.SH ARGUMENTS -.AS Tk_Window heightInc -.AP Tk_Window tkwin in -Token for window. -.AP int reqWidth in -Width in grid units that corresponds to the pixel dimension \fItkwin\fR -has requested via \fBTk_GeometryRequest\fR. -.AP int reqHeight in -Height in grid units that corresponds to the pixel dimension \fItkwin\fR -has requested via \fBTk_GeometryRequest\fR. -.AP int widthInc in -Width of one grid unit, in pixels. -.AP int heightInc in -Height of one grid unit, in pixels. -.BE - -.SH DESCRIPTION -.PP -\fBTk_SetGrid\fR turns on gridded geometry management for \fItkwin\fR's -toplevel window and specifies the geometry of the grid. -\fBTk_SetGrid\fR is typically invoked by a widget when its \fBsetGrid\fR -option is true. -It restricts interactive resizing of \fItkwin\fR's toplevel window so -that the space allocated to the toplevel is equal to its requested -size plus or minus even multiples of \fIwidthInc\fR and \fIheightInc\fR. -Furthermore, the \fIreqWidth\fR and \fIreqHeight\fR values are -passed to the window manager so that it can report the window's -size in grid units during interactive resizes. -If \fItkwin\fR's configuration changes (e.g., the size of a grid unit -changes) then the widget should invoke \fBTk_SetGrid\fR again with the new -information. -.PP -\fBTk_UnsetGrid\fR cancels gridded geometry management for -\fItkwin\fR's toplevel window. -.PP -For each toplevel window there can be at most one internal window -with gridding enabled. -If \fBTk_SetGrid\fR or \fBTk_UnsetGrid\fR is invoked when some -other window is already controlling gridding for \fItkwin\fR's -toplevel, the calls for the new window have no effect. -.PP -See the \fBwm\fR manual entry for additional information on gridded geometry -management. - -.SH KEYWORDS -grid, window, window manager diff --git a/tcl/doc/SetOptions.3 b/tcl/doc/SetOptions.3 deleted file mode 100644 index 925a68767d..0000000000 --- a/tcl/doc/SetOptions.3 +++ /dev/null @@ -1,653 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_SetOptions 3 8.1 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_CreateOptionTable, Tk_DeleteOptionTable, Tk_InitOptions, Tk_SetOptions, Tk_FreeSavedOptions, Tk_RestoreSavedOptions, Tk_GetOptionValue, Tk_GetOptionInfo, Tk_FreeConfigOptions, Tk_Offset \- process configuration options -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -Tk_OptionTable -\fBTk_CreateOptionTable(\fIinterp, templatePtr\fB)\fR -.sp -\fBTk_DeleteOptionTable(\fIoptionTable\fB)\fR -.sp -int -\fBTk_InitOptions(\fIinterp, recordPtr, optionTable, tkwin\fB)\fR -.sp -int -\fBTk_SetOptions(\fIinterp, recordPtr, optionTable, objc, objv, tkwin, savePtr, maskPtr\fB)\fR -.sp -\fBTk_FreeSavedOptions(\fIsavedPtr\fB)\fR -.sp -\fBTk_RestoreSavedOptions(\fIsavedPtr\fB)\fR -.sp -Tcl_Obj * -\fBTk_GetOptionValue(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR -.sp -Tcl_Obj * -\fBTk_GetOptionInfo(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR -.sp -\fBTk_FreeConfigOptions(\fIrecordPtr, optionTable, tkwin\fB)\fR -.sp -int -\fBTk_Offset(\fItype, field\fB)\fR -.SH ARGUMENTS -.AS Tk_SavedOptions "*CONST objv[]" in/out -.AP Tcl_Interp *interp in -A Tcl interpreter. Most procedures use this only for returning error -messages; if it is NULL then no error messages are returned. For -\fBTk_CreateOptionTable\fR the value cannot be NULL; it gives the -interpreter in which the option table will be used. -.AP Tk_OptionSpec *templatePtr in -Points to an array of static information that describes the configuration -options that are supported. Used to build a Tk_OptionTable. The information -pointed to by this argument must exist for the lifetime of the Tk_OptionTable. -.AP Tk_OptionTable optionTable in -Token for an option table. Must have been returned by a previous call -to \fBTk_CreateOptionTable\fR. -.AP char *recordPtr in/out -Points to structure in which values of configuration options are stored; -fields of this record are modified by procedures such as \fBTk_SetOptions\fR -and read by procedures such as \fBTk_GetOptionValue\fR. -.AP Tk_Window tkwin in -For options such as TK_OPTION_COLOR, this argument indicates -the window in which the option will be used. If \fIoptionTable\fR uses -no window-dependent options, then a NULL value may be supplied for -this argument. -.AP int objc in -Number of values in \fIobjv\fR. -.AP Tcl_Obj "*CONST objv[]" in -Command-line arguments for setting configuring options. -.AP Tk_SavedOptions *savePtr out -If not NULL, the structure pointed to by this argument is filled -in with the old values of any options that were modified and old -values are restored automatically if an error occurs in \fBTk_SetOptions\fR. -.AP int *maskPtr out -If not NULL, the word pointed to by \fImaskPtr\fR is filled in with the -bit-wise OR of the \fItypeMask\fR fields for the options that -were modified. -.AP Tk_SavedOptions *savedPtr in/out -Points to a structure previously filled in by \fBTk_SetOptions\fR with -old values of modified options. -.AP Tcl_Obj *namePtr in -The value of this object is the name of a particular option. If NULL -is passed to \fBTk_GetOptionInfo\fR then information is returned for -all options. Must not be NULL when \fBTk_GetOptionValue\fR is called. -.AP "type name" type in -The name of the type of a record. -.AP "field name" field in -The name of a field in records of type \fItype\fR. -.BE -.SH DESCRIPTION -.PP -These procedures handle most of the details of parsing configuration -options such as those for Tk widgets. Given a description of what -options are supported, these procedures handle all the details of -parsing options and storing their values into a C structure associated -with the widget or object. The procedures were designed primarily for -widgets in Tk, but they can also be used for other kinds of objects that -have configuration options. In the rest of this manual page ``widget'' will -be used to refer to the object whose options are being managed; in -practice the object may not actually be a widget. The term ``widget -record'' is used to refer to the C-level structure in -which information about a particular widget or object is stored. -.PP -Note: the easiest way to learn how to use these procedures is to -look at a working example. In Tk, the simplest example is the code -that implements the button family of widgets, which is an \fBtkButton.c\fR. -Other examples are in \fBtkSquare.c\fR and \fBtkMenu.c\fR. -.PP -In order to use these procedures, the code that implements the widget -must contain a static array of Tk_OptionSpec structures. This is a -template that describes the various options supported by that class of -widget; there is a separate template for each kind of widget. The -template contains information such as the name of each option, its type, -its default value, and where the value of the option is stored in the -widget record. See TEMPLATES below for more detail. -.PP -In order to process configuration options efficiently, the static -template must be augmented with additional information that is available -only at runtime. The procedure \fBTk_CreateOptionTable\fR creates this -dynamic information from the template and returns a Tk_OptionTable token -that describes both the static and dynamic information. All of the -other procedures, such as \fBTk_SetOptions\fR, take a Tk_OptionTable -token as argument. Typically, \fBTk_CreateOptionTable\fR is called the -first time that a widget of a particular class is created and the -resulting Tk_OptionTable is used in the future for all widgets of that -class. A Tk_OptionTable may be used only in a single interpreter, given -by the \fIinterp\fR argument to \fBTk_CreateOptionTable\fR. When an -option table is no longer needed \fBTk_DeleteOptionTable\fR should be -called to free all of its resources. All of the option tables -for a Tcl interpreter are freed automatically if the interpreter is deleted. -.PP -\fBTk_InitOptions\fR is invoked when a new widget is created to set -the default values for all of the widget's configuration options. -\fBTk_InitOptions\fR is passed a token for an option table (\fIoptionTable\fR) -and a pointer to a widget record (\fIrecordPtr\fR), which is the C -structure that holds information about this widget. \fBTk_InitOptions\fR -uses the information in the option table to -choose an appropriate default for each option, then it stores the default -value directly into the widget record, overwriting any information that -was already present in the widget record. \fBTk_InitOptions\fR normally -returns TCL_OK. If an error occurred while setting the default values -(e.g., because a default value was erroneous) then TCL_ERROR is returned -and an error message is left in \fIinterp\fR's result if \fIinterp\fR -isn't NULL. -.PP -\fBTk_SetOptions\fR is invoked to modify configuration options based -on information specified in a Tcl command. The command might be one that -creates a new widget, or a command that modifies options on an existing -widget. The \fIobjc\fR and \fIobjv\fR arguments describe the -values of the arguments from the Tcl command. \fIObjv\fR must contain -an even number of objects: the first object of each pair gives the name of -an option and the second object gives the new value for that option. -\fBTk_SetOptions\fR looks up each name in \fIoptionTable\fR, checks that -the new value of the option conforms to the type in \fIoptionTable\fR, -and stores the value of the option into the widget record given by -\fIrecordPtr\fR. \fBTk_SetOptions\fR normally returns TCL_OK. If -an error occurred (such as an unknown option name or an illegal option -value) then TCL_ERROR is returned and an error message is left in -\fIinterp\fR's result if \fIinterp\fR isn't NULL. -.PP -\fBTk_SetOptions\fR has two additional features. First, if the -\fImaskPtr\fR argument isn't NULL then it points to an integer -value that is filled in with information about the options that were -modified. For each option in the template passed to -\fBTk_CreateOptionTable\fR there is a \fItypeMask\fR field. The -bits of this field are defined by the code that implements the widget; -for example, each bit might correspond to a particular configuration option. -Alternatively, bits might be used functionally. For example, one bit might -be used for redisplay: all options that affect the widget's display, such -that changing the option requires the widget to be redisplayed, might have -that bit set. Another bit might indicate that the geometry of the widget -must be recomputed, and so on. \fBTk_SetOptions\fR OR's together the -\fItypeMask\fR fields from all the options that were modified and returns -this value at *\fImaskPtr\fR; the caller can then use this information -to optimize itself so that, for example, it doesn't redisplay the widget -if the modified options don't affect the widget's appearance. -.PP -The second additional feature of \fBTk_SetOptions\fR has to do with error -recovery. If an error occurs while processing configuration options, this -feature makes it possible to restore all the configuration options to their -previous values. Errors can occur either while processing options in -\fBTk_SetOptions\fR or later in the caller. In many cases the caller does -additional processing after \fBTk_SetOptions\fR returns; for example, it -might use an option value to set a trace on a variable and may detect -an error if the variable is an array instead of a scalar. Error recovery -is enabled by passing in a non-NULL value for the \fIsavePtr\fR argument -to \fBTk_SetOptions\fR; this should be a pointer to an uninitialized -Tk_SavedOptions structure on the caller's stack. \fBTk_SetOptions\fR -overwrites the structure pointed to by \fIsavePtr\fR with information -about the old values of any options modified by the procedure. -If \fBTk_SetOptions\fR returns successfully, the -caller uses the structure in one of two ways. If the caller completes -its processing of the new options without any errors, then it must pass -the structure to \fBTk_FreeSavedOptions\fR so that the old values can be -freed. If the caller detects an error in its processing of the new -options, then it should pass the structure to \fBTk_RestoreSavedOptions\fR, -which will copy the old values back into the widget record and free -the new values. -If \fBTk_SetOptions\fR detects an error then it automatically restores -any options that had already been modified and leaves *\fIsavePtr\fR in -an empty state: the caller need not call either \fBTk_FreeSavedOptions\fR or -\fBTk_RestoreSavedOptions\fR. -If the \fIsavePtr\fR argument to \fBTk_SetOptions\fR is NULL then -\fBTk_SetOptions\fR frees each old option value immediately when it sets a new -value for the option. In this case, if an error occurs in the third -option, the old values for the first two options cannot be restored. -.PP -\fBTk_GetOptionValue\fR returns the current value of a configuration option -for a particular widget. The \fInamePtr\fR argument contains the name of -an option; \fBTk_GetOptionValue\fR uses \fIoptionTable\fR -to lookup the option and extract its value from the widget record -pointed to by \fIrecordPtr\fR, then it returns an object containing -that value. If an error occurs (e.g., because \fInamePtr\fR contains an -unknown option name) then NULL is returned and an error message is left -in \fIinterp\fR's result unless \fIinterp\fR is NULL. -.PP -\fBTk_GetOptionInfo\fR returns information about configuration options in -a form suitable for \fBconfigure\fR widget commands. If the \fInamePtr\fR -argument is not NULL, it points to an object that gives the name of a -configuration option; \fBTk_GetOptionInfo\fR returns an object containing -a list with five elements, which are the name of the option, the name and -class used for the option in the option database, the default value for -the option, and the current value for the option. If the \fInamePtr\fR -argument is NULL, then \fBTk_GetOptionInfo\fR returns information about -all options in the form of a list of lists; each sublist describes one -option. Synonym options are handled differently depending on whether -\fInamePtr\fR is NULL: if \fInamePtr\fR is NULL then the sublist for -each synonym option has only two elements, which are the name of the -option and the name of the other option that it refers to; if \fInamePtr\fR -is non-NULL and names a synonym option then the object returned -is the five-element list -for the other option that the synonym refers to. If an error occurs -(e.g., because \fInamePtr\fR contains an unknown option name) then NULL -is returned and an error message is left in \fIinterp\fR's result unless -\fIinterp\fR is NULL. -.PP -\fBTk_FreeConfigOptions\fR must be invoked when a widget is deleted. -It frees all of the resources associated with any of the configuration -options defined in \fIrecordPtr\fR by \fIoptionTable\fR. -.PP -The \fBTk_Offset\fR macro is provided as a safe way of generating the -\fIobjOffset\fR and \fIinternalOffset\fR values for entries in -Tk_OptionSpec structures. It takes two arguments: the name of a type -of record, and the name of a field in that record. It returns the byte -offset of the named field in records of the given type. - -.SH "TEMPLATES" -.PP -The array of Tk_OptionSpec structures passed to \fBTk_CreateOptionTable\fR -via its \fItemplatePtr\fR argument describes the configuration options -supported by a particular class of widgets. Each structure specifies -one configuration option and has the following fields: -.CS -typedef struct { - Tk_OptionType \fItype\fR; - char *\fIoptionName\fR; - char *\fIdbName\fR; - char *\fIdbClass\fR; - char *\fIdefValue\fR; - int \fIobjOffset\fR; - int \fIinternalOffset\fR; - int \fIflags\fR; - ClientData \fIclientData\fR; - int \fItypeMask\fR; -} Tk_OptionSpec; -.CE -The \fItype\fR field indicates what kind of configuration option this is -(e.g. TK_OPTION_COLOR for a color value, or TK_OPTION_INT for -an integer value). \fIType\fR determines how the -value of the option is parsed (more on this below). -The \fIoptionName\fR field is a string such as \fB\-font\fR or \fB\-bg\fR; -it is the name used for the option in Tcl commands and passed to -procedures via the \fIobjc\fR or \fInamePtr\fR arguments. -The \fIdbName\fR and \fIdbClass\fR fields are used by \fBTk_InitOptions\fR -to look up a default value for this option in the option database; if -\fIdbName\fR is NULL then the option database is not used by -\fBTk_InitOptions\fR for this option. The \fIdefValue\fR field -specifies a default value for this configuration option if no -value is specified in the option database. The \fIobjOffset\fR and -\fIinternalOffset\fR fields indicate where to store the value of this -option in widget records (more on this below); values for the \fIobjOffset\fR -and \fIinternalOffset\fR fields should always be generated with the -\fBTk_Offset\fR macro. -The \fIflags\fR field contains additional information -to control the processing of this configuration option (see below -for details). -\fIClientData\fR provides additional type-specific data needed -by certain types. For instance, for TK_OPTION_COLOR types, -\fIclientData\fR is a string giving the default value to use on -monochrome displays. See the descriptions of the different types -below for details. -The last field, \fItypeMask\fR, is used by \fBTk_SetOptions\fR to -return information about which options were modified; see the description -of \fBTk_SetOptions\fR above for details. -.PP -When \fBTk_InitOptions\fR and \fBTk_SetOptions\fR store the value of an -option into the widget record, they can do it in either of two ways. -If the \fIobjOffset\fR field of the Tk_OptionSpec is greater than -or equal to zero, then the value of the option is stored as a -(Tcl_Obj *) at the location in the widget record given by \fIobjOffset\fR. -If the \fIinternalOffset\fR field of the Tk_OptionSpec is -greater than or equal to zero, then the value of the option is stored -in a type-specific internal form at the location in the widget record -given by \fIinternalOffset\fR. For example, if the option's type is -TK_OPTION_INT then the internal form is an integer. If the -\fIobjOffset\fR or \fIinternalOffset\fR field is negative then the -value is not stored in that form. At least one of the offsets must be -greater than or equal to zero. -.PP -The \fIflags\fR field consists of one or more bits ORed together. At -present only a single flag is supported: TK_OPTION_NULL_OK. If -this bit is set for an option then an empty string will be accepted as -the value for the option and the resulting internal form will be a -NULL pointer, a zero value, 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_CUSTOM\fR -This option allows applications to define new option types. The -clientData field of the entry points to a structure defining the new -option type. See the section CUSTOM OPTION TYPES below for details. -.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. This option type supports the TK_OPTION_NULL_OK -flag; if a NULL value is set, the internal representation is set to zero. -.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. This option -type supports the TK_OPTION_NULL_OK flag; if a NULL value is set, the -internal representation is set to zero. -.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. This option type supports the TK_OPTION_NULL_OK -flag; if the empty string is specified as the value for the option, -the integer relief value is set to TK_RELIEF_NULL. -.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, you can 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 "CUSTOM OPTION TYPES" -.PP -Applications can extend the built-in configuration types with -additional configuration types by writing procedures to parse, print, -free, and restore saved copies of the type and creating a structure -pointing to those procedures: -.CS -typedef struct Tk_ObjCustomOption { - char *name; - Tk_CustomOptionSetProc *\fIsetProc\fR; - Tk_CustomOptionGetProc *\fIgetProc\fR; - Tk_CustomOptionRestoreProc *\fIrestoreProc\fR; - Tk_CustomOptionFreeProc *\fIfreeProc\fR; - ClientData \fIclientData\fR; -} Tk_ObjCustomOption; - -typedef int Tk_CustomOptionSetProc( - ClientData \fIclientData\fR, - Tcl_Interp *\fIinterp\fR, - Tk_Window \fItkwin\fR, - Tcl_Obj **\fIvaluePtr\fR, - char *\fIrecordPtr\fR, - int \fIinternalOffset\fR, - char *\fIsaveInternalPtr\fR, - int \fIflags\fR); - -typedef Tcl_Obj *Tk_CustomOptionGetProc( - ClientData \fIclientData\fR, - Tk_Window \fItkwin\fR, - char *\fIrecordPtr\fR, - int \fIinternalOffset\fR); - -typedef void Tk_CustomOptionRestoreProc( - ClientData \fIclientData\fR, - Tk_Window \fItkwin\fR, - char *\fIinternalPtr\fR, - char *\fIsaveInternalPtr\fR); - -typedef void Tk_CustomOptionFreeProc( - ClientData \fIclientData\fR, - Tk_Window \fItkwin\fR, - char *\fIinternalPtr\fR); -.CE -.PP -The Tk_ObjCustomOption structure contains six fields: a name -for the custom option type; pointers to the four procedures; and a -\fIclientData\fR value to be passed to those procedures when they are -invoked. The \fIclientData\fR value typically points to a structure -containing information that is needed by the procedures when they are -parsing and printing options. \fIRestoreProc\fR and \fIfreeProc\fR -may be NULL, indicating that no function should be called for those -operations. -.PP -The \fIsetProc\fR procedure is invoked by \fBTk_SetOptions\fR to -convert a Tcl_Obj into an internal representation and store the -resulting value in the widget record. The arguments are: -.RS -.TP -\fIclientData\fR -A copy of the \fIclientData\fR field in the Tk_ObjCustomOption -structure. -.TP -\fIinterp\fR -A pointer to a Tcl interpreter, used for error reporting. -.TP -\fITkwin\fR -A copy of the \fItkwin\fR argument to \fBTk_SetOptions\fR -.TP -\fIvaluePtr\fR -A pointer to a reference to a Tcl_Obj describing the new value for the -option; it could have been specified explicitly in the call to -\fBTk_SetOptions\fR or it could come from the option database or a -default. If the objOffset for the option is non-negative (the option -value is stored as a (Tcl_Obj *) in the widget record), the Tcl_Obj -pointer referenced by \fIvaluePtr\fR is the pointer that will be -stored at the objOffset for the option. \fISetProc\fR may modify the -value if necessary; for example, \fIsetProc\fR may change the value to -NULL to support the TK_OPTION_NULL_OK flag. -.TP -\fIrecordPtr\fR -A pointer to the start of the widget record to modify. -.TP -\fIinternalOffset\fR -Offset in bytes from the start of the widget record to the location -where the internal representation of the option value is to be placed. -.TP -\fIsaveInternalPtr\fR -A pointer to storage allocated in a Tk_SavedOptions structure for the -internal representation of the original option value. Before setting -the option to its new value, \fIsetProc\fR should set the value -referenced by \fIsaveInternalPtr\fR to the original value of the -option in order to support \fBTk_RestoreSavedOptions\fR. -.TP -\fIflags\fR -A copy of the \fIflags\fR field in the Tk_OptionSpec structure for the -option -.RE -.PP -\fISetProc\fR returns a standard Tcl result: TCL_OK to indicate successful -processing, or TCL_ERROR to indicate a failure of any kind. An error -message may be left in the Tcl interpreter given by \fIinterp\fR in -the case of an error. -.PP -The \fIgetProc\fR procedure is invoked by \fBTk_GetOptionValue\fR and -\fBTk_GetOptionInfo\fR to retrieve a Tcl_Obj representation of the -internal representation of an option. The \fIclientData\fR argument -is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption -structure. \fITkwin\fR is a copy of the \fItkwin\fR argument to -\fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR. \fIRecordPtr\fR -is a pointer to the beginning of the widget record to query. -\fIInternalOffset\fR is the offset in bytes from the beginning of the -widget record to the location where the internal representation of the -option value is stored. \fIGetProc\fR must return a pointer to a -Tcl_Obj representing the value of the option. -.PP -The \fIrestoreProc\fR procedure is invoked by -\fBTk_RestoreSavedOptions\fR to restore a previously saved internal -representation of a custom option value. The \fIclientData\fR argument -is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption -structure. \fITkwin\fR is a copy of the \fItkwin\fR argument to -\fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR. \fIInternalPtr\fR -is a pointer to the location where internal representation of the -option value is stored. -\fISaveInternalPtr\fR is a pointer to the saved value. -\fIRestoreProc\fR must copy the value from \fIsaveInternalPtr\fR to -\fIinternalPtr\fR to restore the value. \fIRestoreProc\fR need not -free any memory associated with either \fIinternalPtr\fR or -\fIsaveInternalPtr\fR; \fIfreeProc\fR will be invoked to free that -memory if necessary. \fIRestoreProc\fR has no return value. -.PP -The \fIfreeProc\fR procedure is invoked by \fBTk_SetOptions\fR and -\fBTk_FreeSavedOptions\fR to free any storage allocated for the -internal representation of a custom option. The \fIclientData\fR argument -is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption -structure. \fITkwin\fR is a copy of the \fItkwin\fR argument to -\fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR. \fIInternalPtr\fR -is a pointer to the location where the internal representation of the -option value is stored. The \fIfreeProc\fR must free any storage -associated with the option. \fIFreeProc\fR has no return value. - - -.SH KEYWORDS -anchor, bitmap, boolean, border, color, configuration option, -cursor, double, font, integer, justify, -pixels, relief, screen distance, synonym diff --git a/tcl/doc/SetVisual.3 b/tcl/doc/SetVisual.3 deleted file mode 100644 index 8895d3a36f..0000000000 --- a/tcl/doc/SetVisual.3 +++ /dev/null @@ -1,54 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_SetWindowVisual 3 4.0 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_SetWindowVisual \- change visual characteristics of window -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -int -\fBTk_SetWindowVisual\fR(\fItkwin, visual, depth, colormap\fR) -.SH ARGUMENTS -.AS "Tk_Window int" colormap -.AP Tk_Window tkwin in -Token for window. -.AP Visual *visual in -New visual type to use for \fItkwin\fR. -.AP "int" depth in -Number of bits per pixel desired for \fItkwin\fR. -.AP Colormap colormap in -New colormap for \fItkwin\fR, which must be compatible with -\fIvisual\fR and \fIdepth\fR. -.BE - -.SH DESCRIPTION -.PP -When Tk creates a new window it assigns it the default visual -characteristics (visual, depth, and colormap) for its screen. -\fBTk_SetWindowVisual\fR may be called to change them. -\fBTk_SetWindowVisual\fR must be called before the window has -actually been created in X (e.g. before \fBTk_MapWindow\fR or -\fBTk_MakeWindowExist\fR has been invoked for the window). -The safest thing is to call \fBTk_SetWindowVisual\fR immediately -after calling \fBTk_CreateWindow\fR. -If \fItkwin\fR has already been created before \fBTk_SetWindowVisual\fR -is called then it returns 0 and doesn't make any changes; otherwise -it returns 1 to signify that the operation -completed successfully. -.PP -Note: \fBTk_SetWindowVisual\fR should not be called if you just want -to change a window's colormap without changing its visual or depth; -call \fBTk_SetWindowColormap\fR instead. - -.SH KEYWORDS -colormap, depth, visual diff --git a/tcl/doc/StrictMotif.3 b/tcl/doc/StrictMotif.3 deleted file mode 100644 index 24c99051a2..0000000000 --- a/tcl/doc/StrictMotif.3 +++ /dev/null @@ -1,41 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_StrictMotif 3 4.0 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_StrictMotif \- Return value of tk_strictMotif variable -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -int -\fBTk_StrictMotif\fR(\fItkwin\fR) -.SH ARGUMENTS -.AS Tk_Window tkwin -.AP Tk_Window tkwin in -Token for window. -.BE - -.SH DESCRIPTION -.PP -This procedure returns the current value of the \fBtk_strictMotif\fR -variable in the interpreter associated with \fItkwin\fR's application. -The value is returned as an integer that is either 0 or 1. -1 means that strict Motif compliance has been requested, so anything -that is not part of the Motif specification should be avoided. -0 means that ``Motif-like'' is good enough, and extra features -are welcome. -.PP -This procedure uses a link to the Tcl variable to provide much -faster access to the variable's value than could be had by calling -\fBTcl_GetVar\fR. - -.SH KEYWORDS -Motif compliance, tk_strictMotif variable diff --git a/tcl/doc/TextLayout.3 b/tcl/doc/TextLayout.3 deleted file mode 100644 index ba1273c5c9..0000000000 --- a/tcl/doc/TextLayout.3 +++ /dev/null @@ -1,280 +0,0 @@ -'\" -'\" 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$ -'\" -.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 \fR -.sp -Tk_TextLayout -\fBTk_ComputeTextLayout(\fItkfont, string, numChars, wrapLength, justify, flags, widthPtr, heightPtr\fB)\fR -.sp -void -\fBTk_FreeTextLayout(\fIlayout\fB)\fR -.sp -void -\fBTk_DrawTextLayout(\fIdisplay, drawable, gc, layout, x, y, firstChar, lastChar\fB)\fR -.sp -void -\fBTk_UnderlineTextLayout(\fIdisplay, drawable, gc, layout, x, y, underline\fB)\fR -.sp -int -\fBTk_PointToChar(\fIlayout, x, y\fB)\fR -.sp -int -\fBTk_CharBbox(\fIlayout, index, xPtr, yPtr, widthPtr, heightPtr\fB)\fR -.sp -int -\fBTk_DistanceToTextLayout(\fIlayout, x, y\fB)\fR -.sp -int -\fBTk_IntersectTextLayout(\fIlayout, x, y, width, height\fB)\fR -.sp -void -\fBTk_TextLayoutToPostscript(\fIinterp, layout\fB)\fR - -.SH ARGUMENTS -.AS Tk_TextLayout "*xPtr, *yPtr" -.AP Tk_Font tkfont in -Font to use when constructing and displaying a text layout. The -\fItkfont\fR must remain valid for the lifetime of the text layout. Must -have been returned by a previous call to \fBTk_GetFont\fR. -.AP "const char" *string in -Potentially multi-line string whose dimensions are to be computed and -stored in the text layout. The \fIstring\fR must remain valid for the -lifetime of the text layout. -.AP int numChars in -The number of characters to consider from \fIstring\fR. If -\fInumChars\fR is less than 0, then assumes \fIstring\fR is null -.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 -newline/return character is encountered. -.AP Tk_Justify justify in -How to justify the lines in a multi-line text layout. Possible values -are TK_JUSTIFY_LEFT, TK_JUSTIFY_CENTER, or TK_JUSTIFY_RIGHT. If the text -layout only occupies a single line, then \fIjustify\fR is irrelevant. -.AP int flags in -Various flag bits OR-ed together. TK_IGNORE_TABS means that tab characters -should not be expanded to the next tab stop. TK_IGNORE_NEWLINES means that -newline/return characters should not cause a line break. If either tabs or -newlines/returns are ignored, then they will be treated as regular -characters, being measured and displayed in a platform-dependent manner as -described in \fBTk_MeasureChars\fR, and will not have any special behaviors. -.AP int *widthPtr out -If non-NULL, filled with either the width, in pixels, of the widest -line in the text layout, or the width, in pixels, of the bounding box for the -character specified by \fIindex\fR. -.AP int *heightPtr out -If non-NULL, filled with either the total height, in pixels, of all -the lines in the text layout, or the height, in pixels, of the bounding -box for the character specified by \fIindex\fR. -.AP Tk_TextLayout layout in -A token that represents the cached layout information about the single-font, -multi-line, justified piece of text. This token is returned by -\fBTk_ComputeTextLayout\fR. -.AP Display *display in -Display on which to draw. -.AP Drawable drawable in -Window or pixmap in which to draw. -.AP GC gc in -Graphics context to use for drawing text layout. The font selected in -this GC must correspond to the \fItkfont\fR used when constructing the -text layout. -.AP int "x, y" in -Point, in pixels, at which to place the upper-left hand corner of the -text layout when it is being drawn, or the coordinates of a point (with -respect to the upper-left hand corner of the text layout) to check -against the text layout. -.AP int firstChar in -The index of the first character to draw from the given text layout. -The number 0 means to draw from the beginning. -.AP int lastChar in -The index of the last character up to which to draw. The character -specified by \fIlastChar\fR itself will not be drawn. A number less -than 0 means to draw all characters in the text layout. -.AP int underline in -Index of the single character to underline in the text layout, or a number -less than 0 for no underline. -.AP int index in -The index of the character whose bounding box is desired. The bounding -box is computed with respect to the upper-left hand corner of the text layout. -.AP int "*xPtr, *yPtr" out -Filled with the upper-left hand corner, in pixels, of the bounding box -for the character specified by \fIindex\fR. Either or both \fIxPtr\fR -and \fIyPtr\fR may be NULL, in which case the corresponding value -is not calculated. -.AP int "width, height" in -Specifies the width and height, in pixels, of the rectangular area to -compare for intersection against the text layout. -.AP Tcl_Interp *interp out -Postscript code that will print the text layout is appended to -\fIinterp->result\fR. -.BE - -.SH DESCRIPTION -.PP -These routines are for measuring and displaying single-font, multi-line, -justified text. To measure and display simple single-font, single-line -strings, refer to the documentation for \fBTk_MeasureChars\fR. There is -no programming interface in the core of Tk that supports multi-font, -multi-line text; support for that behavior must be built on top of -simpler layers. -.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 -display a single-font, multi-line, justified \fIstring\fR of text and -returns a Tk_TextLayout token that holds this information. This token is -used in subsequent calls to procedures such as \fBTk_DrawTextLayout\fR, -\fBTk_DistanceToTextLayout\fR, and \fBTk_FreeTextLayout\fR. The -\fIstring\fR and \fItkfont\fR used when computing the layout must remain -valid for the lifetime of this token. -.PP -\fBTk_FreeTextLayout\fR is called to release the storage associated with -\fIlayout\fR when it is no longer needed. A \fIlayout\fR should not be used -in any other text layout procedures once it has been released. -.PP -\fBTk_DrawTextLayout\fR uses the information in \fIlayout\fR to display a -single-font, multi-line, justified string of text at the specified location. -.PP -\fBTk_UnderlineTextLayout\fR uses the information in \fIlayout\fR to -display an underline below an individual character. This procedure does -not draw the text, just the underline. To produce natively underlined -text, an underlined font should be constructed and used. All characters, -including tabs, newline/return characters, and spaces at the ends of -lines, can be underlined using this method. However, the underline will -never be drawn outside of the computed width of \fIlayout\fR; the -underline will stop at the edge for any character that would extend -partially outside of \fIlayout\fR, and the underline will not be visible -at all for any character that would be located completely outside of the -layout. -.PP -\fBTk_PointToChar\fR uses the information in \fIlayout\fR to determine the -character closest to the given point. The point is specified with respect -to the upper-left hand corner of the \fIlayout\fR, which is considered to be -located at (0, 0). Any point whose \fIy\fR-value is less that 0 will be -considered closest to the first character in the text layout; any point -whose \fIy\fR-value is greater than the height of the text layout will be -considered closest to the last character in the text layout. Any point -whose \fIx\fR-value is less than 0 will be considered closest to the first -character on that line; any point whose \fIx\fR-value is greater than the -width of the text layout will be considered closest to the last character on -that line. The return value is the index of the character that was closest -to the point. Given a \fIlayout\fR with no characters, the value 0 will -always be returned, referring to a hypothetical zero-width placeholder -character. -.PP -\fBTk_CharBbox\fR uses the information in \fIlayout\fR to return the -bounding box for the character specified by \fIindex\fR. The width of the -bounding box is the advance width of the character, and does not include any -left or right bearing. Any character that extends partially outside of -\fIlayout\fR is considered to be truncated at the edge. Any character -that would be located completely outside of \fIlayout\fR is considered to -be zero-width and pegged against the edge. The height of the bounding -box is the line height for this font, extending from the top of the -ascent to the bottom of the descent; information about the actual height -of individual letters is not available. For measurement purposes, a -\fIlayout\fR that contains no characters is considered to contain a -single zero-width placeholder character at index 0. If \fIindex\fR was -not a valid character index, the return value is 0 and \fI*xPtr\fR, -\fI*yPtr\fR, \fI*widthPtr\fR, and \fI*heightPtr\fR are unmodified. -Otherwise, if \fIindex\fR did specify a valid, the return value is -non-zero, and \fI*xPtr\fR, \fI*yPtr\fR, \fI*widthPtr\fR, and -\fI*heightPtr\fR are filled with the bounding box information for the -character. If any of \fIxPtr\fR, \fIyPtr\fR, \fIwidthPtr\fR, or -\fIheightPtr\fR are NULL, the corresponding value is not calculated or -stored. -.PP -\fBTk_DistanceToTextLayout\fR computes the shortest distance in pixels from -the given point (\fIx, y\fR) to the characters in \fIlayout\fR. -Newline/return characters and non-displaying space characters that occur at -the end of individual lines in the text layout are ignored for hit detection -purposes, but tab characters are not. The return value is 0 if the point -actually hits the \fIlayout\fR. If the point didn't hit the \fIlayout\fR -then the return value is the distance in pixels from the point to the -\fIlayout\fR. -.PP -\fBTk_IntersectTextLayout\fR determines whether a \fIlayout\fR lies -entirely inside, entirely outside, or overlaps a given rectangle. -Newline/return characters and non-displaying space characters that occur -at the end of individual lines in the \fIlayout\fR are ignored for -intersection calculations. The return value is \-1 if the \fIlayout\fR is -entirely outside of the rectangle, 0 if it overlaps, and 1 if it is -entirely inside of the rectangle. -.PP -\fBTk_TextLayoutToPostscript\fR outputs code consisting of a Postscript -array of strings that represent the individual lines in \fIlayout\fR. It -is the responsibility of the caller to take the Postscript array of -strings and add some Postscript function operate on the array to render -each of the lines. The code that represents the Postscript array of -strings is appended to \fIinterp->result\fR. -.PP -.SH DISPLAY MODEL -When measuring a text layout, space characters that occur at the end of a -line are ignored. The space characters still exist and the insertion point -can be positioned amongst them, but their additional width is ignored when -justifying lines or returning the total width of a text layout. All -end-of-line space characters are considered to be attached to the right edge -of the line; this behavior is logical for left-justified text and reasonable -for center-justified text, but not very useful when editing right-justified -text. Spaces are considered variable width characters; the first space that -extends past the edge of the text layout is clipped to the edge, and any -subsequent spaces on the line are considered zero width and pegged against -the edge. Space characters that occur in the middle of a line of text are -not suppressed and occupy their normal space width. -.PP -Tab characters are not ignored for measurement calculations. If wrapping -is turned on and there are enough tabs on a line, the next tab will wrap -to the beginning of the next line. There are some possible strange -interactions between tabs and justification; tab positions are calculated -and the line length computed in a left-justified world, and then the -whole resulting line is shifted so it is centered or right-justified, -causing the tab columns not to align any more. -.PP -When wrapping is turned on, lines may wrap at word breaks (space or tab -characters) or newline/returns. A dash or hyphen character in the middle -of a word is not considered a word break. \fBTk_ComputeTextLayout\fR -always attempts to place at least one word on each line. If it cannot -because the \fIwrapLength\fR is too small, the word will be broken and as -much as fits placed on the line and the rest on subsequent line(s). If -\fIwrapLength\fR is so small that not even one character can fit on a -given line, the \fIwrapLength\fR is ignored for that line and one -character will be placed on the line anyhow. When wrapping is turned -off, only newline/return characters may cause a line break. -.PP -When a text layout has been created using an underlined \fItkfont\fR, -then any space characters that occur at the end of individual lines, -newlines/returns, and tabs will not be displayed underlined when -\fBTk_DrawTextLayout\fR is called, because those characters are never -actually drawn \- they are merely placeholders maintained in the -\fIlayout\fR. -.SH KEYWORDS -font diff --git a/tcl/doc/TkInitStubs.3 b/tcl/doc/TkInitStubs.3 deleted file mode 100644 index 3edd93555b..0000000000 --- a/tcl/doc/TkInitStubs.3 +++ /dev/null @@ -1,77 +0,0 @@ -'\" -'\" Copyright (c) 1999 Scriptics Corportation -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id$ -'\" -.so man.macros -.TH Tk_InitStubs 3 8.4 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_InitStubs \- initialize the Tk stubs mechanism -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -CONST char * -\fBTk_InitStubs\fR(\fIinterp, version, exact\fR) -.SH ARGUMENTS -.AS Tcl_Interp *interp in -.AP Tcl_Interp *interp in -Tcl interpreter handle. -.AP char *version in -A version string consisting of one or more decimal numbers -separated by dots. -.AP int exact in -Non-zero means that only the particular Tk version specified by -\fIversion\fR is acceptable. -Zero means that versions newer than \fIversion\fR are also -acceptable as long as they have the same major version number -as \fIversion\fR. -.BE -.SH INTRODUCTION -.PP -The Tcl stubs mechanism defines a way to dynamically bind -extensions to a particular Tcl implementation at run time. -the stubs mechanism requires no changes to applications -incoporating Tcl/Tk interpreters. Only developers creating -C-based Tcl/Tk extensions need to take steps to use the -stubs mechanism with their extensions. -See the \fBTcl_InitStubs\fR page for more information. -.PP -Enabling the stubs mechanism for a Tcl/Tk extension requires the following -steps: -.IP 1) 5 -Call \fBTcl_InitStubs\fR in the extension before calling any other -Tcl functions. -.IP 2) 5 -Call \fBTk_InitStubs\fR if the extension before calling any other -Tk functions. -.IP 2) 5 -Define the USE_TCL_STUBS symbol. Typically, you would include the --DUSE_TCL_STUBS flag when compiling the extension. -.IP 3) 5 -Link the extension with the Tcl and Tk stubs libraries instead of -the standard Tcl and Tk libraries. On Unix platforms, the library -names are \fIlibtclstub8.4.a\fR and \fIlibtkstub8.4.a\fR; on Windows -platforms, the library names are \fItclstub84.lib\fR and \fItkstub84.lib\fR -(adjust names with appropriate version number). -.SH DESCRIPTION -\fBTk_InitStubs\fR attempts to initialize the Tk stub table pointers -and ensure that the correct version of Tk is loaded. In addition -to an interpreter handle, it accepts as arguments a version number -and a Boolean flag indicating whether the extension requires -an exact version match or not. If \fIexact\fR is 0, then the -extension is indicating that newer versions of Tk are acceptable -as long as they have the same major version number as \fIversion\fR; -non-zero means that only the specified \fIversion\fR is acceptable. -\fBTcl_InitStubs\fR returns a string containing the actual version -of Tk satisfying the request, or NULL if the Tk version is not -acceptable, does not support the stubs mechansim, or any other -error condition occurred. -.SH "SEE ALSO" -\fBTcl_InitStubs\fR -.SH KEYWORDS -stubs diff --git a/tcl/doc/Tk_Init.3 b/tcl/doc/Tk_Init.3 deleted file mode 100644 index b9be1e227f..0000000000 --- a/tcl/doc/Tk_Init.3 +++ /dev/null @@ -1,88 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_Init 3 8.0 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_Init, Tk_SafeInit \- add Tk to an interpreter and make a new Tk application. -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -int -\fBTk_Init\fR(\fIinterp\fR) -.sp -int -\fBTk_SafeInit\fR(\fIinterp\fR) -.SH ARGUMENTS -.AP Tcl_Interp *interp in -Interpreter in which to load Tk. Tk should not already be loaded -in this interpreter. -.BE - -.SH DESCRIPTION -.PP -\fBTk_Init\fR is the package initialization procedure for Tk. -It is normally invoked by the \fBTcl_AppInit\fR procedure -for an application or by the \fBload\fR command. -\fBTk_Init\fR adds all of Tk's commands to \fIinterp\fR -and creates a new Tk application, including its main window. -If the initialization is successful \fBTk_Init\fR returns -\fBTCL_OK\fR; if there is an error it returns \fBTCL_ERROR\fR. -\fBTk_Init\fR also leaves a result or error message -in \fIinterp->result\fR. -.PP -If there is a variable \fBargv\fR in \fIinterp\fR, \fBTk_Init\fR -treats the contents of this variable as a list of options for the -new Tk application. -The options may have any of the forms documented for the -\fBwish\fR application (in fact, \fBwish\fR uses Tk_Init to process -its command-line arguments). -.PP -\fBTk_SafeInit\fR is identical to \fBTk_Init\fR except that it removes -all Tk commands that are considered unsafe. Those commands and the -reasons for their exclusion are: -.TP -\fBbell\fR -Continuous ringing of the bell is a nuisance. -.TP -\fBclipboard\fR -A malicious script could replace the contents of the clipboard with -the string \fB"rm -r *"\fR and lead to surprises when the contents of -the clipboard are pasted. -.TP -\fBgrab\fR -Grab can be used to block the user from using any other applications. -.TP -\fBmenu\fR -Menus can be used to cover the entire screen and to steal input from -the user. -.TP -\fBselection\fR -See clipboard. -.TP -\fBsend\fR -Send can be used to cause unsafe interpreters to execute commands. -.TP -\fBtk\fR -The tk command recreates the send command, which is unsafe. -.TP -\fBtkwait\fR -Tkwait can block the containing process forever -.TP -\fBtoplevel\fR -Toplevels can be used to cover the entire screen and to steal input -from the user. -.TP -\fBwm\fR -If toplevels are ever allowed, wm can be used to remove decorations, -move windows around, etc. - -.SH KEYWORDS -safe, application, initialization, load, main window diff --git a/tcl/doc/Tk_Main.3 b/tcl/doc/Tk_Main.3 deleted file mode 100644 index 72f506638e..0000000000 --- a/tcl/doc/Tk_Main.3 +++ /dev/null @@ -1,61 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_Main 3 4.0 Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_Main \- main program for Tk-based applications -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -\fBTk_Main\fR(\fIargc, argv, appInitProc\fR) -.SH ARGUMENTS -.AS Tcl_AppInitProc *appInitProc -.AP int argc in -Number of elements in \fIargv\fR. -.AP char *argv[] in -Array of strings containing command-line arguments. -.AP Tcl_AppInitProc *appInitProc in -Address of an application-specific initialization procedure. -The value for this argument is usually \fBTcl_AppInit\fR. -.BE - -.SH DESCRIPTION -.PP -\fBTk_Main\fR acts as the main program for most Tk-based applications. -Starting with Tk 4.0 it is not called \fBmain\fR anymore because it -is part of the Tk library and having a function \fBmain\fR -in a library (particularly a shared library) causes problems on many -systems. -Having \fBmain\fR in the Tk library would also make it hard to use -Tk in C++ programs, since C++ programs must have special C++ -\fBmain\fR functions. -.PP -Normally each application contains a small \fBmain\fR function that does -nothing but invoke \fBTk_Main\fR. -\fBTk_Main\fR then does all the work of creating and running a -\fBwish\fR-like application. -.PP -When it is has finished its own initialization, but before -it processes commands, \fBTk_Main\fR calls the procedure given by -the \fIappInitProc\fR argument. This procedure provides a ``hook'' -for the application to perform its own initialization, such as defining -application-specific commands. The procedure must have an interface -that matches the type \fBTcl_AppInitProc\fR: -.CS -typedef int Tcl_AppInitProc(Tcl_Interp *\fIinterp\fR); -.CE -\fIAppInitProc\fR is almost always a pointer to \fBTcl_AppInit\fR; -for more details on this procedure, see the documentation -for \fBTcl_AppInit\fR. - -.SH KEYWORDS -application-specific initialization, command-line arguments, main program diff --git a/tcl/doc/WindowId.3 b/tcl/doc/WindowId.3 deleted file mode 100644 index c414644597..0000000000 --- a/tcl/doc/WindowId.3 +++ /dev/null @@ -1,186 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH Tk_WindowId 3 "8.4" 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_IsContainer, Tk_IsEmbedded, Tk_IsMapped, Tk_IsTopLevel, Tk_ReqWidth, Tk_ReqHeight, Tk_MinReqWidth, Tk_MinReqHeight, Tk_InternalBorderLeft, Tk_InternalBorderRight, Tk_InternalBorderTop, Tk_InternalBorderBottom, Tk_Visual, Tk_Depth, Tk_Colormap \- retrieve information from Tk's local data structure -.SH SYNOPSIS -.nf -\fB#include \fR -.sp -Window -\fBTk_WindowId\fR(\fItkwin\fR) -.sp -Tk_Window -\fBTk_Parent\fR(\fItkwin\fR) -.sp -Display * -\fBTk_Display\fR(\fItkwin\fR) -.sp -CONST char * -\fBTk_DisplayName\fR(\fItkwin\fR) -.sp -int -\fBTk_ScreenNumber\fR(\fItkwin\fR) -.sp -Screen * -\fBTk_Screen\fR(\fItkwin\fR) -.sp -int -\fBTk_X\fR(\fItkwin\fR) -.sp -int -\fBTk_Y\fR(\fItkwin\fR) -.sp -int -\fBTk_Width\fR(\fItkwin\fR) -.sp -int -\fBTk_Height\fR(\fItkwin\fR) -.sp -XWindowChanges * -\fBTk_Changes\fR(\fItkwin\fR) -.sp -XSetWindowAttributes * -\fBTk_Attributes\fR(\fItkwin\fR) -.sp -int -\fBTk_IsContainer\fR(\fItkwin\fR) -.sp -int -\fBTk_IsEmbedded\fR(\fItkwin\fR) -.sp -int -\fBTk_IsMapped\fR(\fItkwin\fR) -.sp -int -\fBTk_IsTopLevel\fR(\fItkwin\fR) -.sp -int -\fBTk_ReqWidth\fR(\fItkwin\fR) -.sp -int -\fBTk_ReqHeight\fR(\fItkwin\fR) -.sp -int -\fBTk_MinReqWidth\fR(\fItkwin\fR) -.sp -int -\fBTk_MinReqHeight\fR(\fItkwin\fR) -.sp -int -\fBTk_InternalBorderLeft\fR(\fItkwin\fR) -.sp -int -\fBTk_InternalBorderRight\fR(\fItkwin\fR) -.sp -int -\fBTk_InternalBorderTop\fR(\fItkwin\fR) -.sp -int -\fBTk_InternalBorderBottom\fR(\fItkwin\fR) -.sp -Visual * -\fBTk_Visual\fR(\fItkwin\fR) -.sp -int -\fBTk_Depth\fR(\fItkwin\fR) -.sp -Colormap -\fBTk_Colormap\fR(\fItkwin\fR) -.SH ARGUMENTS -.AS Tk_Window tkwin -.AP Tk_Window tkwin in -Token for window. -.BE - -.SH DESCRIPTION -.PP -\fBTk_WindowId\fR and the other names listed above are -all macros that return fields from Tk's local data structure -for \fItkwin\fR. None of these macros requires any -interaction with the server; it is safe to assume that -all are fast. -.PP -\fBTk_WindowId\fR returns the X identifier for \fItkwin\fR, -or \fBNULL\fR if no X window has been created for \fItkwin\fR -yet. -.PP -\fBTk_Parent\fR returns Tk's token for the logical parent of -\fItkwin\fR. The parent is the token that was specified when -\fItkwin\fR was created, or NULL for main windows. -.PP -\fBTk_Display\fR returns a pointer to the Xlib display structure -corresponding to \fItkwin\fR. \fBTk_DisplayName\fR returns an -ASCII string identifying \fItkwin\fR's display. \fBTk_ScreenNumber\fR -returns the index of \fItkwin\fR's screen among all the screens -of \fItkwin\fR's display. \fBTk_Screen\fR returns a pointer to -the Xlib structure corresponding to \fItkwin\fR's screen. -.PP -\fBTk_X\fR, \fBTk_Y\fR, \fBTk_Width\fR, and \fBTk_Height\fR -return information about \fItkwin's\fR location within its -parent and its size. The location information refers to the -upper-left pixel in the window, or its border if there is one. -The width and height information refers to the interior size -of the window, not including any border. \fBTk_Changes\fR -returns a pointer to a structure containing all of the above -information plus a few other fields. \fBTk_Attributes\fR -returns a pointer to an XSetWindowAttributes structure describing -all of the attributes of the \fItkwin\fR's window, such as background -pixmap, event mask, and so on (Tk keeps track of all this information -as it is changed by the application). Note: it is essential that -applications use Tk procedures like \fBTk_ResizeWindow\fR instead -of X procedures like \fBXResizeWindow\fR, so that Tk can keep its -data structures up-to-date. -.PP -\fBTk_IsContainer\fR returns a non-zero value if \fItkwin\fR -is a container, and that some other application may be embedding -itself inside \fItkwin\fR. -.PP -\fBTk_IsEmbedded\fR returns a non-zero value if \fItkwin\fR -is is not a free-standing window, but rather is embedded in some -other application. -.PP -\fBTk_IsMapped\fR returns a non-zero value if \fItkwin\fR -is mapped and zero if \fItkwin\fR isn't mapped. -.PP -\fBTk_IsTopLevel\fR returns a non-zero value if \fItkwin\fR -is a top-level window (its X parent is the root window of the -screen) and zero if \fItkwin\fR isn't a top-level window. -.PP -\fBTk_ReqWidth\fR and \fBTk_ReqHeight\fR return information about -the window's requested size. These values correspond to the last -call to \fBTk_GeometryRequest\fR for \fItkwin\fR. -.PP -\fBTk_MinReqWidth\fR and \fBTk_MinReqHeight\fR return information about -the window's minimum requested size. These values correspond to the last -call to \fBTk_SetMinimumRequestSize\fR for \fItkwin\fR. -.PP -\fBTk_InternalBorderLeft\fR, \fBTk_InternalBorderRight\fR, -\fBTk_InternalBorderTop\fR and \fBTk_InternalBorderBottom\fR -return the width of one side of the internal border -that has been requested for \fItkwin\fR, or 0 if no internal border was -requested. The return value is simply the last value passed to -\fBTk_SetInternalBorder\fR or \fBTk_SetInternalBorderEx\fR for \fItkwin\fR. -.PP -\fBTk_Visual\fR, \fBTk_Depth\fR, and \fBTk_Colormap\fR return -information about the visual characteristics of a window. -\fBTk_Visual\fR returns the visual type for -the window, \fBTk_Depth\fR returns the number of bits per pixel, -and \fBTk_Colormap\fR returns the current -colormap for the window. The visual characteristics are -normally set from the defaults for the window's screen, but -they may be overridden by calling \fBTk_SetWindowVisual\fR. - -.SH KEYWORDS -attributes, colormap, depth, display, height, geometry manager, -identifier, mapped, requested size, screen, top-level, -visual, width, window, x, y diff --git a/tcl/doc/bell.n b/tcl/doc/bell.n deleted file mode 100644 index 3b0e50cbd8..0000000000 --- a/tcl/doc/bell.n +++ /dev/null @@ -1,35 +0,0 @@ -'\" -'\" Copyright (c) 1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" Copyright (c) 2000 Ajuba Solutions. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id$ -'\" -.so man.macros -.TH bell n 8.4 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -bell \- Ring a display's bell -.SH SYNOPSIS -\fBbell \fR?\fB\-displayof \fIwindow\fR? ?\fB\-nice\fR? -.BE - -.SH DESCRIPTION -.PP -This command rings the bell on the display for \fIwindow\fR and -returns an empty string. -If the \fB\-displayof\fR option is omitted, the display of the -application's main window is used by default. -The command uses the current bell-related settings for the display, which -may be modified with programs such as \fBxset\fR. -.PP -If \fB\-nice\fR is not specified, this command also resets the screen saver -for the screen. Some screen savers will ignore this, but others will reset -so that the screen becomes visible again. - -.SH KEYWORDS -beep, bell, ring diff --git a/tcl/doc/bind.n b/tcl/doc/bind.n deleted file mode 100644 index 82b3e1b6d6..0000000000 --- a/tcl/doc/bind.n +++ /dev/null @@ -1,531 +0,0 @@ -'\" -'\" 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$ -'\" -.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 -\fBbind\fI tag sequence\fR -.sp -\fBbind\fI tag sequence script\fR -.sp -\fBbind\fI tag sequence \fB+\fIscript\fR -.BE - -.SH INTRODUCTION -.PP -The \fBbind\fR command associates Tcl scripts with X events. -If all three arguments are specified, \fBbind\fR will -arrange for \fIscript\fR (a Tcl script) to be evaluated whenever -the event(s) given by \fIsequence\fR occur in the window(s) -identified by \fItag\fR. -If \fIscript\fR is prefixed with a ``+'', then it is appended to -any existing binding for \fIsequence\fR; otherwise \fIscript\fR replaces -any existing binding. -If \fIscript\fR is an empty string then the current binding for -\fIsequence\fR is destroyed, leaving \fIsequence\fR unbound. -In all of the cases where a \fIscript\fR argument is provided, -\fBbind\fR returns an empty string. -.PP -If \fIsequence\fR is specified without a \fIscript\fR, then the -script currently bound to \fIsequence\fR is returned, or -an empty string is returned if there is no binding for \fIsequence\fR. -If neither \fIsequence\fR nor \fIscript\fR is specified, then the -return value is a list whose elements are all the sequences -for which there exist bindings for \fItag\fR. -.PP -The \fItag\fR argument determines which window(s) the binding applies to. -If \fItag\fR begins with a dot, as in \fB.a.b.c\fR, then it must -be the path name for a window; otherwise it may be an arbitrary -string. -Each window has an associated list of tags, and a binding applies -to a particular window if its tag is among those specified for -the window. -Although the \fBbindtags\fR command may be used to assign an -arbitrary set of binding tags to a window, the default binding -tags provide the following behavior: -.IP -If a tag is the name of an internal window the binding applies -to that window. -.IP -If the tag is the name of a toplevel window the binding applies -to the toplevel window and all its internal windows. -.IP -If the tag is the name of a class of widgets, such as \fBButton\fR, -the binding applies to all widgets in that class; -.IP -If \fItag\fR has the value \fBall\fR, -the binding applies to all windows in the application. - -.SH "EVENT PATTERNS" -.PP -The \fIsequence\fR argument specifies a sequence of one or more -event patterns, with optional white space between the patterns. Each -.VS -event pattern may -take one of three forms. In the simplest case it is a single -.VE -printing ASCII character, such as \fBa\fR or \fB[\fR. The character -may not be a space character or the character \fB<\fR. This form of -pattern matches a \fBKeyPress\fR event for the particular -character. The second form of pattern is longer but more general. -It has the following syntax: -.CS -\fB<\fImodifier-modifier-type-detail\fB>\fR -.CE -The entire event pattern is surrounded by angle brackets. -Inside the angle brackets are zero or more modifiers, an event -type, and an extra piece of information (\fIdetail\fR) identifying -a particular button or keysym. Any of the fields may be omitted, -as long as at least one of \fItype\fR and \fIdetail\fR is present. -The fields must be separated by white space or dashes. -.VS -.PP -The third form of pattern is used to specify a user-defined, named virtual -event. It has the following syntax: -.CS -\fB<<\fIname\fB>>\fR -.CE -The entire virtual event pattern is surrounded by double angle brackets. -Inside the angle brackets is the user-defined name of the virtual event. -Modifiers, such as \fBShift\fR or \fBControl\fR, may not be combined with a -virtual event to modify it. Bindings on a virtual event may be created -before the virtual event is defined, and if the definition of a virtual -event changes dynamically, all windows bound to that virtual event will -respond immediately to the new definition. -.VE -.SH "MODIFIERS" -.PP -Modifiers consist of any of the following values: -.DS -.ta 6c -\fBControl\fR \fBMod2, M2\fR -\fBShift\fR \fBMod3, M3\fR -\fBLock\fR \fBMod4, M4\fR -\fBButton1, B1\fR \fBMod5, M5\fR -\fBButton2, B2\fR \fBMeta, M\fR -\fBButton3, B3\fR \fBAlt\fR -\fBButton4, B4\fR \fBDouble\fR -\fBButton5, B5\fR \fBTriple\fR -\fBMod1, M1\fR \fBQuadruple\fR -.DE -Where more than one value is listed, separated by commas, the values -are equivalent. -Most of the modifiers have the obvious X meanings. -For example, \fBButton1\fR requires that -button 1 be depressed when the event occurs. -For a binding to match a given event, the modifiers in the event -must include all of those specified in the event pattern. -An event may also contain additional modifiers not specified in -the binding. -For example, if button 1 is pressed while the shift and control keys -are down, the pattern \fB\fR will match -the event, but \fB\fR will not. -If no modifiers are specified, then any combination of modifiers may -be present in the event. -.PP -\fBMeta\fR and \fBM\fR refer to whichever of the -\fBM1\fR through \fBM5\fR modifiers is associated with the meta -key(s) on the keyboard (keysyms \fBMeta_R\fR and \fBMeta_L\fR). -If there are no meta keys, or if they are not associated with any -modifiers, then \fBMeta\fR and \fBM\fR will not match any events. -Similarly, the \fBAlt\fR modifier refers to whichever modifier -is associated with the alt key(s) on the keyboard (keysyms -\fBAlt_L\fR and \fBAlt_R\fR). -.PP -The \fBDouble\fR, \fBTriple\fR and \fBQuadruple\fR modifiers are a -convenience for specifying double mouse clicks and other repeated -events. They cause a particular event pattern to be repeated 2, 3 or 4 -times, and also place a time and space requirement on the sequence: for a -sequence of events to match a \fBDouble\fR, \fBTriple\fR or \fBQuadruple\fR -pattern, all of the events must occur close together in time and without -substantial mouse motion in between. For example, \fB\fR -is equivalent to \fB\fR with the extra time and space -requirement. - -.SH "EVENT TYPES" -.PP -The \fItype\fR field may be any of the standard X event types, with a -few extra abbreviations. 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 -.ta 5c 10c -\fBActivate Destroy Map -ButtonPress, Button Enter MapRequest -ButtonRelease Expose Motion -Circulate FocusIn MouseWheel -CirculateRequest FocusOut Property -Colormap Gravity Reparent -Configure KeyPress, Key ResizeRequest -ConfigureRequest KeyRelease Unmap -Create Leave Visibility -Deactivate\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; -in the first case, it refers to a button being pressed or released, -while in the second it refers to some other button that is already -depressed when the matching event occurs. If a button -number is given then \fItype\fR may be omitted: if will default -to \fBButtonPress\fR. For example, the specifier \fB<1>\fR -is equivalent to \fB\fR. -.PP -If the event type is \fBKeyPress\fR or \fBKeyRelease\fR, then -\fIdetail\fR may be specified in the form of an X keysym. Keysyms -are textual specifications for particular keys on the keyboard; -they include all the alphanumeric ASCII characters (e.g. ``a'' is -the keysym for the ASCII character ``a''), plus descriptions for -non-alphanumeric characters (``comma'' is the keysym for the comma -character), plus descriptions for all the non-ASCII keys on the -keyboard (``Shift_L'' is the keysm for the left shift key, and -``F1'' is the keysym for the F1 function key, if it exists). The -complete list of keysyms is not presented here; it is -available in other X documentation and may vary from system to -system. -If necessary, you can use the \fB%K\fR notation described below -to print out the keysym name for a particular key. -If a keysym \fIdetail\fR is given, then the -\fItype\fR field may be omitted; it will default to \fBKeyPress\fR. -For example, \fB\fR is equivalent to -\fB\fR. - -.SH "BINDING SCRIPTS AND SUBSTITUTIONS" -.PP -The \fIscript\fR argument to \fBbind\fR is a Tcl script, -which will be executed whenever the given event sequence occurs. -\fICommand\fR will be executed in the same interpreter that the -\fBbind\fR command was executed in, and it will run at global -level (only global variables will be accessible). -If \fIscript\fR contains -any \fB%\fR characters, then the script will not be -executed directly. Instead, a new script will be -generated by replacing each \fB%\fR, and the character following -it, with information from the current event. The replacement -depends on the character following the \fB%\fR, as defined in the -list below. Unless otherwise indicated, the -replacement string is the decimal value of the given field from -the current event. -Some of the substitutions are only valid for -certain types of events; if they are used for other types of events -the value substituted is undefined. -.IP \fB%%\fR 5 -Replaced with a single percent. -.IP \fB%#\fR 5 -The number of the last client request processed by the server -(the \fIserial\fR field from the event). Valid for all event -types. -.IP \fB%a\fR 5 -The \fIabove\fR field from the event, -formatted as a hexadecimal number. -Valid only for \fBConfigure\fR events. -.IP \fB%b\fR 5 -The number of the button that was pressed or released. Valid only -for \fBButtonPress\fR and \fBButtonRelease\fR events. -.IP \fB%c\fR 5 -The \fIcount\fR field from the event. Valid only for \fBExpose\fR events. -.IP \fB%d\fR 5 -The \fIdetail\fR field from the event. The \fB%d\fR is replaced by -a string identifying the detail. For \fBEnter\fR, -\fBLeave\fR, \fBFocusIn\fR, and \fBFocusOut\fR events, -the string will be one of the following: -.RS -.DS -.ta 6c -\fBNotifyAncestor NotifyNonlinearVirtual -NotifyDetailNone NotifyPointer -NotifyInferior NotifyPointerRoot -NotifyNonlinear NotifyVirtual\fR -.DE -For \fBConfigureRequest\fR events, the string will be one of: -.DS -.ta 6c -\fBAbove Opposite -Below None -BottomIf TopIf\fR -.DE -For events other than these, the substituted string is undefined. -.RE -.IP \fB%f\fR 5 -The \fIfocus\fR field from the event (\fB0\fR or \fB1\fR). Valid only -for \fBEnter\fR and \fBLeave\fR events. -.IP \fB%h\fR 5 -.VS -The \fIheight\fR field from the event. Valid for the \fBConfigure\fR, -\fBConfigureRequest\fR, \fBCreate\fR, \fBResizeRequest\fR, and -\fBExpose\fR events. -.VE -.IP \fB%i\fR 5 -The \fIwindow\fR field from the event, represented as a hexadecimal -integer. -.IP \fB%k\fR 5 -The \fIkeycode\fR field from the event. Valid only for \fBKeyPress\fR -and \fBKeyRelease\fR events. -.IP \fB%m\fR 5 -The \fImode\fR field from the event. The substituted string is one of -\fBNotifyNormal\fR, \fBNotifyGrab\fR, \fBNotifyUngrab\fR, or -.VS -\fBNotifyWhileGrabbed\fR. Valid only for \fBEnter\fR, -\fBFocusIn\fR, \fBFocusOut\fR, and \fBLeave\fR events. -.VE -.IP \fB%o\fR 5 -The \fIoverride_redirect\fR field from the event. Valid only for -\fBMap\fR, \fBReparent\fR, and \fBConfigure\fR events. -.IP \fB%p\fR 5 -The \fIplace\fR field from the event, substituted as one of the -strings \fBPlaceOnTop\fR or \fBPlaceOnBottom\fR. Valid only -for \fBCirculate\fR and \fBCirculateRequest\fR events. -.IP \fB%s\fR 5 -The \fIstate\fR field from the event. For \fBButtonPress\fR, -\fBButtonRelease\fR, \fBEnter\fR, \fBKeyPress\fR, \fBKeyRelease\fR, -\fBLeave\fR, and \fBMotion\fR events, a decimal string -is substituted. For \fBVisibility\fR, one of the strings -\fBVisibilityUnobscured\fR, \fBVisibilityPartiallyObscured\fR, -and \fBVisibilityFullyObscured\fR is substituted. -.IP \fB%t\fR 5 -The \fItime\fR field from the event. Valid only for events that -contain a \fItime\fR field. -.IP \fB%w\fR 5 -The \fIwidth\fR field from the event. Valid only for -.VS -\fBConfigure\fR, \fBConfigureRequest\fR, \fBCreate\fR, -\fBResizeRequest\fR, and \fBExpose\fR events. -.VE -.IP \fB%x\fR 5 -The \fIx\fR field from the event. Valid only for events containing -an \fIx\fR field. -.IP \fB%y\fR 5 -The \fIy\fR field from the event. Valid only for events containing -a \fIy\fR field. -.IP \fB%A\fR 5 -Substitutes the ASCII character corresponding to the event, or -the empty string if the event doesn't correspond to an ASCII character -(e.g. the shift key was pressed). \fBXLookupString\fR does all the -work of translating from the event to an ASCII character. -Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events. -.IP \fB%B\fR 5 -The \fIborder_width\fR field from the event. Valid only for -\fBConfigure\fR, \fBConfigureRequest\fR, and \fBCreate\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 -number. Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events. -.IP \fB%R\fR 5 -The \fIroot\fR window identifier from the event. Valid only for -events containing a \fIroot\fR field. -.IP \fB%S\fR 5 -The \fIsubwindow\fR window identifier from the event, -formatted as a hexadecimal number. -Valid only for events containing a \fIsubwindow\fR field. -.IP \fB%T\fR 5 -The \fItype\fR field from the event. Valid for all event types. -.IP \fB%W\fR 5 -The path name of the window to which the event was reported (the -\fIwindow\fR field from the event). Valid for all event types. -.IP \fB%X\fR 5 -The \fIx_root\fR field from the event. -If a virtual-root window manager is being used then the substituted -value is the corresponding x-coordinate in the virtual root. -Valid only for -\fBButtonPress\fR, \fBButtonRelease\fR, \fBKeyPress\fR, \fBKeyRelease\fR, -and \fBMotion\fR events. -.IP \fB%Y\fR 5 -The \fIy_root\fR field from the event. -If a virtual-root window manager is being used then the substituted -value is the corresponding y-coordinate in the virtual root. -Valid only for -\fBButtonPress\fR, \fBButtonRelease\fR, \fBKeyPress\fR, \fBKeyRelease\fR, -and \fBMotion\fR events. -.LP -The replacement string for a %-replacement is formatted as a proper -Tcl list element. -This means that it will be surrounded with braces -if it contains spaces, or special characters such as \fB$\fR and -\fB{\fR may be preceded by backslashes. -This guarantees that the string will be passed through the Tcl -parser when the binding script is evaluated. -Most replacements are numbers or well-defined strings such -as \fBAbove\fR; for these replacements no special formatting -is ever necessary. -The most common case where reformatting occurs is for the \fB%A\fR -substitution. For example, if \fIscript\fR is -.CS -\fBinsert\0%A\fR -.CE -and the character typed is an open square bracket, then the script -actually executed will be -.CS -\fBinsert\0\e[\fR -.CE -This will cause the \fBinsert\fR to receive the original replacement -string (open square bracket) as its first argument. -If the extra backslash hadn't been added, Tcl would not have been -able to parse the script correctly. - -.SH "MULTIPLE MATCHES" -.PP -It is possible for several bindings to match a given X event. -If the bindings are associated with different \fItag\fR's, -then each of the bindings will be executed, in order. -By default, a binding for the widget will be executed first, followed -by a class binding, a binding for its toplevel, and -an \fBall\fR binding. -The \fBbindtags\fR command may be used to change this order for -a particular window or to associate additional binding tags with -the window. -.PP -The \fBcontinue\fR and \fBbreak\fR commands may be used inside a -binding script to control the processing of matching scripts. -If \fBcontinue\fR is invoked, then the current binding script -is terminated but Tk will continue processing binding scripts -associated with other \fItag\fR's. -If the \fBbreak\fR command is invoked within a binding script, -then that script terminates and no other scripts will be invoked -for the event. -.PP -If more than one binding matches a particular event and they -have the same \fItag\fR, then the most specific binding -is chosen and its script is evaluated. -The following tests are applied, in order, to determine which of -several matching sequences is more specific: -(a) an event pattern that specifies a specific button or key is more specific -than one that doesn't; -(b) a longer sequence (in terms of number -of events matched) is more specific than a shorter sequence; -(c) if the modifiers specified in one pattern are a subset of the -modifiers in another pattern, then the pattern with more modifiers -is more specific. -(d) a virtual event whose physical pattern matches the sequence is less -specific than the same physical pattern that is not associated with a -virtual event. -(e) given a sequence that matches two or more virtual events, one -of the virtual events will be chosen, but the order is undefined. -.PP -If the matching sequences contain more than one event, then tests -(c)-(e) are applied in order from the most recent event to the least recent -event in the sequences. If these tests fail to determine a winner, then the -most recently registered sequence is the winner. -.PP -If there are two (or more) virtual events that are both triggered by the -same sequence, and both of those virtual events are bound to the same window -tag, then only one of the virtual events will be triggered, and it will -be picked at random: -.CS -event add <> -event add <> -event add <> -bind Entry <> {puts Paste} -bind Entry <> {puts Scroll} -.CE -If the user types Control-y, the \fB<>\fR binding -will be invoked, but if the user presses button 2 then one of -either the \fB<>\fR or the \fB<>\fR bindings will -be invoked, but exactly which one gets invoked is undefined. -.PP -If an X event does not match any of the existing bindings, then the -event is ignored. -An unbound event is not considered to be an error. - -.SH "MULTI-EVENT SEQUENCES AND IGNORED EVENTS" -.PP -When a \fIsequence\fR specified in a \fBbind\fR command contains -more than one event pattern, then its script is executed whenever -the recent events (leading up to and including the current event) -match the given sequence. This means, for example, that if button 1 is -clicked repeatedly the sequence \fB\fR will match -each button press but the first. -If extraneous events that would prevent a match occur in the middle -of an event sequence then the extraneous events are -ignored unless they are \fBKeyPress\fR or \fBButtonPress\fR events. -For example, \fB\fR will match a sequence of -presses of button 1, even though there will be \fBButtonRelease\fR -events (and possibly \fBMotion\fR events) between the -\fBButtonPress\fR events. -Furthermore, a \fBKeyPress\fR event may be preceded by any number -of other \fBKeyPress\fR events for modifier keys without the -modifier keys preventing a match. -For example, the event sequence \fBaB\fR will match a press of the -\fBa\fR key, a release of the \fBa\fR key, a press of the \fBShift\fR -key, and a press of the \fBb\fR key: the press of \fBShift\fR is -ignored because it is a modifier key. -Finally, if several \fBMotion\fR events occur in a row, only -the last one is used for purposes of matching binding sequences. - -.SH ERRORS -.PP -If an error occurs in executing the script for a binding then the -\fBbgerror\fR mechanism is used to report the error. -The \fBbgerror\fR command will be executed at global level -(outside the context of any Tcl procedure). - -.SH "SEE ALSO" -bgerror, keysyms - -.SH KEYWORDS -form, manual diff --git a/tcl/doc/bindtags.n b/tcl/doc/bindtags.n deleted file mode 100644 index 20e5291f45..0000000000 --- a/tcl/doc/bindtags.n +++ /dev/null @@ -1,81 +0,0 @@ -'\" -'\" 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$ -'\" -.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 -.SH SYNOPSIS -\fBbindtags \fIwindow \fR?\fItagList\fR? -.BE - -.SH DESCRIPTION -.PP -When a binding is created with the \fBbind\fR command, it is -associated either with a particular window such as \fB.a.b.c\fR, -a class name such as \fBButton\fR, the keyword \fBall\fR, or any -other string. -All of these forms are called \fIbinding tags\fR. -Each window contains a list of binding tags that determine how -events are processed for the window. -When an event occurs in a window, it is applied to each of the -window's tags in order: for each tag, the most specific binding -that matches the given tag and event is executed. -See the \fBbind\fR command for more information on the matching -process. -.PP -By default, each window has four binding tags consisting of the -name of the window, the window's class name, the name of the window's -nearest toplevel ancestor, and \fBall\fR, in that order. -Toplevel windows have only three tags by default, since the toplevel -name is the same as that of the window. -The \fBbindtags\fR command allows the binding tags for a window to be -read and modified. -.PP -If \fBbindtags\fR is invoked with only one argument, then the -current set of binding tags for \fIwindow\fR is returned as a list. -If the \fItagList\fR argument is specified to \fBbindtags\fR, -then it must be a proper list; the tags for \fIwindow\fR are changed -to the elements of the list. -The elements of \fItagList\fR may be arbitrary strings; however, -any tag starting with a dot is treated as the name of a window; if -no window by that name exists at the time an event is processed, -then the tag is ignored for that event. -The order of the elements in \fItagList\fR determines the order in -which binding scripts are executed in response to events. -For example, the command -.CS -\fBbindtags .b {all . Button .b}\fR -.CE -reverses the order in which binding scripts will be evaluated for -a button named \fB.b\fR so that \fBall\fR bindings are invoked -first, following by bindings for \fB.b\fR's toplevel (``.''), followed by -class bindings, followed by bindings for \fB.b\fR. -If \fItagList\fR is an empty list then the binding tags for \fIwindow\fR -are returned to the default state described above. -.PP -The \fBbindtags\fR command may be used to introduce arbitrary -additional binding tags for a window, or to remove standard tags. -For example, the command -.CS -\fBbindtags .b {.b TrickyButton . all}\fR -.CE -replaces the \fBButton\fR tag for \fB.b\fR with \fBTrickyButton\fR. -This means that the default widget bindings for buttons, which are -associated with the \fBButton\fR tag, will no longer apply to \fB.b\fR, -but any bindings associated with \fBTrickyButton\fR (perhaps some -new button behavior) will apply. - -.SH "SEE ALSO" -bind - -.SH KEYWORDS -binding, event, tag diff --git a/tcl/doc/bitmap.n b/tcl/doc/bitmap.n deleted file mode 100644 index 0fa1c5afda..0000000000 --- a/tcl/doc/bitmap.n +++ /dev/null @@ -1,114 +0,0 @@ -'\" -'\" 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$ -'\" -.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 -.SH SYNOPSIS -\fBimage create bitmap \fR?\fIname\fR? ?\fIoptions\fR? -.BE - -.SH DESCRIPTION -.PP -A bitmap is an image whose pixels can display either of two colors -or be transparent. -A bitmap image is defined by four things: a background color, -a foreground color, and two bitmaps, called the \fIsource\fR -and the \fImask\fR. -Each of the bitmaps specifies 0/1 values for a rectangular -array of pixels, and the two bitmaps must have the same -dimensions. -For pixels where the mask is zero, the image displays nothing, -producing a transparent effect. -For other pixels, the image displays the foreground color if -the source data is one and the background color if the source -data is zero. - -.SH "CREATING BITMAPS" -.PP -Like all images, bitmaps are created using the \fBimage create\fR -command. -Bitmaps support the following \fIoptions\fR: -.TP -\fB\-background \fIcolor\fR -Specifies a background color for the image in any of the standard -ways accepted by Tk. If this option is set to an empty string -then the background pixels will be transparent. This effect -is achieved by using the source bitmap as the mask bitmap, ignoring -any \fB\-maskdata\fR or \fB\-maskfile\fR options. -.TP -\fB\-data \fIstring\fR -Specifies the contents of the source bitmap as a string. -The string must adhere to X11 bitmap format (e.g., as generated -by the \fBbitmap\fR program). -If both the \fB\-data\fR and \fB\-file\fR options are specified, -the \fB\-data\fR option takes precedence. -.TP -\fB\-file \fIname\fR -\fIname\fR gives the name of a file whose contents define the -source bitmap. -The file must adhere to X11 bitmap format (e.g., as generated -by the \fBbitmap\fR program). -.TP -\fB\-foreground \fIcolor\fR -Specifies a foreground color for the image in any of the standard -ways accepted by Tk. -.TP -\fB\-maskdata \fIstring\fR -Specifies the contents of the mask as a string. -The string must adhere to X11 bitmap format (e.g., as generated -by the \fBbitmap\fR program). -If both the \fB\-maskdata\fR and \fB\-maskfile\fR options are specified, -the \fB\-maskdata\fR option takes precedence. -.TP -\fB\-maskfile \fIname\fR -\fIname\fR gives the name of a file whose contents define the -mask. -The file must adhere to X11 bitmap format (e.g., as generated -by the \fBbitmap\fR program). - -.SH "IMAGE COMMAND" -.PP -When a bitmap image is created, Tk also creates a new command -whose name is the same as the image. -This command may be used to invoke various operations -on the image. -It has the following general form: -.CS -\fIimageName option \fR?\fIarg arg ...\fR? -.CE -\fIOption\fR and the \fIarg\fRs -determine the exact behavior of the command. The following -commands are possible for bitmap images: -.TP -\fIimageName \fBcget\fR \fIoption\fR -Returns the current value of the configuration option given -by \fIoption\fR. -\fIOption\fR may have any of the values accepted by the -\fBimage create bitmap\fR command. -.TP -\fIimageName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -Query or modify the configuration options for the image. -If no \fIoption\fR is specified, returns a list describing all of -the available options for \fIimageName\fR (see \fBTk_ConfigureInfo\fR for -information on the format of this list). If \fIoption\fR is specified -with no \fIvalue\fR, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no \fIoption\fR is specified). If -one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given option(s) to have the given value(s); in -this case the command returns an empty string. -\fIOption\fR may have any of the values accepted by the -\fBimage create bitmap\fR command. - -.SH KEYWORDS -bitmap, image diff --git a/tcl/doc/button.n b/tcl/doc/button.n deleted file mode 100644 index ca07c4827c..0000000000 --- a/tcl/doc/button.n +++ /dev/null @@ -1,198 +0,0 @@ -'\" -'\" 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$ -'\" -.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 -.SH SYNOPSIS -\fBbutton\fR \fIpathName \fR?\fIoptions\fR? -.SO -\-activebackground \-foreground \-repeatdelay -\-activeforeground \-highlightbackground \-repeatinterval -\-anchor \-highlightcolor \-takefocus -\-background \-highlightthickness \-text -\-bitmap \-image \-textvariable -\-borderwidth \-justify \-underline -\-cursor \-padx \-wraplength -\-disabledforeground \-pady -\-font \-relief -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-command command Command -Specifies a Tcl command to associate with the button. This command -is typically invoked when mouse button 1 is released over the button -window. -.VS 8.4 -.OP \-compound compound Compound -Specifies whether the button should display both an image and text, -and if so, where the image should be placed relative to the text. -Valid values for this option are \fBbottom\fR, \fBcenter\fR, -\fBleft\fR, \fBnone\fR, \fBright\fR and \fBtop\fR. The default value -is \fBnone\fR, meaning that the button will display either an image or -text, depending on the values of the \fB\-image\fR and \fB\-bitmap\fR -options. -.VE -.OP \-default default Default -.VS -Specifies one of three states for the default ring: \fBnormal\fR, -\fBactive\fR, or \fBdisabled\fR. In active state, the button is drawn -with the platform specific appearance for a default button. In normal -state, the button is drawn with the platform specific appearance for a -non-default button, leaving enough space to draw the default button -appearance. The normal and active states will result in buttons of -the same size. In disabled state, the button is drawn with the -non-default button appearance without leaving space for the default -appearance. The disabled state may result in a smaller button than -the active state. -ring. -.VE -.OP \-height height Height -Specifies a desired height for the button. -If an image or bitmap is being displayed in the button then the value is in -screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR); -for text it is in lines of text. -If this option isn't specified, the button's desired height is computed -from the size of the image or bitmap or text being displayed in it. -.VS 8.4 -.OP \-overrelief overRelief OverRelief -Specifies an alternative relief for the button, to be used when the -mouse cursor is over the widget. This option can be used to make -toolbar buttons, by configuring \fB\-relief flat \-overrelief -raised\fR. If the value of this option is the empty string, then no -alternative relief is used when the mouse cursor is over the button. -The empty string is the default value. -.VE 8.4 -.OP \-state state State -Specifies one of three states for the button: \fBnormal\fR, \fBactive\fR, -or \fBdisabled\fR. In normal state the button is displayed using the -\fBforeground\fR and \fBbackground\fR options. The active state is -typically used when the pointer is over the button. In active state -the button is displayed using the \fBactiveForeground\fR and -\fBactiveBackground\fR options. Disabled state means that the button -should be insensitive: the default bindings will refuse to activate -the widget and will ignore mouse button presses. -In this state the \fBdisabledForeground\fR and -\fBbackground\fR options determine how the button is displayed. -.OP \-width width Width -Specifies a desired width for the button. -If an image or bitmap is being displayed in the button then the value is in -screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR); -for text it is in characters. -If this option isn't specified, the button's desired width is computed -from the size of the image or bitmap or text being displayed in it. -.BE - -.SH DESCRIPTION -.PP -The \fBbutton\fR command creates a new window (given by the -\fIpathName\fR argument) and makes it into a button widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the button such as its colors, font, -text, and initial relief. The \fBbutton\fR command returns its -\fIpathName\fR argument. At the time this command is invoked, -there must not exist a window named \fIpathName\fR, but -\fIpathName\fR's parent must exist. -.PP -A button is a widget that displays a textual string, bitmap or image. -If text is displayed, it must all be in a single font, but it -can occupy multiple lines on the screen (if it contains newlines -or if wrapping occurs because of the \fBwrapLength\fR option) and -one of the characters may optionally be underlined using the -\fBunderline\fR option. -It can display itself in either of three different ways, according -to -the \fBstate\fR option; -it can be made to appear raised, sunken, or flat; -and it can be made to flash. When a user invokes the -button (by pressing mouse button 1 with the cursor over the -button), then the Tcl command specified in the \fB\-command\fR -option is invoked. - -.SH "WIDGET COMMAND" -.PP -The \fBbutton\fR command creates a new Tcl command whose -name is \fIpathName\fR. This -command may be used to invoke various -operations on the widget. It has the following general form: -.CS -\fIpathName option \fR?\fIarg arg ...\fR? -.CE -\fIOption\fR and the \fIarg\fRs -determine the exact behavior of the command. The following -commands are possible for button widgets: -.TP -\fIpathName \fBcget\fR \fIoption\fR -Returns the current value of the configuration option given -by \fIoption\fR. -\fIOption\fR may have any of the values accepted by the \fBbutton\fR -command. -.TP -\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -Query or modify the configuration options of the widget. -If no \fIoption\fR is specified, returns a list describing all of -the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for -information on the format of this list). If \fIoption\fR is specified -with no \fIvalue\fR, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no \fIoption\fR is specified). If -one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given widget option(s) to have the given value(s); in -this case the command returns an empty string. -\fIOption\fR may have any of the values accepted by the \fBbutton\fR -command. -.TP -\fIpathName \fBflash\fR -Flash the button. This is accomplished by redisplaying the button -several times, alternating between active and normal colors. At -the end of the flash the button is left in the same normal/active -state as when the command was invoked. -This command is ignored if the button's state is \fBdisabled\fR. -.TP -\fIpathName \fBinvoke\fR -Invoke the Tcl command associated with the button, if there is one. -The return value is the return value from the Tcl command, or an -empty string if there is no command associated with the button. -This command is ignored if the button's state is \fBdisabled\fR. - -.SH "DEFAULT BINDINGS" -.PP -Tk automatically creates class bindings for buttons that give them -default behavior: -.IP [1] -A button activates whenever the mouse passes over it and deactivates -whenever the mouse leaves the button. -.VS -Under Windows, this binding is only active when mouse button 1 has -been pressed over the button. -.VE -.IP [2] -A button's relief is changed to sunken whenever mouse button 1 is -pressed over the button, and the relief is restored to its original -value when button 1 is later released. -.IP [3] -If mouse button 1 is pressed over a button and later released over -the button, the button is invoked. However, if the mouse is not -over the button when button 1 is released, then no invocation occurs. -.IP [4] -When a button has the input focus, the space key causes the button -to be invoked. -.PP -If the button's state is \fBdisabled\fR then none of the above -actions occur: the button is completely non-responsive. -.PP -The behavior of buttons can be changed by defining new bindings for -individual widgets or by redefining the class bindings. - -.SH KEYWORDS -button, widget diff --git a/tcl/doc/canvas.n b/tcl/doc/canvas.n deleted file mode 100644 index b67622799a..0000000000 --- a/tcl/doc/canvas.n +++ /dev/null @@ -1,1750 +0,0 @@ -'\" -'\" Copyright (c) 1992-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" Copyright (c) 1997-1999 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$ -'\" -.so man.macros -.TH canvas n 8.3 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -canvas \- Create and manipulate canvas widgets -.SH SYNOPSIS -\fBcanvas\fR \fIpathName \fR?\fIoptions\fR? -.SO -\-background \-insertborderwidth \-selectborderwidth -\-borderwidth \-insertofftime \-selectforeground -\-cursor \-insertontime \-takefocus -\-highlightbackground \-insertwidth \-xscrollcommand -\-highlightcolor \-relief \-yscrollcommand -\-highlightthickness \-state -\-insertbackground \-selectbackground -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-closeenough closeEnough CloseEnough -Specifies a floating-point value indicating how close the mouse cursor -must be to an item before it is considered to be ``inside'' the item. -Defaults to 1.0. -.OP \-confine confine Confine -Specifies a boolean value that indicates whether or not it should be -allowable to set the canvas's view outside the region defined by the -\fBscrollRegion\fR argument. -Defaults to true, which means that the view will -be constrained within the scroll region. -.OP \-height height Height -Specifies a desired window height that the canvas widget should request from -its geometry manager. The value may be specified in any -of the forms described in the COORDINATES section below. -.OP \-scrollregion scrollRegion ScrollRegion -Specifies a list with four coordinates describing the left, top, right, and -bottom coordinates of a rectangular region. -This region is used for scrolling purposes and is considered to be -the boundary of the information in the canvas. -Each of the coordinates may be specified -in any of the forms given in the COORDINATES section below. -.OP \-state state State -Modifies the default state of the canvas where \fIstate\fR may be set to -one of: \fBnormal\fR, \fBdisabled\fR, or \fBhidden\fR. Individual canvas -objects all have their own state option which may override the default -state. Many options can take separate specifications such that the -appearance of the item can be different in different situations. The -options that start with \fBactive\fR control the appearence when the mouse -pointer is over it, while the option starting with \fBdisabled\fR controls -the appearence when the state is disabled. Canvas items which are -\fBdisabled\fR will not react to canvas bindings. -.OP \-width width width -Specifies a desired window width that the canvas widget should request from -its geometry manager. The value may be specified in any -of the forms described in the COORDINATES section below. -.OP \-xscrollincrement xScrollIncrement ScrollIncrement -Specifies an increment for horizontal scrolling, in any of the usual forms -permitted for screen distances. If the value of this option is greater -than zero, the horizontal view in the window will be constrained so that -the canvas x coordinate at the left edge of the window is always an even -multiple of \fBxScrollIncrement\fR; furthermore, the units for scrolling -(e.g., the change in view when the left and right arrows of a scrollbar -are selected) will also be \fBxScrollIncrement\fR. If the value of -this option is less than or equal to zero, then horizontal scrolling -is unconstrained. -.OP \-yscrollincrement yScrollIncrement ScrollIncrement -Specifies an increment for vertical scrolling, in any of the usual forms -permitted for screen distances. If the value of this option is greater -than zero, the vertical view in the window will be constrained so that -the canvas y coordinate at the top edge of the window is always an even -multiple of \fByScrollIncrement\fR; furthermore, the units for scrolling -(e.g., the change in view when the top and bottom arrows of a scrollbar -are selected) will also be \fByScrollIncrement\fR. If the value of -this option is less than or equal to zero, then vertical scrolling -is unconstrained. -.BE - -.SH INTRODUCTION -.PP -The \fBcanvas\fR command creates a new window (given -by the \fIpathName\fR argument) and makes it into a canvas widget. -Additional options, described above, may be specified on the -command line or in the option database -to configure aspects of the canvas such as its colors and 3-D relief. -The \fBcanvas\fR command returns its -\fIpathName\fR argument. At the time this command is invoked, -there must not exist a window named \fIpathName\fR, but -\fIpathName\fR's parent must exist. -.PP -Canvas widgets implement structured graphics. -A canvas displays any number of \fIitems\fR, which may be things like -rectangles, circles, lines, and text. -Items may be manipulated (e.g. moved or re-colored) and commands may -be associated with items in much the same way that the \fBbind\fR -command allows commands to be bound to widgets. For example, -a particular command may be associated with the event -so that the command is invoked whenever button 1 is pressed with -the mouse cursor over an item. -This means that items in a canvas can have behaviors defined by -the Tcl scripts bound to them. - -.SH "DISPLAY LIST" -.PP -The items in a canvas are ordered for purposes of display, -with the first item in the display list being displayed -first, followed by the next item in the list, and so on. -Items later in the display list obscure those that are -earlier in the display list and are sometimes referred to -as being ``on top'' of earlier items. -When a new item is created it is placed at the end of the -display list, on top of everything else. -Widget commands may be used to re-arrange the order of the -display list. -.PP -Window items are an exception to the above rules. The underlying -window systems require them always to be drawn on top of other items. -In addition, the stacking order of window items -is not affected by any of the canvas widget commands; you must use -the \fBraise\fR and \fBlower\fR Tk commands instead. - -.SH "ITEM IDS AND TAGS" -.PP -Items in a canvas widget may be named in either of two ways: -by id or by tag. -Each item has a unique identifying number which is assigned to -that item when it is created. The id of an item never changes -and id numbers are never re-used within the lifetime of a -canvas widget. -.PP -Each item may also have any number of \fItags\fR associated -with it. A tag is just a string of characters, and it may -take any form except that of an integer. -For example, ``x123'' is OK but ``123'' isn't. -The same tag may be associated with many different items. -This is commonly done to group items in various interesting -ways; for example, all selected items might be given the -tag ``selected''. -.PP -The tag \fBall\fR is implicitly associated with every item -in the canvas; it may be used to invoke operations on -all the items in the canvas. -.PP -The tag \fBcurrent\fR is managed automatically by Tk; -it applies to the \fIcurrent item\fR, which is the -topmost item whose drawn area covers the position of -the mouse cursor. -If the mouse is not in the canvas widget or is not over -an item, then no item has the \fBcurrent\fR tag. -.PP -When specifying items in canvas widget commands, if the -specifier is an integer then it is assumed to refer to -the single item with that id. -If the specifier is not an integer, then it is assumed to -refer to all of the items in the canvas that have a tag -matching the specifier. -The symbol \fItagOrId\fR is used below to indicate that -an argument specifies either an id that selects a single -item or a tag that selects zero or more items. -.PP -\fItagOrId\fR may contain a logical expressions of -tags by using operators: '&&', '||', '^' '!', and parenthezised -subexpressions. For example: -.CS - .c find withtag {(a&&!b)||(!a&&b)} -.CE -or equivalently: -.CS - .c find withtag {a^b} -.CE -will find only those items with either "a" or "b" tags, but not both. -.PP -Some widget commands only operate on a single item at a -time; if \fItagOrId\fR is specified in a way that -names multiple items, then the normal behavior is for -the command to use the first (lowest) of these items in -the display list that is suitable for the command. -Exceptions are noted in the widget command descriptions -below. - -.SH "COORDINATES" -.PP -All coordinates related to canvases are stored as floating-point -numbers. -Coordinates and distances are specified in screen units, -which are floating-point numbers optionally followed -by one of several letters. -If no letter is supplied then the distance is in pixels. -If the letter is \fBm\fR then the distance is in millimeters on -the screen; if it is \fBc\fR then the distance is in centimeters; -\fBi\fR means inches, and \fBp\fR means printers points (1/72 inch). -Larger y-coordinates refer to points lower on the screen; larger -x-coordinates refer to points farther to the right. -.VS -Coordinates can be specified either as an even number of parameters, -or as a single list parameter containing an even number of x and y -coordinate values. -.VE - -.SH TRANSFORMATIONS -.PP -Normally the origin of the canvas coordinate system is at the -upper-left corner of the window containing the canvas. -It is possible to adjust the origin of the canvas -coordinate system relative to the origin of the window using the -\fBxview\fR and \fByview\fR widget commands; this is typically used -for scrolling. -Canvases do not support scaling or rotation of the canvas coordinate -system relative to the window coordinate system. -.PP -Individual items may be moved or scaled using widget commands -described below, but they may not be rotated. - -.SH "INDICES" -.PP -Text items support the notion of an \fIindex\fR for identifying -particular positions within the item. -In a similar fashion, line and polygon items support \fIindex\fR for -identifying, inserting and deleting subsets of their coordinates. -Indices are used for commands such as inserting or deleting -a range of characters or coordinates, and setting the insertion -cursor position. An index may be specified in any of a number -of ways, and different types of items may support different forms -for specifying indices. -Text items support the following forms for an index; if you -define new types of text-like items, it would be advisable to -support as many of these forms as practical. -Note that it is possible to refer to the character just after -the last one in the text item; this is necessary for such -tasks as inserting new text at the end of the item. -Lines and Polygons don't support the insertion cursor -and the selection. Their indixes are supposed to be even -always, because coordinates always appear in pairs. -.TP 10 -\fInumber\fR -A decimal number giving the position of the desired character -within the text item. -0 refers to the first character, 1 to the next character, and -so on. If indexes are odd for lines and polygons, they will be -automatically decremented by one. -A number less than 0 is treated as if it were zero, and a -number greater than the length of the text item is treated -as if it were equal to the length of the text item. For -polygons, numbers less than 0 or greater then the length -of the coordinate list will be adjusted by adding or substracting -the length until the result is between zero and the length, -inclusive. -.TP 10 -\fBend\fR -Refers to the character or coordinate just after the last one -in the item (same as the number of characters or coordinates -in the item). -.TP 10 -\fBinsert\fR -Refers to the character just before which the insertion cursor -is drawn in this item. Not valid for lines and polygons. -.TP 10 -\fBsel.first\fR -Refers to the first selected character in the item. -If the selection isn't in this item then this form is illegal. -.TP 10 -\fBsel.last\fR -Refers to the last selected character in the item. -If the selection isn't in this item then this form is illegal. -.TP 10 -\fB@\fIx,y\fR -Refers to the character or coordinate at the point given by \fIx\fR and -\fIy\fR, where \fIx\fR and \fIy\fR are specified in the coordinate -system of the canvas. -If \fIx\fR and \fIy\fR lie outside the coordinates covered by the -text item, then they refer to the first or last character in the -line that is closest to the given point. - -.SH "DASH PATTERNS" -.PP -Many items support the notion of an dash pattern for outlines. -.PP -The first possible syntax is a list of integers. Each element -represents the number of pixels of a line segment. Only the odd -segments are drawn using the "outline" color. The other segments -are drawn transparant. -.PP -The second possible syntax is a character list containing only -5 possible characters \fB[.,-_ ]\fR. The space can be used -to enlarge the space between other line elements, and can not -occur as the first position in the string. Some examples: - -dash . = -dash {2 4} - -dash - = -dash {6 4} - -dash -. = -dash {6 4 2 4} - -dash -.. = -dash {6 4 2 4 2 4} - -dash {. } = -dash {2 8} - -dash , = -dash {4 4} -.PP -The main difference of this syntax with the previous is that it -it shape-conserving. This means that all values in the dash -list will be multiplied by the line width before display. This -assures that "." will always be displayed as a dot and "-" -always as a dash regardless of the line width. -.PP -On systems which support only a limited set of dash patterns, the dash -pattern will be displayed as the closest dash pattern that is available. -For example, on Windows only the first 4 of the above examples are -available. The last 2 examples will be displayed identically to the first -one. - -.SH "WIDGET COMMAND" -.PP -The \fBcanvas\fR command creates a new Tcl command whose -name is \fIpathName\fR. This -command may be used to invoke various -operations on the widget. It has the following general form: -.CS -\fIpathName option \fR?\fIarg arg ...\fR? -.CE -\fIOption\fR and the \fIarg\fRs -determine the exact behavior of the command. -The following widget commands are possible for canvas widgets: -.TP -\fIpathName \fBaddtag \fItag searchSpec \fR?\fIarg arg ...\fR? -For each item that meets the constraints specified by -\fIsearchSpec\fR and the \fIarg\fRs, add -\fItag\fR to the list of tags associated with the item if it -isn't already present on that list. -It is possible that no items will satisfy the constraints -given by \fIsearchSpec\fR and \fIarg\fRs, in which case the -command has no effect. -This command returns an empty string as result. -\fISearchSpec\fR and \fIarg\fR's may take any of the following -forms: -.RS -.TP -\fBabove \fItagOrId\fR -Selects the item just after (above) the one given by \fItagOrId\fR -in the display list. -If \fItagOrId\fR denotes more than one item, then the last (topmost) -of these items in the display list is used. -.TP -\fBall\fR -Selects all the items in the canvas. -.TP -\fBbelow \fItagOrId\fR -Selects the item just before (below) the one given by \fItagOrId\fR -in the display list. -If \fItagOrId\fR denotes more than one item, then the first (lowest) -of these items in the display list is used. -.TP -\fBclosest \fIx y \fR?\fIhalo\fR? ?\fIstart\fR? -Selects the item closest to the point given by \fIx\fR and \fIy\fR. -If more than one item is at the same closest distance (e.g. two -items overlap the point), then the top-most of these items (the -last one in the display list) is used. -If \fIhalo\fR is specified, then it must be a non-negative -value. -Any item closer than \fIhalo\fR to the point is considered to -overlap it. -The \fIstart\fR argument may be used to step circularly through -all the closest items. -If \fIstart\fR is specified, it names an item using a tag or id -(if by tag, it selects the first item in the display list with -the given tag). -Instead of selecting the topmost closest item, this form will -select the topmost closest item that is below \fIstart\fR in -the display list; if no such item exists, then the selection -behaves as if the \fIstart\fR argument had not been specified. -.TP -\fBenclosed\fR \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fR -Selects all the items completely enclosed within the rectangular -region given by \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR. -\fIX1\fR must be no greater then \fIx2\fR and \fIy1\fR must be -no greater than \fIy2\fR. -.TP -\fBoverlapping\fR \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fR -Selects all the items that overlap or are enclosed within the -rectangular region given by \fIx1\fR, \fIy1\fR, \fIx2\fR, -and \fIy2\fR. -\fIX1\fR must be no greater then \fIx2\fR and \fIy1\fR must be -no greater than \fIy2\fR. -.TP -\fBwithtag \fItagOrId\fR -Selects all the items given by \fItagOrId\fR. -.RE -.TP -\fIpathName \fBbbox \fItagOrId\fR ?\fItagOrId tagOrId ...\fR? -Returns a list with four elements giving an approximate bounding box -for all the items named by the \fItagOrId\fR arguments. -The list has the form ``\fIx1 y1 x2 y2\fR'' such that the drawn -areas of all the named elements are within the region bounded by -\fIx1\fR on the left, \fIx2\fR on the right, \fIy1\fR on the top, -and \fIy2\fR on the bottom. -The return value may overestimate the actual bounding box by -a few pixels. -If no items match any of the \fItagOrId\fR arguments or if the -matching items have empty bounding boxes (i.e. they have nothing -to display) -then an empty string is returned. -.TP -\fIpathName \fBbind \fItagOrId\fR ?\fIsequence\fR? ?\fIcommand\fR? -This command associates \fIcommand\fR with all the items given by -\fItagOrId\fR such that whenever the event sequence given by -\fIsequence\fR occurs for one of the items the command will -be invoked. -This widget command is similar to the \fBbind\fR command except that -it operates on items in a canvas rather than entire widgets. -See the \fBbind\fR manual entry for complete details -on the syntax of \fIsequence\fR and the substitutions performed -on \fIcommand\fR before invoking it. -If all arguments are specified then a new binding is created, replacing -any existing binding for the same \fIsequence\fR and \fItagOrId\fR -(if the first character of \fIcommand\fR is ``+'' then \fIcommand\fR -augments an existing binding rather than replacing it). -In this case the return value is an empty string. -If \fIcommand\fR is omitted then the command returns the \fIcommand\fR -associated with \fItagOrId\fR and \fIsequence\fR (an error occurs -if there is no such binding). -If both \fIcommand\fR and \fIsequence\fR are omitted then the command -returns a list of all the sequences for which bindings have been -defined for \fItagOrId\fR. -.RS -.PP -The only events for which bindings may be specified are those related to -the mouse and keyboard (such as \fBEnter\fR, \fBLeave\fR, -\fBButtonPress\fR, \fBMotion\fR, and \fBKeyPress\fR) or virtual events. -The handling of events in canvases uses the current item defined in ITEM -IDS AND TAGS above. \fBEnter\fR and \fBLeave\fR events trigger for an -item when it becomes the current item or ceases to be the current item; -note that these events are different than \fBEnter\fR and \fBLeave\fR -events for windows. Mouse-related events are directed to the current -item, if any. Keyboard-related events are directed to the focus item, if -any (see the \fBfocus\fR widget command below for more on this). If a -virtual event is used in a binding, that binding can trigger only if the -virtual event is defined by an underlying mouse-related or -keyboard-related event. -.PP -It is possible for multiple bindings to match a particular event. -This could occur, for example, if one binding is associated with the -item's id and another is associated with one of the item's tags. -When this occurs, all of the matching bindings are invoked. -A binding associated with the \fBall\fR tag is invoked first, -followed by one binding for each of the item's tags (in order), -followed by a binding associated with the item's id. -If there are multiple matching bindings for a single tag, -then only the most specific binding is invoked. -A \fBcontinue\fR command in a binding script terminates that -script, and a \fBbreak\fR command terminates that script -and skips any remaining scripts for the event, just as for the -\fBbind\fR command. -.PP -If bindings have been created for a canvas window using the \fBbind\fR -command, then they are invoked in addition to bindings created for -the canvas's items using the \fBbind\fR widget command. -The bindings for items will be invoked before any of the bindings -for the window as a whole. -.RE -.TP -\fIpathName \fBcanvasx \fIscreenx\fR ?\fIgridspacing\fR? -Given a window x-coordinate in the canvas \fIscreenx\fR, this command returns -the canvas x-coordinate that is displayed at that location. -If \fIgridspacing\fR is specified, then the canvas coordinate is -rounded to the nearest multiple of \fIgridspacing\fR units. -.TP -\fIpathName \fBcanvasy \fIscreeny\fR ?\fIgridspacing\fR? -Given a window y-coordinate in the canvas \fIscreeny\fR this command returns -the canvas y-coordinate that is displayed at that location. -If \fIgridspacing\fR is specified, then the canvas coordinate is -rounded to the nearest multiple of \fIgridspacing\fR units. -.TP -\fIpathName \fBcget\fR \fIoption\fR -Returns the current value of the configuration option given -by \fIoption\fR. -\fIOption\fR may have any of the values accepted by the \fBcanvas\fR -command. -.TP -\fIpathName \fBconfigure ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? -Query or modify the configuration options of the widget. -If no \fIoption\fR is specified, returns a list describing all of -the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for -information on the format of this list). If \fIoption\fR is specified -with no \fIvalue\fR, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no \fIoption\fR is specified). If -one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given widget option(s) to have the given value(s); in -this case the command returns an empty string. -\fIOption\fR may have any of the values accepted by the \fBcanvas\fR -command. -.TP -\fIpathName\fR \fBcoords \fItagOrId \fR?\fIx0 y0 ...\fR? -.TP -\fIpathName\fR \fBcoords \fItagOrId \fR?\fIcoordList\fR? -Query or modify the coordinates that define an item. -If no coordinates are specified, this command returns a list -whose elements are the coordinates of the item named by -\fItagOrId\fR. -If coordinates are specified, then they replace the current -coordinates for the named item. -If \fItagOrId\fR refers to multiple items, then -the first one in the display list is used. -.TP -\fIpathName \fBcreate \fItype x y \fR?\fIx y ...\fR? ?\fIoption value ...\fR? -.TP -\fIpathName \fBcreate \fItype coordList \fR?\fIoption value ...\fR? -Create a new item in \fIpathName\fR of type \fItype\fR. -The exact format of the arguments after \fBtype\fR depends -on \fBtype\fR, but usually they consist of the coordinates for -one or more points, followed by specifications for zero or -more item options. -See the subsections on individual item types below for more -on the syntax of this command. -This command returns the id for the new item. -.TP -\fIpathName \fBdchars \fItagOrId first \fR?\fIlast\fR? -For each item given by \fItagOrId\fR, delete the characters, or coordinates, -in the range given by \fIfirst\fR and \fIlast\fR, inclusive. -If some of the items given by \fItagOrId\fR don't support -indexing operations then they ignore dchars. -Text items interpret \fIfirst\fR and \fIlast\fR as indices to a character, -line and polygon items interpret them indices to a coordinate (an x,y pair). -Indices are described in INDICES above. -If \fIlast\fR is omitted, it defaults to \fIfirst\fR. -This command returns an empty string. -.TP -\fIpathName \fBdelete \fR?\fItagOrId tagOrId ...\fR? -Delete each of the items given by each \fItagOrId\fR, and return -an empty string. -.TP -\fIpathName \fBdtag \fItagOrId \fR?\fItagToDelete\fR? -For each of the items given by \fItagOrId\fR, delete the -tag given by \fItagToDelete\fR from the list of those -associated with the item. -If an item doesn't have the tag \fItagToDelete\fR then -the item is unaffected by the command. -If \fItagToDelete\fR is omitted then it defaults to \fItagOrId\fR. -This command returns an empty string. -.TP -\fIpathName \fBfind \fIsearchCommand \fR?\fIarg arg ...\fR? -This command returns a list consisting of all the items that -meet the constraints specified by \fIsearchCommand\fR and -\fIarg\fR's. -\fISearchCommand\fR and \fIargs\fR have any of the forms -accepted by the \fBaddtag\fR command. -The items are returned in stacking order, with the lowest item first. -.TP -\fIpathName \fBfocus \fR?\fItagOrId\fR? -Set the keyboard focus for the canvas widget to the item given by -\fItagOrId\fR. -If \fItagOrId\fR refers to several items, then the focus is set -to the first such item in the display list that supports the -insertion cursor. -If \fItagOrId\fR doesn't refer to any items, or if none of them -support the insertion cursor, then the focus isn't changed. -If \fItagOrId\fR is an empty -string, then the focus item is reset so that no item has the focus. -If \fItagOrId\fR is not specified then the command returns the -id for the item that currently has the focus, or an empty string -if no item has the focus. -.RS -.PP -Once the focus has been set to an item, the item will display -the insertion cursor and all keyboard events will be directed -to that item. -The focus item within a canvas and the focus window on the -screen (set with the \fBfocus\fR command) are totally independent: -a given item doesn't actually have the input focus unless (a) -its canvas is the focus window and (b) the item is the focus item -within the canvas. -In most cases it is advisable to follow the \fBfocus\fR widget -command with the \fBfocus\fR command to set the focus window to -the canvas (if it wasn't there already). -.RE -.TP -\fIpathName \fBgettags\fR \fItagOrId\fR -Return a list whose elements are the tags associated with the -item given by \fItagOrId\fR. -If \fItagOrId\fR refers to more than one item, then the tags -are returned from the first such item in the display list. -If \fItagOrId\fR doesn't refer to any items, or if the item -contains no tags, then an empty string is returned. -.TP -\fIpathName \fBicursor \fItagOrId index\fR -Set the position of the insertion cursor for the item(s) given by \fItagOrId\fR -to just before the character whose position is given by \fIindex\fR. -If some or all of the items given by \fItagOrId\fR don't support -an insertion cursor then this command has no effect on them. -See INDICES above for a description of the -legal forms for \fIindex\fR. -Note: the insertion cursor is only displayed in an item if -that item currently has the keyboard focus (see the widget -command \fBfocus\fR, below), but the cursor position may -be set even when the item doesn't have the focus. -This command returns an empty string. -.TP -\fIpathName \fBindex \fItagOrId index\fR -This command returns a decimal string giving the numerical index -within \fItagOrId\fR corresponding to \fIindex\fR. -\fIIndex\fR gives a textual description of the desired position -as described in INDICES above. -Text items interpret \fIindex\fR as an index to a character, -line and polygon items interpret it as an index to a coordinate (an x,y pair). -The return value is guaranteed to lie between 0 and the number -of characters, or coordinates, within the item, inclusive. -If \fItagOrId\fR refers to multiple items, then the index -is processed in the first of these items that supports indexing -operations (in display list order). -.TP -\fIpathName \fBinsert \fItagOrId beforeThis string\fR -For each of the items given by \fItagOrId\fR, if the item supports -text or coordinate, insertion then \fIstring\fR is inserted into the item's -text just before the character, or coordinate, whose index is \fIbeforeThis\fR. -Text items interpret \fIbeforethis\fR as an index to a character, -line and polygon items interpret it as an index to a coordinate (an x,y pair). -For lines and polygons the \fIstring\fR must be a valid coordinate -sequence. -See INDICES above for information about the forms allowed -for \fIbeforeThis\fR. -This command returns an empty string. -.TP -\fIpathName \fBitemcget\fR \fItagOrId\fR \fIoption\fR -Returns the current value of the configuration option for the -item given by \fItagOrId\fR whose name is \fIoption\fR. -This command is similar to the \fBcget\fR widget command except that -it applies to a particular item rather than the widget as a whole. -\fIOption\fR may have any of the values accepted by the \fBcreate\fR -widget command when the item was created. -If \fItagOrId\fR is a tag that refers to more than one item, -the first (lowest) such item is used. -.TP -\fIpathName \fBitemconfigure \fItagOrId\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? -This command is similar to the \fBconfigure\fR widget command except -that it modifies item-specific options for the items given by -\fItagOrId\fR instead of modifying options for the overall -canvas widget. -If no \fIoption\fR is specified, returns a list describing all of -the available options for the first item given by \fItagOrId\fR -(see \fBTk_ConfigureInfo\fR for -information on the format of this list). If \fIoption\fR is specified -with no \fIvalue\fR, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no \fIoption\fR is specified). If -one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given widget option(s) to have the given value(s) in -each of the items given by \fItagOrId\fR; in -this case the command returns an empty string. -The \fIoption\fRs and \fIvalue\fRs are the same as those permissible -in the \fBcreate\fR widget command when the item(s) were created; -see the sections describing individual item types below for details -on the legal options. -.TP -\fIpathName \fBlower \fItagOrId \fR?\fIbelowThis\fR? -Move all of the items given by \fItagOrId\fR to a new position -in the display list just before the item given by \fIbelowThis\fR. -If \fItagOrId\fR refers to more than one item then all are moved -but the relative order of the moved items will not be changed. -\fIBelowThis\fR is a tag or id; if it refers to more than one -item then the first (lowest) of these items in the display list is used -as the destination location for the moved items. -Note: this command has no effect on window items. Window items always -obscure other item types, and the stacking order of window items is -determined by the \fBraise\fR and \fBlower\fR commands, not the -\fBraise\fR and \fBlower\fR widget commands for canvases. -This command returns an empty string. -.TP -\fIpathName \fBmove \fItagOrId xAmount yAmount\fR -Move each of the items given by \fItagOrId\fR in the canvas coordinate -space by adding \fIxAmount\fR to the x-coordinate of each point -associated with the item and \fIyAmount\fR to the y-coordinate of -each point associated with the item. -This command returns an empty string. -.TP -\fIpathName \fBpostscript \fR?\fIoption value option value ...\fR? -Generate a Postscript representation for part or all of the canvas. -If the \fB\-file\fR option is specified then the Postscript is written -to a file and an empty string is returned; otherwise the Postscript -is returned as the result of the command. -If the interpreter that owns the canvas is marked as safe, the operation -will fail because safe interpreters are not allowed to write files. -If the \fB\-channel\fR option is specified, the argument denotes the name -of a channel already opened for writing. The Postscript is written to -that channel, and the channel is left open for further writing at the end -of the operation. -The Postscript is created in Encapsulated Postscript form using -version 3.0 of the Document Structuring Conventions. -Note: by default Postscript is only generated for information that -appears in the canvas's window on the screen. If the canvas is -freshly created it may still have its initial size of 1x1 pixel -so nothing will appear in the Postscript. To get around this problem -either invoke the "update" command to wait for the canvas window -to reach its final size, or else use the \fB\-width\fR and \fB\-height\fR -options to specify the area of the canvas to print. -The \fIoption\fR\-\fIvalue\fR argument pairs provide additional -information to control the generation of Postscript. The following -options are supported: -.RS -.TP -\fB\-colormap \fIvarName\fR -\fIVarName\fR must be the name of an array variable -that specifies a color mapping to use in the Postscript. -Each element of \fIvarName\fR must consist of Postscript -code to set a particular color value (e.g. ``\fB1.0 1.0 0.0 setrgbcolor\fR''). -When outputting color information in the Postscript, Tk checks -to see if there is an element of \fIvarName\fR with the same -name as the color. -If so, Tk uses the value of the element as the Postscript command -to set the color. -If this option hasn't been specified, or if there isn't an entry -in \fIvarName\fR for a given color, then Tk uses the red, green, -and blue intensities from the X color. -.TP -\fB\-colormode \fImode\fR -Specifies how to output color information. \fIMode\fR must be either -\fBcolor\fR (for full color output), \fBgray\fR (convert all colors -to their gray-scale equivalents) or \fBmono\fR (convert all colors -to black or white). -.TP -\fB\-file \fIfileName\fR -Specifies the name of the file in which to write the Postscript. -If this option isn't specified then the Postscript is returned as the -result of the command instead of being written to a file. -.TP -\fB\-fontmap \fIvarName\fR -\fIVarName\fR must be the name of an array variable -that specifies a font mapping to use in the Postscript. -Each element of \fIvarName\fR must consist of a Tcl list with -two elements, which are the name and point size of a Postscript font. -When outputting Postscript commands for a particular font, Tk -checks to see if \fIvarName\fR contains an element with the same -name as the font. -If there is such an element, then the font information contained in -that element is used in the Postscript. -Otherwise Tk attempts to guess what Postscript font to use. -Tk's guesses generally only work for well-known fonts such as -Times and Helvetica and Courier, and only if the X font name does not -omit any dashes up through the point size. -For example, \fB\-*\-Courier\-Bold\-R\-Normal\-\-*\-120\-*\fR will work but -\fB*Courier\-Bold\-R\-Normal*120*\fR will not; Tk needs the dashes to -parse the font name). -.TP -\fB\-height \fIsize\fR -Specifies the height of the area of the canvas to print. -Defaults to the height of the canvas window. -.TP -\fB\-pageanchor \fIanchor\fR -Specifies which point of the printed area of the canvas should appear over -the positioning point on the page (which is given by the \fB\-pagex\fR -and \fB\-pagey\fR options). -For example, \fB\-pageanchor n\fR means that the top center of the -area of the canvas being printed (as it appears in the canvas window) -should be over the positioning point. Defaults to \fBcenter\fR. -.TP -\fB\-pageheight \fIsize\fR -Specifies that the Postscript should be scaled in both x and y so -that the printed area is \fIsize\fR high on the Postscript page. -\fISize\fR consists of a floating-point number followed by -\fBc\fR for centimeters, \fBi\fR for inches, \fBm\fR for millimeters, -or \fBp\fR or nothing for printer's points (1/72 inch). -Defaults to the height of the printed area on the screen. -If both \fB\-pageheight\fR and \fB\-pagewidth\fR are specified then -the scale factor from \fB\-pagewidth\fR is used (non-uniform scaling -is not implemented). -.TP -\fB\-pagewidth \fIsize\fR -Specifies that the Postscript should be scaled in both x and y so -that the printed area is \fIsize\fR wide on the Postscript page. -\fISize\fR has the same form as for \fB\-pageheight\fR. -Defaults to the width of the printed area on the screen. -If both \fB\-pageheight\fR and \fB\-pagewidth\fR are specified then -the scale factor from \fB\-pagewidth\fR is used (non-uniform scaling -is not implemented). -.TP -\fB\-pagex \fIposition\fR -\fIPosition\fR gives the x-coordinate of the positioning point on -the Postscript page, using any of the forms allowed for \fB\-pageheight\fR. -Used in conjunction with the \fB\-pagey\fR and \fB\-pageanchor\fR options -to determine where the printed area appears on the Postscript page. -Defaults to the center of the page. -.TP -\fB\-pagey \fIposition\fR -\fIPosition\fR gives the y-coordinate of the positioning point on -the Postscript page, using any of the forms allowed for \fB\-pageheight\fR. -Used in conjunction with the \fB\-pagex\fR and \fB\-pageanchor\fR options -to determine where the printed area appears on the Postscript page. -Defaults to the center of the page. -.TP -\fB\-rotate \fIboolean\fR -\fIBoolean\fR specifies whether the printed area is to be rotated 90 -degrees. -In non-rotated output the x-axis of the printed area runs along -the short dimension of the page (``portrait'' orientation); -in rotated output the x-axis runs along the long dimension of the -page (``landscape'' orientation). -Defaults to non-rotated. -.TP -\fB\-width \fIsize\fR -Specifies the width of the area of the canvas to print. -Defaults to the width of the canvas window. -.TP -\fB\-x \fIposition\fR -Specifies the x-coordinate of the left edge of the area of the -canvas that is to be printed, in canvas coordinates, not window -coordinates. -Defaults to the coordinate of the left edge of the window. -.TP -\fB\-y \fIposition\fR -Specifies the y-coordinate of the top edge of the area of the -canvas that is to be printed, in canvas coordinates, not window -coordinates. -Defaults to the coordinate of the top edge of the window. -.RE -.TP -\fIpathName \fBraise \fItagOrId \fR?\fIaboveThis\fR? -Move all of the items given by \fItagOrId\fR to a new position -in the display list just after the item given by \fIaboveThis\fR. -If \fItagOrId\fR refers to more than one item then all are moved -but the relative order of the moved items will not be changed. -\fIAboveThis\fR is a tag or id; if it refers to more than one -item then the last (topmost) of these items in the display list is used -as the destination location for the moved items. -Note: this command has no effect on window items. Window items always -obscure other item types, and the stacking order of window items is -determined by the \fBraise\fR and \fBlower\fR commands, not the -\fBraise\fR and \fBlower\fR widget commands for canvases. -This command returns an empty string. -.TP -\fIpathName \fBscale \fItagOrId xOrigin yOrigin xScale yScale\fR -Rescale all of the items given by \fItagOrId\fR in canvas coordinate -space. -\fIXOrigin\fR and \fIyOrigin\fR identify the origin for the scaling -operation and \fIxScale\fR and \fIyScale\fR identify the scale -factors for x- and y-coordinates, respectively (a scale factor of -1.0 implies no change to that coordinate). -For each of the points defining each item, the x-coordinate is -adjusted to change the distance from \fIxOrigin\fR by a factor -of \fIxScale\fR. -Similarly, each y-coordinate is adjusted to change the distance -from \fIyOrigin\fR by a factor of \fIyScale\fR. -This command returns an empty string. -.TP -\fIpathName \fBscan\fR \fIoption args\fR -This command is used to implement scanning on canvases. It has -two forms, depending on \fIoption\fR: -.RS -.TP -\fIpathName \fBscan mark \fIx y\fR -Records \fIx\fR and \fIy\fR and the canvas's current view; used -in conjunction with later \fBscan dragto\fR commands. -Typically this command is associated with a mouse button press in -the widget and \fIx\fR and \fIy\fR are the coordinates of the -mouse. It returns an empty string. -.TP -\fIpathName \fBscan dragto \fIx y ?gain?\fR. -This command computes the difference between its \fIx\fR and \fIy\fR -arguments (which are typically mouse coordinates) and the \fIx\fR and -\fIy\fR arguments to the last \fBscan mark\fR command for the widget. -It then adjusts the view by \fIgain\fR times the -difference in coordinates, where \fIgain\fR defaults to 10. -This command is typically associated -with mouse motion events in the widget, to produce the effect of -dragging the canvas at high speed through its window. The return -value is an empty string. -.RE -.TP -\fIpathName \fBselect \fIoption\fR ?\fItagOrId arg\fR? -Manipulates the selection in one of several ways, depending on -\fIoption\fR. -The command may take any of the forms described below. -In all of the descriptions below, \fItagOrId\fR must refer to -an item that supports indexing and selection; if it refers to -multiple items then the first of -these that supports indexing and the selection is used. -\fIIndex\fR gives a textual description of a position -within \fItagOrId\fR, as described in INDICES above. -.RS -.TP -\fIpathName \fBselect adjust \fItagOrId index\fR -Locate the end of the selection in \fItagOrId\fR nearest -to the character given by \fIindex\fR, and adjust that -end of the selection to be at \fIindex\fR (i.e. including -but not going beyond \fIindex\fR). -The other end of the selection is made the anchor point -for future \fBselect to\fR commands. -If the selection isn't currently in \fItagOrId\fR then -this command behaves the same as the \fBselect to\fR widget -command. -Returns an empty string. -.TP -\fIpathName \fBselect clear\fR -Clear the selection if it is in this widget. -If the selection isn't in this widget then the command -has no effect. -Returns an empty string. -.TP -\fIpathName \fBselect from \fItagOrId index\fR -Set the selection anchor point for the widget to be just -before the character -given by \fIindex\fR in the item given by \fItagOrId\fR. -This command doesn't change the selection; it just sets -the fixed end of the selection for future \fBselect to\fR -commands. -Returns an empty string. -.TP -\fIpathName \fBselect item\fR -Returns the id of the selected item, if the selection is in an -item in this canvas. -If the selection is not in this canvas then an empty string -is returned. -.TP -\fIpathName \fBselect to \fItagOrId index\fR -Set the selection to consist of those characters of \fItagOrId\fR -between the selection anchor point and -\fIindex\fR. -The new selection will include the character given by \fIindex\fR; -it will include the character given by the anchor point only if -\fIindex\fR is greater than or equal to the anchor point. -The anchor point is determined by the most recent \fBselect adjust\fR -or \fBselect from\fR command for this widget. -If the selection anchor point for the widget isn't currently in -\fItagOrId\fR, then it is set to the same character given -by \fIindex\fR. -Returns an empty string. -.RE -.TP -\fIpathName \fBtype\fI tagOrId\fR -Returns the type of the item given by \fItagOrId\fR, such as -\fBrectangle\fR or \fBtext\fR. -If \fItagOrId\fR refers to more than one item, then the type -of the first item in the display list is returned. -If \fItagOrId\fR doesn't refer to any items at all then -an empty string is returned. -.TP -\fIpathName \fBxview \fR?\fIargs\fR? -This command is used to query and change the horizontal position of the -information displayed in the canvas's window. -It can take any of the following forms: -.RS -.TP -\fIpathName \fBxview\fR -Returns a list containing two elements. -Each element is a real fraction between 0 and 1; together they describe -the horizontal span that is visible in the window. -For example, if the first element is .2 and the second element is .6, -20% of the canvas's area (as defined by the \fB\-scrollregion\fR option) -is off-screen to the left, the middle 40% is visible -in the window, and 40% of the canvas is off-screen to the right. -These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR -option. -.TP -\fIpathName \fBxview moveto\fI fraction\fR -Adjusts the view in the window so that \fIfraction\fR of the -total width of the canvas is off-screen to the left. -\fIFraction\fR must be a fraction between 0 and 1. -.TP -\fIpathName \fBxview scroll \fInumber what\fR -This command shifts the view in the window left or right according to -\fInumber\fR and \fIwhat\fR. -\fINumber\fR must be an integer. -\fIWhat\fR must be either \fBunits\fR or \fBpages\fR or an abbreviation -of one of these. -If \fIwhat\fR is \fBunits\fR, the view adjusts left or right in units -of the \fBxScrollIncrement\fR option, if it is greater than zero, -or in units of one-tenth the window's width otherwise. -If \fIwhat is \fBpages\fR then the view -adjusts in units of nine-tenths the window's width. -If \fInumber\fR is negative then information farther to the left -becomes visible; if it is positive then information farther to the right -becomes visible. -.RE -.TP -\fIpathName \fByview \fI?args\fR? -This command is used to query and change the vertical position of the -information displayed in the canvas's window. -It can take any of the following forms: -.RS -.TP -\fIpathName \fByview\fR -Returns a list containing two elements. -Each element is a real fraction between 0 and 1; together they describe -the vertical span that is visible in the window. -For example, if the first element is .6 and the second element is 1.0, -the lowest 40% of the canvas's area (as defined by the \fB\-scrollregion\fR -option) is visible in the window. -These are the same values passed to scrollbars via the \fB\-yscrollcommand\fR -option. -.TP -\fIpathName \fByview moveto\fI fraction\fR -Adjusts the view in the window so that \fIfraction\fR of the canvas's -area is off-screen to the top. -\fIFraction\fR is a fraction between 0 and 1. -.TP -\fIpathName \fByview scroll \fInumber what\fR -This command adjusts the view in the window up or down according to -\fInumber\fR and \fIwhat\fR. -\fINumber\fR must be an integer. -\fIWhat\fR must be either \fBunits\fR or \fBpages\fR. -If \fIwhat\fR is \fBunits\fR, the view adjusts up or down in units -of the \fByScrollIncrement\fR option, if it is greater than zero, -or in units of one-tenth the window's height otherwise. -If \fIwhat\fR is \fBpages\fR then -the view adjusts in units of nine-tenths the window's height. -If \fInumber\fR is negative then higher information becomes -visible; if it is positive then lower information -becomes visible. -.RE - -.SH "OVERVIEW OF ITEM TYPES" -.PP -The sections below describe the various types of items supported -by canvas widgets. Each item type is characterized by two things: -first, the form of the \fBcreate\fR command used to create -instances of the type; and second, a set of configuration options -for items of that type, which may be used in the -\fBcreate\fR and \fBitemconfigure\fR widget commands. -Most items don't support indexing or selection or the commands -related to them, such as \fBindex\fR and \fBinsert\fR. -Where items do support these facilities, it is noted explicitly -in the descriptions below. -At present, text, line and polygon items provide this support. -For lines and polygons the indexing facility is used to manipulate -the coordinates of the item. - -.SH "COMMON ITEM OPTIONS" -.PP -Many items share a common set of options. These options are -explained here, and then referred to be each widget type for brevity. -.PP -.TP -\fB\-dash \fIpattern\fR -.TP -\fB\-activedash \fIpattern\fR -.TP -\fB\-disableddash \fIpattern\fR -This option specifies dash patterns for the normal, active -state, and disabled state of an item. -\fIpattern\fR may have any of the forms accepted by \fBTk_GetDash\fR. -If the dash options are omitted then the default is a solid outline. -See "DASH PATTERNS" for more information. -.TP -\fB\-dashoffset \fIoffset\fR -The starting \fIoffset\fR in pixels into the pattern provided by the -\fB\-dash\fR option. \fB\-dashoffset\fR is ignored if there is no -\fB-dash\fR pattern. The \fIoffset\fR may have any of the forms described -in the COORDINATES section above. -.TP -\fB\-fill \fIcolor\fR -.TP -\fB\-activefill \fIcolor\fR -.TP -\fB\-disabledfill \fIcolor\fR -Specifies the color to be used to fill item's area. -in its normal, active, and disabled states, -\fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR. -If \fIcolor\fR is an empty string (the default), then -then the item will not be filled. -For the line item, it specifies the color of the line drawn. -For the text item, it specifies the foreground color of the text. -.TP -\fB\-outline \fIcolor\fR -.TP -\fB\-activeoutline \fIcolor\fR -.TP -\fB\-disabledoutline \fIcolor\fR -This option specifies the color that should be used to draw the -outline of the item in its normal, active and disabled states. -\fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR. -This option defaults to \fBblack\fR. If \fIcolor\fR is specified -as an empty string then no outline is drawn for the item. -.TP -\fB\-offset \fIoffset\fR -Specifies the offset of stipples. The offset value can be of the form -\fBx,y\fR or \fBside\fR, where side can be \fBn\fR, \fBne\fR, \fBe\fR, -\fBse\fR, \fBs\fR, \fBsw\fR, \fBw\fR, \fBnw\fR, or \fBcenter\fR. In the -first case the origin is the origin of the toplevel of the current window. -For the canvas itself and canvas objects the origin is the canvas origin, -but putting \fB#\fR in front of the coordinate pair indicates using the -toplevel origin instead. For canvas objects, the \fB-offset\fR option is -used for stippling as well. For the line and polygon canvas items you can -also specify an index as argument, which connects the stipple origin to one -of the coordinate points of the line/polygon. -.TP -\fB\-outlinestipple \fIbitmap\fR -.TP -\fB\-activeoutlinestipple \fIbitmap\fR -.TP -\fB\-disabledoutlinestipple \fIbitmap\fR -This option specifies stipple patterns that should be used to draw the -outline of the item in its normal, active and disabled states. -Indicates that the outline for the item should be drawn with a stipple pattern; -\fIbitmap\fR specifies the stipple pattern to use, in any of the -forms accepted by \fBTk_GetBitmap\fR. -If the \fB\-outline\fR option hasn't been specified then this option -has no effect. -If \fIbitmap\fR is an empty string (the default), then the outline is drawn -in a solid fashion. -.TP -\fB\-stipple \fIbitmap\fR -.TP -\fB\-activestipple \fIbitmap\fR -.TP -\fB\-disabledstipple \fIbitmap\fR -This option specifies stipple patterns that should be used to fill the -the item in its normal, active and disabled states. -\fIbitmap\fR specifies the stipple pattern to use, in any of the -forms accepted by \fBTk_GetBitmap\fR. -If the \fB\-fill\fR option hasn't been specified then this option -has no effect. -If \fIbitmap\fR is an empty string (the default), then filling is done -in a solid fashion. -For the text item, it affects the actual text. -.TP -\fB\-state \fIstate\fR -This allows an item to override the canvas widget's global \fIstate\fR -option. It takes the same values: -\fInormal\fR, \fIdisabled\fR or \fIhidden\fR. -.TP -\fB\-tags \fItagList\fR -Specifies a set of tags to apply to the item. -\fITagList\fR consists of a list of tag names, which replace any -existing tags for the item. \fITagList\fR may be an empty list. -.TP -\fB\-width \fIoutlineWidth\fR -.TP -\fB\-activewidth \fIoutlineWidth\fR -.TP -\fB\-disabledwidth \fIoutlineWidth\fR -Specifies the width of the outline to be drawn around -the item's region, in its normal, active and disabled states. -\fIoutlineWidth\fR may be in any of the forms described in the COORDINATES -section above. -If the \fB\-outline\fR option has been specified as an empty string then -this option has no effect. This option defaults to 1.0. -For arcs, wide outlines will be drawn centered on the edges of the -arc's region. - -.SH "ARC ITEMS" -.PP -Items of type \fBarc\fR appear on the display as arc-shaped regions. -An arc is a section of an oval delimited by two angles (specified -by the \fB\-start\fR and \fB\-extent\fR options) and displayed in -one of several ways (specified by the \fB\-style\fR option). -Arcs are created with widget commands of the following form: -.CS -\fIpathName \fBcreate arc \fIx1 y1 x2 y2 \fR?\fIoption value option value ...\fR? -\fIpathName \fBcreate arc \fIcoordList\fR ?\fIoption value option value ...\fR? -.CE -The arguments \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR or \fIcoordList\fR give -the coordinates of two diagonally opposite corners of a -rectangular region enclosing the oval that defines the arc. -After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR -pairs, each of which sets one of the configuration options -for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be -used in \fBitemconfigure\fR widget commands to change the item's -configuration. -.br -The following standard options are supported by arcs: -.CS -\-dash -\-activedash -\-disableddash -\-dashoffset -\-fill -\-activefill -\-disabledfill -\-offset -\-outline -\-activeoutline -\-disabledoutline -\-outlinestipple -\-activeoutlinestipple -\-disabledoutlinestipple -\-stipple -\-activestipple -\-disabledstipple -\-state -\-tags -\-width -\-activewidth -\-disabledwidth -.CE -The following extra options are supported for arcs: -.TP -\fB\-extent \fIdegrees\fR -Specifies the size of the angular range occupied by the arc. -The arc's range extends for \fIdegrees\fR degrees counter-clockwise -from the starting angle given by the \fB\-start\fR option. -\fIDegrees\fR may be negative. -If it is greater than 360 or less than -360, then \fIdegrees\fR -modulo 360 is used as the extent. -.TP -\fB\-start \fIdegrees\fR -Specifies the beginning of the angular range occupied by the -arc. -\fIDegrees\fR is given in units of degrees measured counter-clockwise -from the 3-o'clock position; it may be either positive or negative. -.TP -\fB\-style \fItype\fR -Specifies how to draw the arc. If \fItype\fR is \fBpieslice\fR -(the default) then the arc's region is defined by a section -of the oval's perimeter plus two line segments, one between the center -of the oval and each end of the perimeter section. -If \fItype\fR is \fBchord\fR then the arc's region is defined -by a section of the oval's perimeter plus a single line segment -connecting the two end points of the perimeter section. -If \fItype\fR is \fBarc\fR then the arc's region consists of -a section of the perimeter alone. -In this last case the \fB\-fill\fR option is ignored. - -.SH "BITMAP ITEMS" -.PP -Items of type \fBbitmap\fR appear on the display as images with -two colors, foreground and background. -Bitmaps are created with widget commands of the following form: -.CS -\fIpathName \fBcreate bitmap \fIx y \fR?\fIoption value option value ...\fR? -\fIpathName \fBcreate bitmap \fIcoordList\fR ?\fIoption value option value ...\fR? -.CE -The arguments \fIx\fR and \fIy\fR or \fIcoordList\fR specify the coordinates of a -point used to position the bitmap on the display (see the \fB\-anchor\fR -option below for more information on how bitmaps are displayed). -After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR -pairs, each of which sets one of the configuration options -for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be -used in \fBitemconfigure\fR widget commands to change the item's -configuration. -.br -The following standard options are supported by bitmaps: -.CS -\-state -\-tags -.CE -The following extra options are supported for bitmaps: -.TP -\fB\-anchor \fIanchorPos\fR -\fIAnchorPos\fR tells how to position the bitmap relative to the -positioning point for the item; it may have any of the forms -accepted by \fBTk_GetAnchor\fR. For example, if \fIanchorPos\fR -is \fBcenter\fR then the bitmap is centered on the point; if -\fIanchorPos\fR is \fBn\fR then the bitmap will be drawn so that -its top center point is at the positioning point. -This option defaults to \fBcenter\fR. -.TP -\fB\-background \fIcolor\fR -.TP -\fB\-activebackground \fIbitmap\fR -.TP -\fB\-disabledbackground \fIbitmap\fR -Specifies the color to use for each of the bitmap's '0' valued pixels -in its normal, active and disabled states. -\fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR. -If this option isn't specified, or if it is specified as an empty -string, then nothing is displayed where the bitmap pixels are 0; this -produces a transparent effect. -.TP -\fB\-bitmap \fIbitmap\fR -.TP -\fB\-activebitmap \fIbitmap\fR -.TP -\fB\-disabledbitmap \fIbitmap\fR -Specifies the bitmaps to display in the item in its normal, active and -disabled states. -\fIBitmap\fR may have any of the forms accepted by \fBTk_GetBitmap\fR. -.TP -\fB\-foreground \fIcolor\fR -.TP -\fB\-activeforeground \fIbitmap\fR -.TP -\fB\-disabledforeground \fIbitmap\fR -Specifies the color to use for each of the bitmap's '1' valued pixels -in its normal, active and disabled states. -\fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR and -defaults to \fBblack\fR. - -.SH "IMAGE ITEMS" -.PP -Items of type \fBimage\fR are used to display images on a -canvas. -Images are created with widget commands of the following form: -.CS -\fIpathName \fBcreate image \fIx y \fR?\fIoption value option value ...\fR? -\fIpathName \fBcreate image \fIcoordList\fR ?\fIoption value option value ...\fR? -.CE -The arguments \fIx\fR and \fIy\fR or \fIcoordList\fR specify the coordinates of a -point used to position the image on the display (see the \fB\-anchor\fR -option below for more information). -After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR -pairs, each of which sets one of the configuration options -for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be -used in \fBitemconfigure\fR widget commands to change the item's -configuration. -.br -The following standard options are supported by images: -.CS -\-state -\-tags -.CE -The following extra options are supported for images: -.TP -\fB\-anchor \fIanchorPos\fR -\fIAnchorPos\fR tells how to position the image relative to the -positioning point for the item; it may have any of the forms -accepted by \fBTk_GetAnchor\fR. For example, if \fIanchorPos\fR -is \fBcenter\fR then the image is centered on the point; if -\fIanchorPos\fR is \fBn\fR then the image will be drawn so that -its top center point is at the positioning point. -This option defaults to \fBcenter\fR. -.TP -\fB\-image \fIname\fR -.TP -\fB\-activeimage \fIname\fR -.TP -\fB\-disabledimage \fIname\fR -Specifies the name of the images to display in the item in is normal, -active and disabled states. -This image must have been created previously with the -\fBimage create\fR command. - -.SH "LINE ITEMS" -.PP -Items of type \fBline\fR appear on the display as one or more connected -line segments or curves. -Line items support coordinate indexing operations using the canvas -widget commands: \fBdchars, index, insert.\fR -Lines are created with widget commands of the following form: -.CS -\fIpathName \fBcreate line \fIx1 y1... xn yn \fR?\fIoption value option value ...\fR? -\fIpathName \fBcreate line \fIcoordList\fR ?\fIoption value option value ...\fR? -.CE -The arguments \fIx1\fR through \fIyn\fR or \fIcoordList\fR give -the coordinates for a series of two or more points that describe -a series of connected line segments. -After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR -pairs, each of which sets one of the configuration options -for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be -used in \fBitemconfigure\fR widget commands to change the item's -configuration. -.br -The following standard options are supported by lines: -.CS -\-dash -\-activedash -\-disableddash -\-dashoffset -\-fill -\-activefill -\-disabledfill -\-stipple -\-activestipple -\-disabledstipple -\-state -\-tags -\-width -\-activewidth -\-disabledwidth -.CE -The following extra options are supported for lines: -.TP -\fB\-arrow \fIwhere\fR -Indicates whether or not arrowheads are to be drawn at one or both -ends of the line. -\fIWhere\fR must have one of the values \fBnone\fR (for no arrowheads), -\fBfirst\fR (for an arrowhead at the first point of the line), -\fBlast\fR (for an arrowhead at the last point of the line), or -\fBboth\fR (for arrowheads at both ends). -This option defaults to \fBnone\fR. -.TP -\fB\-arrowshape \fIshape\fR -This option indicates how to draw arrowheads. -The \fIshape\fR argument must be a list with three elements, each -specifying a distance in any of the forms described in -the COORDINATES section above. -The first element of the list gives the distance along the line -from the neck of the arrowhead to its tip. -The second element gives the distance along the line from the -trailing points of the arrowhead to the tip, and the third -element gives the distance from the outside edge of the line to the -trailing points. -If this option isn't specified then Tk picks a ``reasonable'' shape. -.TP -\fB\-capstyle \fIstyle\fR -Specifies the ways in which caps are to be drawn at the endpoints -of the line. -\fIStyle\fR may have any of the forms accepted by \fBTk_GetCapStyle\fR -(\fBbutt\fR, \fBprojecting\fR, or \fBround\fR). -If this option isn't specified then it defaults to \fBbutt\fR. -Where arrowheads are drawn the cap style is ignored. -.TP -\fB\-joinstyle \fIstyle\fR -Specifies the ways in which joints are to be drawn at the vertices -of the line. -\fIStyle\fR may have any of the forms accepted by \fBTk_GetCapStyle\fR -(\fBbevel\fR, \fBmiter\fR, or \fBround\fR). -If this option isn't specified then it defaults to \fBmiter\fR. -If the line only contains two points then this option is -irrelevant. -.TP -\fB\-smooth \fIsmoothMethod\fR -\fIsmoothMethod\fR must have one of the forms accepted by -\fBTk_GetBoolean\fR or a line smoothing method. Only \fBbezier\fR is -supported in the core, but more can be added at runtime. If a boolean -false value or empty string is given, no smoothing is applied. A boolean -truth value assume \fBbezier\fR smoothing. -It indicates whether or not the line should be drawn as a curve. -If so, the line is rendered as a set of parabolic splines: one spline -is drawn for the first and second line segments, one for the second -and third, and so on. Straight-line segments can be generated within -a curve by duplicating the end-points of the desired line segment. -.TP -\fB\-splinesteps \fInumber\fR -Specifies the degree of smoothness desired for curves: each spline -will be approximated with \fInumber\fR line segments. This -option is ignored unless the \fB\-smooth\fR option is true. - -.SH "OVAL ITEMS" -.PP -Items of type \fBoval\fR appear as circular or oval regions on -the display. Each oval may have an outline, a fill, or -both. Ovals are created with widget commands of the -following form: -.CS -\fIpathName \fBcreate oval \fIx1 y1 x2 y2 \fR?\fIoption value option value ...\fR? -\fIpathName \fBcreate oval \fIcoordList\fR ?\fIoption value option value ...\fR? -.CE -The arguments \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR or \fIcoordList\fR give -the coordinates of two diagonally opposite corners of a -rectangular region enclosing the oval. -The oval will include the top and left edges of the rectangle -not the lower or right edges. -If the region is square then the resulting oval is circular; -otherwise it is elongated in shape. -After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR -pairs, each of which sets one of the configuration options -for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be -used in \fBitemconfigure\fR widget commands to change the item's -configuration. -.br -The following standard options are supported by ovals: -.CS -\-dash -\-activedash -\-disableddash -\-dashoffset -\-fill -\-activefill -\-disabledfill -\-offset -\-outline -\-activeoutline -\-disabledoutline -\-outlinestipple -\-activeoutlinestipple -\-disabledoutlinestipple -\-stipple -\-activestipple -\-disabledstipple -\-state -\-tags -\-width -\-activewidth -\-disabledwidth -.CE - -.SH "POLYGON ITEMS" -.PP -Items of type \fBpolygon\fR appear as polygonal or curved filled regions -on the display. -Polygon items support coordinate indexing operations using the canvas -widget commands: \fBdchars, index, insert.\fR -Polygons are created with widget commands of the following form: -.CS -\fIpathName \fBcreate polygon \fIx1 y1 ... xn yn \fR?\fIoption value option value ...\fR? -\fIpathName \fBcreate polygon \fIcoordList\fR ?\fIoption value option value ...\fR? -.CE -The arguments \fIx1\fR through \fIyn\fR or \fIcoordList\fR specify the coordinates for -three or more points that define a polygon. -The first point should not be repeated as the last to -close the shape; Tk will automatically close the periphery between -the first and last points. -After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR -pairs, each of which sets one of the configuration options -for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be -used in \fBitemconfigure\fR widget commands to change the item's -configuration. -.br -The following standard options are supported by polygons: -.CS -\-dash -\-activedash -\-disableddash -\-dashoffset -\-fill -\-activefill -\-disabledfill -\-offset -\-outline -\-activeoutline -\-disabledoutline -\-outlinestipple -\-activeoutlinestipple -\-disabledoutlinestipple -\-stipple -\-activestipple -\-disabledstipple -\-state -\-tags -\-width -\-activewidth -\-disabledwidth -.CE -The following extra options are supported for polygons: -.TP -\fB\-joinstyle \fIstyle\fR -Specifies the ways in which joints are to be drawn at the vertices -of the outline. -\fIStyle\fR may have any of the forms accepted by \fBTk_GetCapStyle\fR -(\fBbevel\fR, \fBmiter\fR, or \fBround\fR). -If this option isn't specified then it defaults to \fBmiter\fR. -.TP -\fB\-smooth \fIboolean\fR -\fIBoolean\fR must have one of the forms accepted by \fBTk_GetBoolean\fR -It indicates whether or not the polygon should be drawn with a -curved perimeter. -If so, the outline of the polygon becomes a set of parabolic splines, -one spline for the first and second line segments, one for the second -and third, and so on. Straight-line segments can be generated in a -smoothed polygon by duplicating the end-points of the desired line segment. -.TP -\fB\-splinesteps \fInumber\fR -Specifies the degree of smoothness desired for curves: each spline -will be approximated with \fInumber\fR line segments. This -option is ignored unless the \fB\-smooth\fR option is true. -.PP -Polygon items are different from other items such as rectangles, ovals -and arcs in that interior points are considered to be ``inside'' a -polygon (e.g. for purposes of the \fBfind closest\fR and -\fBfind overlapping\fR widget commands) even if it is not filled. -For most other item types, an -interior point is considered to be inside the item only if the item -is filled or if it has neither a fill nor an outline. If you would -like an unfilled polygon whose interior points are not considered -to be inside the polygon, use a line item instead. - -.SH "RECTANGLE ITEMS" -.PP -Items of type \fBrectangle\fR appear as rectangular regions on -the display. Each rectangle may have an outline, a fill, or -both. Rectangles are created with widget commands of the -following form: -.CS -\fIpathName \fBcreate rectangle \fIx1 y1 x2 y2 \fR?\fIoption value option value ...\fR? -\fIpathName \fBcreate rectangle \fIcoordList\fR ?\fIoption value option value ...\fR? -.CE -The arguments \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR or \fIcoordList\fR give -the coordinates of two diagonally opposite corners of the rectangle -(the rectangle will include its upper and left edges but not -its lower or right edges). -After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR -pairs, each of which sets one of the configuration options -for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be -used in \fBitemconfigure\fR widget commands to change the item's -configuration. -.br -The following standard options are supported by rectangles: -.CS -\-dash -\-activedash -\-disableddash -\-dashoffset -\-fill -\-activefill -\-disabledfill -\-offset -\-outline -\-activeoutline -\-disabledoutline -\-outlinestipple -\-activeoutlinestipple -\-disabledoutlinestipple -\-stipple -\-activestipple -\-disabledstipple -\-state -\-tags -\-width -\-activewidth -\-disabledwidth -.CE - -.SH "TEXT ITEMS" -.PP -A text item displays a string of characters on the screen in one -or more lines. -Text items support indexing and selection, along with the -following text-related canvas widget commands: \fBdchars\fR, -\fBfocus\fR, \fBicursor\fR, \fBindex\fR, \fBinsert\fR, -\fBselect\fR. -Text items are created with widget commands of the following -form: -.CS -\fIpathName \fBcreate text \fIx y \fR?\fIoption value option value ...\fR? -\fIpathName \fBcreate text \fIcoordList\fR ?\fIoption value option value ...\fR? -.CE -The arguments \fIx\fR and \fIy\fR or \fIcoordList\fR specify the coordinates of a -point used to position the text on the display (see the options -below for more information on how text is displayed). -After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR -pairs, each of which sets one of the configuration options -for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be -used in \fBitemconfigure\fR widget commands to change the item's -configuration. -.br -The following standard options are supported by text items: -.CS -\-fill -\-activefill -\-disabledfill -\-stipple -\-activestipple -\-disabledstipple -\-state -\-tags -.CE -The following extra options are supported for text items: -.TP -\fB\-anchor \fIanchorPos\fR -\fIAnchorPos\fR tells how to position the text relative to the -positioning point for the text; it may have any of the forms -accepted by \fBTk_GetAnchor\fR. For example, if \fIanchorPos\fR -is \fBcenter\fR then the text is centered on the point; if -\fIanchorPos\fR is \fBn\fR then the text will be drawn such that -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\-font \fIfontName\fR -Specifies the font to use for the text item. -\fIFontName\fR may be any string acceptable to \fBTk_GetFont\fR. -If this option isn't specified, it defaults to a system-dependent -font. -.TP -\fB\-justify \fIhow\fR -Specifies how to justify the text within its bounding region. -\fIHow\fR must be one of the values \fBleft\fR, \fBright\fR, -or \fBcenter\fR. -This option will only matter if the text is displayed as multiple -lines. -If the option is omitted, it defaults to \fBleft\fR. -.TP -\fB\-text \fIstring\fR -\fIString\fR specifies the characters to be displayed in the text item. -Newline characters cause line breaks. -The characters in the item may also be changed with the -\fBinsert\fR and \fBdelete\fR widget commands. -This option defaults to an empty string. -.TP -\fB\-width \fIlineLength\fR -Specifies a maximum line length for the text, in any of the forms -described in the COORDINATES section above. -If this option is zero (the default) the text is broken into -lines only at newline characters. -However, if this option is non-zero then any line that would -be longer than \fIlineLength\fR is broken just before a space -character to make the line shorter than \fIlineLength\fR; the -space character is treated as if it were a newline -character. - -.SH "WINDOW ITEMS" -.PP -Items of type \fBwindow\fR cause a particular window to be displayed -at a given position on the canvas. -Window items are created with widget commands of the following form: -.CS -\fIpathName \fBcreate window \fIx y \fR?\fIoption value option value ...\fR? -\fIpathName \fBcreate window \fIcoordList\fR ?\fIoption value option value ...\fR? -.CE -The arguments \fIx\fR and \fIy\fR or \fIcoordList\fR specify the coordinates of a -point used to position the window on the display (see the \fB\-anchor\fR -option below for more information on how bitmaps are displayed). -After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR -pairs, each of which sets one of the configuration options -for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be -used in \fBitemconfigure\fR widget commands to change the item's -configuration. -.br -The following standard options are supported by window items: -.CS -\-state -\-tags -.CE -The following extra options are supported for window items: -.TP -\fB\-anchor \fIanchorPos\fR -\fIAnchorPos\fR tells how to position the window relative to the -positioning point for the item; it may have any of the forms -accepted by \fBTk_GetAnchor\fR. For example, if \fIanchorPos\fR -is \fBcenter\fR then the window is centered on the point; if -\fIanchorPos\fR is \fBn\fR then the window will be drawn so that -its top center point is at the positioning point. -This option defaults to \fBcenter\fR. -.TP -\fB\-height \fIpixels\fR -Specifies the height to assign to the item's window. -\fIPixels\fR may have any of the -forms described in the COORDINATES section above. -If this option isn't specified, or if it is specified as an empty -string, then the window is given whatever height it requests internally. -.TP -\fB\-width \fIpixels\fR -Specifies the width to assign to the item's window. -\fIPixels\fR may have any of the -forms described in the COORDINATES section above. -If this option isn't specified, or if it is specified as an empty -string, then the window is given whatever width it requests internally. -.TP -\fB\-window \fIpathName\fR -Specifies the window to associate with this item. -The window specified by \fIpathName\fR must either be a child of -the canvas widget or a child of some ancestor of the canvas widget. -\fIPathName\fR may not refer to a top-level window. -.PP -Note: due to restrictions in the ways that windows are managed, it is not -possible to draw other graphical items (such as lines and images) on top -of window items. A window item always obscures any graphics that -overlap it, regardless of their order in the display list. - -.SH "APPLICATION-DEFINED ITEM TYPES" -.PP -It is possible for individual applications to define new item -types for canvas widgets using C code. -See the documentation for \fBTk_CreateItemType\fR. - -.SH BINDINGS -.PP -In the current implementation, new canvases are not given any -default behavior: you'll have to execute explicit Tcl commands -to give the canvas its behavior. - -.SH CREDITS -.PP -Tk's canvas widget is a blatant ripoff of ideas from Joel Bartlett's -\fIezd\fR program. \fIEzd\fR provides structured graphics in a Scheme -environment and preceded canvases by a year or two. Its simple -mechanisms for placing and animating graphical objects inspired the -functions of canvases. - -.SH KEYWORDS -canvas, widget diff --git a/tcl/doc/checkbutton.n b/tcl/doc/checkbutton.n deleted file mode 100644 index 15e457f47c..0000000000 --- a/tcl/doc/checkbutton.n +++ /dev/null @@ -1,260 +0,0 @@ -'\" -'\" 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$ -'\" -.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 -.SH SYNOPSIS -\fBcheckbutton\fI pathName \fR?\fIoptions\fR? -.SO -\-activebackground \-font \-pady -\-activeforeground \-foreground \-relief -\-anchor \-highlightbackground \-takefocus -\-background \-highlightcolor \-text -\-bitmap \-highlightthickness \-textvariable -\-borderwidth \-image \-underline -\-cursor \-justify \-wraplength -\-disabledforeground \-padx -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-command command Command -Specifies a Tcl command to associate with the button. This command -is typically invoked when mouse button 1 is released over the button -window. The button's global variable (\fB\-variable\fR option) will -be updated before the command is invoked. -.OP \-height height Height -Specifies a desired height for the button. -If an image or bitmap is being displayed in the button then the value is in -screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR); -for text it is in lines of text. -If this option isn't specified, the button's desired height is computed -from the size of the image or bitmap or text being displayed in it. -.OP \-indicatoron indicatorOn IndicatorOn -Specifies whether or not the indicator should be drawn. Must be a -proper boolean value. If false, the \fBrelief\fR option is -ignored and the widget's relief is always sunken if the widget is -selected and raised otherwise. -.VS 8.4 -.OP \-offrelief offRelief OffRelief -Specifies the relief for the checkbutton when the indicator is not drawn and -the checkbutton is off. The default value is "raised". By setting this option -to "flat" and setting -indicatoron to false and -overrelief to raised, -the effect is achieved -of having a flat button that raises on mouse-over and which is -depressed when activated. This is the behavior typically exhibited by -the Bold, Italic, and Underline checkbuttons on the toolbar of a -word-processor, for example. -.VE 8.4 -.OP \-offvalue offValue Value -Specifies value to store in the button's associated variable whenever -this button is deselected. Defaults to ``0''. -.OP \-onvalue onValue Value -Specifies value to store in the button's associated variable whenever -this button is selected. Defaults to ``1''. -.VS 8.4 -.OP \-overrelief overRelief OverRelief -Specifies an alternative relief for the checkbutton, to be used when the -mouse cursor is over the widget. This option can be used to make -toolbar buttons, by configuring \fB\-relief flat \-overrelief -raised\fR. If the value of this option is the empty string, then no -alternative relief is used when the mouse cursor is over the checkbutton. -The empty string is the default value. -.VE 8.4 -.OP \-selectcolor selectColor Background -Specifies a background color to use when the button is selected. -If \fBindicatorOn\fR is true then the color applies to the indicator. -Under Windows, this color is used as the background for the indicator -regardless of the select state. -If \fBindicatorOn\fR is false, this color is used as the background -for the entire widget, in place of \fBbackground\fR or \fBactiveBackground\fR, -whenever the widget is selected. -If specified as an empty string then no special color is used for -displaying when the widget is selected. -.OP \-selectimage selectImage SelectImage -Specifies an image to display (in place of the \fBimage\fR option) -when the checkbutton is selected. -This option is ignored unless the \fBimage\fR option has been -specified. -.OP \-state state State -Specifies one of three states for the checkbutton: \fBnormal\fR, \fBactive\fR, -or \fBdisabled\fR. In normal state the checkbutton is displayed using the -\fBforeground\fR and \fBbackground\fR options. The active state is -typically used when the pointer is over the checkbutton. In active state -the checkbutton is displayed using the \fBactiveForeground\fR and -\fBactiveBackground\fR options. Disabled state means that the checkbutton -should be insensitive: the default bindings will refuse to activate -the widget and will ignore mouse button presses. -In this state the \fBdisabledForeground\fR and -\fBbackground\fR options determine how the checkbutton is displayed. -.OP \-variable variable Variable -Specifies name of global variable to set to indicate whether -or not this button is selected. Defaults to the name of the -button within its parent (i.e. the last element of the button -window's path name). -.OP \-width width Width -Specifies a desired width for the button. -If an image or bitmap is being displayed in the button then the value is in -screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR); -for text it is in characters. -If this option isn't specified, the button's desired width is computed -from the size of the image or bitmap or text being displayed in it. -.BE - -.SH DESCRIPTION -.PP -The \fBcheckbutton\fR command creates a new window (given by the -\fIpathName\fR argument) and makes it into a checkbutton widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the checkbutton such as its colors, font, -text, and initial relief. The \fBcheckbutton\fR command returns its -\fIpathName\fR argument. At the time this command is invoked, -there must not exist a window named \fIpathName\fR, but -\fIpathName\fR's parent must exist. -.PP -A checkbutton is a widget -that displays a textual string, bitmap or image -and a square called an \fIindicator\fR. -If text is displayed, it must all be in a single font, but it -can occupy multiple lines on the screen (if it contains newlines -or if wrapping occurs because of the \fBwrapLength\fR option) and -one of the characters may optionally be underlined using the -\fBunderline\fR option. -A checkbutton has -all of the behavior of a simple button, including the -following: it can display itself in either of three different -ways, according to the \fBstate\fR option; -it can be made to appear -raised, sunken, or flat; it can be made to flash; and it invokes -a Tcl command whenever mouse button 1 is clicked over the -checkbutton. -.PP -In addition, checkbuttons can be \fIselected\fR. -If a checkbutton is selected then the indicator is normally -.VS -drawn with a selected appearance, and -a Tcl variable associated with the checkbutton is set to a particular -value (normally 1). -Under Unix, the indicator is drawn with a sunken relief and a special -color. Under Windows, the indicator is drawn with a check mark inside. -If the checkbutton is not selected, then the indicator is drawn with a -deselected appearance, and the associated variable is -set to a different value (typically 0). -Under Unix, the indicator is drawn with a raised relief and no special -color. Under Windows, the indicator is drawn without a check mark inside. -.VE -By default, the name of the variable associated with a checkbutton is the -same as the \fIname\fR used to create the checkbutton. -The variable name, and the ``on'' and ``off'' values stored in it, -may be modified with options on the command line or in the option -database. -Configuration options may also be used to modify the way the -indicator is displayed (or whether it is displayed at all). -By default a checkbutton is configured to select and deselect -itself on alternate button clicks. -In addition, each checkbutton monitors its associated variable and -automatically selects and deselects itself when the variables value -changes to and from the button's ``on'' value. - -.SH "WIDGET COMMAND" -.PP -The \fBcheckbutton\fR command creates a new Tcl command whose -name is \fIpathName\fR. This -command may be used to invoke various -operations on the widget. It has the following general form: -.CS -\fIpathName option \fR?\fIarg arg ...\fR? -.CE -\fIOption\fR and the \fIarg\fRs -determine the exact behavior of the command. The following -commands are possible for checkbutton widgets: -.TP -\fIpathName \fBcget\fR \fIoption\fR -Returns the current value of the configuration option given -by \fIoption\fR. -\fIOption\fR may have any of the values accepted by the \fBcheckbutton\fR -command. -.TP -\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -Query or modify the configuration options of the widget. -If no \fIoption\fR is specified, returns a list describing all of -the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for -information on the format of this list). If \fIoption\fR is specified -with no \fIvalue\fR, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no \fIoption\fR is specified). If -one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given widget option(s) to have the given value(s); in -this case the command returns an empty string. -\fIOption\fR may have any of the values accepted by the \fBcheckbutton\fR -command. -.TP -\fIpathName \fBdeselect\fR -Deselects the checkbutton and sets the associated variable to its ``off'' -value. -.TP -\fIpathName \fBflash\fR -Flashes the checkbutton. This is accomplished by redisplaying the checkbutton -several times, alternating between active and normal colors. At -the end of the flash the checkbutton is left in the same normal/active -state as when the command was invoked. -This command is ignored if the checkbutton's state is \fBdisabled\fR. -.TP -\fIpathName \fBinvoke\fR -Does just what would have happened if the user invoked the checkbutton -with the mouse: toggle the selection state of the button and invoke -the Tcl command associated with the checkbutton, if there is one. -The return value is the return value from the Tcl command, or an -empty string if there is no command associated with the checkbutton. -This command is ignored if the checkbutton's state is \fBdisabled\fR. -.TP -\fIpathName \fBselect\fR -Selects the checkbutton and sets the associated variable to its ``on'' -value. -.TP -\fIpathName \fBtoggle\fR -Toggles the selection state of the button, redisplaying it and -modifying its associated variable to reflect the new state. - -.SH BINDINGS -.PP -Tk automatically creates class bindings for checkbuttons that give them -the following default behavior: -.VS -.IP [1] -On Unix systems, a checkbutton activates whenever the mouse passes -over it and deactivates whenever the mouse leaves the checkbutton. On -Mac and Windows systems, when mouse button 1 is pressed over a -checkbutton, the button activates whenever the mouse pointer is inside -the button, and deactivates whenever the mouse pointer leaves the -button. -.VE -.IP [2] -When mouse button 1 is pressed over a checkbutton, it is invoked (its -selection state toggles and the command associated with the button is -invoked, if there is one). -.VS -.IP [3] -When a checkbutton has the input focus, the space key causes the checkbutton -to be invoked. Under Windows, there are additional key bindings; plus -(+) and equal (=) select the button, and minus (-) deselects the button. -.VE -.PP -If the checkbutton's state is \fBdisabled\fR then none of the above -actions occur: the checkbutton is completely non-responsive. -.PP -The behavior of checkbuttons can be changed by defining new bindings for -individual widgets or by redefining the class bindings. - -.SH KEYWORDS -checkbutton, widget diff --git a/tcl/doc/chooseColor.n b/tcl/doc/chooseColor.n deleted file mode 100644 index 18b5feffe2..0000000000 --- a/tcl/doc/chooseColor.n +++ /dev/null @@ -1,49 +0,0 @@ -'\" -'\" 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$ -'\" -.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. -.PP -.SH SYNOPSIS -\fBtk_chooseColor \fR?\fIoption value ...\fR? -.BE - -.SH DESCRIPTION -.PP -The procedure \fBtk_chooseColor\fR pops up a dialog box for the -user to select a color. The following \fIoption\-value\fR pairs are -possible as command line arguments: -.TP -\fB\-initialcolor\fR \fIcolor\fR -Specifies the color to display in the color dialog when it pops -up. \fIcolor\fR must be in a form acceptable to the \fBTk_GetColor\fR -function. -.TP -\fB\-parent\fR \fIwindow\fR -Makes \fIwindow\fR the logical parent of the color dialog. The color -dialog is displayed on top of its parent window. -.TP -\fB\-title\fR \fItitleString\fR -Specifies a string to display as the title of the dialog box. If this -option is not specified, then a default title will be displayed. -.LP -If the user selects a color, \fBtk_chooseColor\fR will return the -name of the color in a form acceptable to \fBTk_GetColor\fR. If the -user cancels the operation, both commands will return the empty -string. -.SH EXAMPLE -.CS -button .b \-fg [tk_chooseColor \-initialcolor gray \-title "Choose color"] -.CE - -.SH KEYWORDS -color selection dialog diff --git a/tcl/doc/chooseDirectory.n b/tcl/doc/chooseDirectory.n deleted file mode 100644 index 17edd7e5cc..0000000000 --- a/tcl/doc/chooseDirectory.n +++ /dev/null @@ -1,52 +0,0 @@ -'\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. -'\" All rights reserved. -'\" -'\" RCS: @(#) $Id$ -'\" -.so man.macros -.TH tk_chooseDirectory n 8.3 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -tk_chooseDirectory \- pops up a dialog box for the user to select a directory. -.PP -.SH SYNOPSIS -\fBtk_chooseDirectory \fR?\fIoption value ...\fR? -.BE - -.SH DESCRIPTION -.PP -The procedure \fBtk_chooseDirectory\fR pops up a dialog box for the -user to select a directory. The following \fIoption\-value\fR pairs are -possible as command line arguments: -.TP -\fB\-initialdir\fR \fIdirname\fR -Specifies that the directories in \fIdirectory\fR should be displayed -when the dialog pops up. If this parameter is not specified, then -the directories in the current working directory are displayed. If the -parameter specifies a relative path, the return value will convert the -relative path to an absolute path. This option may not always work on -the Macintosh. This is not a bug. Rather, the \fIGeneral Controls\fR -control panel on the Mac allows the end user to override the -application default directory. -.TP -\fB\-parent\fR \fIwindow\fR -Makes \fIwindow\fR the logical parent of the dialog. The dialog -is displayed on top of its parent window. -.TP -\fB\-title\fR \fItitleString\fR -Specifies a string to display as the title of the dialog box. If this -option is not specified, then a default title will be displayed. -.TP -\fB\-mustexist\fR \fIboolean\fR -Specifies whether the user may specify non-existant directories. If -this parameter is true, then the user may only select directories that -already exist. The default value is \fIfalse\fR. -.LP - -.SH "SEE ALSO" -tk_getOpenFile, tk_getSaveFile - -.SH KEYWORDS -directory selection dialog diff --git a/tcl/doc/clipboard.n b/tcl/doc/clipboard.n deleted file mode 100644 index 0825cf8c0f..0000000000 --- a/tcl/doc/clipboard.n +++ /dev/null @@ -1,94 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH clipboard n 8.4 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -clipboard \- Manipulate Tk clipboard -.SH SYNOPSIS -\fBclipboard \fIoption\fR ?\fIarg arg ...\fR? -.BE - -.SH DESCRIPTION -.PP -This command provides a Tcl interface to the Tk clipboard, -which stores data for later retrieval using the selection mechanism -(via the \fB-selection CLIPBOARD\fR option). -In order to copy data into the clipboard, \fBclipboard clear\fR must -be called, followed by a sequence of one or more calls to \fBclipboard -append\fR. To ensure that the clipboard is updated atomically, all -appends should be completed before returning to the event loop. -.PP -The first argument to \fBclipboard\fR determines the format of the -rest of the arguments and the behavior of the command. The following -forms are currently supported: -.PP -.TP -\fBclipboard clear\fR ?\fB\-displayof\fR \fIwindow\fR? -Claims ownership of the clipboard on \fIwindow\fR's display and removes -any previous contents. \fIWindow\fR defaults to ``.''. Returns an -empty string. -.TP -\fBclipboard append\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-format\fR \fIformat\fR? ?\fB\-type\fR \fItype\fR? ?\fB\-\|\-\fR? \fIdata\fR -Appends \fIdata\fR to the clipboard on \fIwindow\fR's -display in the form given by \fItype\fR with the representation given -by \fIformat\fR and claims ownership of the clipboard on \fIwindow\fR's -display. -.RS -.PP -\fIType\fR specifies the form in which the selection is to be returned -(the desired ``target'' for conversion, in ICCCM terminology), and -should be an atom name such as STRING or FILE_NAME; see the -Inter-Client Communication Conventions Manual for complete details. -\fIType\fR defaults to STRING. -.PP -The \fIformat\fR argument specifies the representation that should be -used to transmit the selection to the requester (the second column of -Table 2 of the ICCCM), and defaults to STRING. If \fIformat\fR is -STRING, the selection is transmitted as 8-bit ASCII characters. If -\fIformat\fR is ATOM, then the \fIdata\fR is -divided into fields separated by white space; each field is converted -to its atom value, and the 32-bit atom value is transmitted instead of -the atom name. For any other \fIformat\fR, \fIdata\fR is divided -into fields separated by white space and each -field is converted to a 32-bit integer; an array of integers is -transmitted to the selection requester. Note that strings passed to -\fBclipboard append\fR are concatenated before conversion, so the -caller must take care to ensure appropriate spacing across string -boundaries. All items appended to the clipboard with the same -\fItype\fR must have the same \fIformat\fR. -.PP -The \fIformat\fR argument is needed only for compatibility with -clipboard requesters that don't use Tk. If the Tk toolkit is being -used to retrieve the CLIPBOARD selection then the value is converted back to -a string at the requesting end, so \fIformat\fR is -irrelevant. -.PP -A \fB\-\|\-\fR argument may be specified to mark the end of options: the -next argument will always be used as \fIdata\fR. -This feature may be convenient if, for example, \fIdata\fR starts -with a \fB\-\fR. -.RE -.TP -.VS 8.4 -\fBclipboard get\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-type\fR? -Retrieve data from the clipboard on \fIwindow\fR's display. -\fIwindow\fR defaults to ".". \fIType\fR specifies the form in which -the data is to be returned and should be an atom name such as STRING -or FILE_NAME. \fIType\fR defaults to STRING. This command is -equivalent to \fBselection get -selection CLIPBOARD\fR. -.VE 8.4 - -.SH "SEE ALSO" -selection - -.SH KEYWORDS -clear, format, clipboard, append, selection, type diff --git a/tcl/doc/colors.n b/tcl/doc/colors.n deleted file mode 100644 index 239de5bcd0..0000000000 --- a/tcl/doc/colors.n +++ /dev/null @@ -1,782 +0,0 @@ -'\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. -'\" All rights reserved. -'\" -'\" RCS: @(#) $Id$ -'\" -'\" -.so man.macros -.TH colors n 8.3 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -colors \- symbolic color names recognized by Tk -.BE -.SH DESCRIPTION -.PP -Tk recognizes many symbolic color names (eg, \fBred\fR) when -specifying colors. The symbolic names recognized by Tk and their -8-bit RGB values are: -.CS -alice blue 240 248 248 -AliceBlue 240 248 248 -antique white 250 235 235 -AntiqueWhite 250 235 235 -AntiqueWhite1 255 239 239 -AntiqueWhite2 238 223 223 -AntiqueWhite3 205 192 192 -AntiqueWhite4 139 131 131 -aquamarine 127 255 255 -aquamarine1 127 255 255 -aquamarine2 118 238 238 -aquamarine3 102 205 205 -aquamarine4 69 139 139 -azure 240 255 255 -azure1 240 255 255 -azure2 224 238 238 -azure3 193 205 205 -azure4 131 139 139 -beige 245 245 245 -bisque 255 228 228 -bisque1 255 228 228 -bisque2 238 213 213 -bisque3 205 183 183 -bisque4 139 125 125 -black 0 0 0 -blanched almond 255 235 235 -BlanchedAlmond 255 235 235 -blue 0 0 255 -blue violet 138 43 43 -blue1 0 0 255 -blue2 0 0 238 -blue3 0 0 205 -blue4 0 0 139 -BlueViolet 138 43 43 -brown 165 42 42 -brown1 255 64 64 -brown2 238 59 59 -brown3 205 51 51 -brown4 139 35 35 -burlywood 222 184 184 -burlywood1 255 211 211 -burlywood2 238 197 197 -burlywood3 205 170 170 -burlywood4 139 115 115 -cadet blue 95 158 158 -CadetBlue 95 158 158 -CadetBlue1 152 245 245 -CadetBlue2 142 229 229 -CadetBlue3 122 197 197 -CadetBlue4 83 134 134 -chartreuse 127 255 255 -chartreuse1 127 255 255 -chartreuse2 118 238 238 -chartreuse3 102 205 205 -chartreuse4 69 139 139 -chocolate 210 105 105 -chocolate1 255 127 127 -chocolate2 238 118 118 -chocolate3 205 102 102 -chocolate4 139 69 69 -coral 255 127 127 -coral1 255 114 114 -coral2 238 106 106 -coral3 205 91 91 -coral4 139 62 62 -cornflower blue 100 149 149 -CornflowerBlue 100 149 149 -cornsilk 255 248 248 -cornsilk1 255 248 248 -cornsilk2 238 232 232 -cornsilk3 205 200 200 -cornsilk4 139 136 136 -cyan 0 255 255 -cyan1 0 255 255 -cyan2 0 238 238 -cyan3 0 205 205 -cyan4 0 139 139 -dark blue 0 0 139 -dark cyan 0 139 139 -dark goldenrod 184 134 134 -dark gray 169 169 169 -dark green 0 100 100 -dark grey 169 169 169 -dark khaki 189 183 183 -dark magenta 139 0 0 -dark olive green 85 107 107 -dark orange 255 140 140 -dark orchid 153 50 50 -dark red 139 0 0 -dark salmon 233 150 150 -dark sea green 143 188 188 -dark slate blue 72 61 61 -dark slate gray 47 79 79 -dark slate grey 47 79 79 -dark turquoise 0 206 206 -dark violet 148 0 0 -DarkBlue 0 0 139 -DarkCyan 0 139 139 -DarkGoldenrod 184 134 134 -DarkGoldenrod1 255 185 185 -DarkGoldenrod2 238 173 173 -DarkGoldenrod3 205 149 149 -DarkGoldenrod4 139 101 101 -DarkGray 169 169 169 -DarkGreen 0 100 100 -DarkGrey 169 169 169 -DarkKhaki 189 183 183 -DarkMagenta 139 0 0 -DarkOliveGreen 85 107 107 -DarkOliveGreen1 202 255 255 -DarkOliveGreen2 188 238 238 -DarkOliveGreen3 162 205 205 -DarkOliveGreen4 110 139 139 -DarkOrange 255 140 140 -DarkOrange1 255 127 127 -DarkOrange2 238 118 118 -DarkOrange3 205 102 102 -DarkOrange4 139 69 69 -DarkOrchid 153 50 50 -DarkOrchid1 191 62 62 -DarkOrchid2 178 58 58 -DarkOrchid3 154 50 50 -DarkOrchid4 104 34 34 -DarkRed 139 0 0 -DarkSalmon 233 150 150 -DarkSeaGreen 143 188 188 -DarkSeaGreen1 193 255 255 -DarkSeaGreen2 180 238 238 -DarkSeaGreen3 155 205 205 -DarkSeaGreen4 105 139 139 -DarkSlateBlue 72 61 61 -DarkSlateGray 47 79 79 -DarkSlateGray1 151 255 255 -DarkSlateGray2 141 238 238 -DarkSlateGray3 121 205 205 -DarkSlateGray4 82 139 139 -DarkSlateGrey 47 79 79 -DarkTurquoise 0 206 206 -DarkViolet 148 0 0 -deep pink 255 20 20 -deep sky blue 0 191 191 -DeepPink 255 20 20 -DeepPink1 255 20 20 -DeepPink2 238 18 18 -DeepPink3 205 16 16 -DeepPink4 139 10 10 -DeepSkyBlue 0 191 191 -DeepSkyBlue1 0 191 191 -DeepSkyBlue2 0 178 178 -DeepSkyBlue3 0 154 154 -DeepSkyBlue4 0 104 104 -dim gray 105 105 105 -dim grey 105 105 105 -DimGray 105 105 105 -DimGrey 105 105 105 -dodger blue 30 144 144 -DodgerBlue 30 144 144 -DodgerBlue1 30 144 144 -DodgerBlue2 28 134 134 -DodgerBlue3 24 116 116 -DodgerBlue4 16 78 78 -firebrick 178 34 34 -firebrick1 255 48 48 -firebrick2 238 44 44 -firebrick3 205 38 38 -firebrick4 139 26 26 -floral white 255 250 250 -FloralWhite 255 250 250 -forest green 34 139 139 -ForestGreen 34 139 139 -gainsboro 220 220 220 -ghost white 248 248 248 -GhostWhite 248 248 248 -gold 255 215 215 -gold1 255 215 215 -gold2 238 201 201 -gold3 205 173 173 -gold4 139 117 117 -goldenrod 218 165 165 -goldenrod1 255 193 193 -goldenrod2 238 180 180 -goldenrod3 205 155 155 -goldenrod4 139 105 105 -gray 190 190 190 -gray0 0 0 0 -gray1 3 3 3 -gray2 5 5 5 -gray3 8 8 8 -gray4 10 10 10 -gray5 13 13 13 -gray6 15 15 15 -gray7 18 18 18 -gray8 20 20 20 -gray9 23 23 23 -gray10 26 26 26 -gray11 28 28 28 -gray12 31 31 31 -gray13 33 33 33 -gray14 36 36 36 -gray15 38 38 38 -.CE -.CS -gray16 41 41 41 -gray17 43 43 43 -gray18 46 46 46 -gray19 48 48 48 -gray20 51 51 51 -gray21 54 54 54 -gray22 56 56 56 -gray23 59 59 59 -gray24 61 61 61 -gray25 64 64 64 -gray26 66 66 66 -gray27 69 69 69 -gray28 71 71 71 -gray29 74 74 74 -gray30 77 77 77 -gray31 79 79 79 -gray32 82 82 82 -gray33 84 84 84 -gray34 87 87 87 -gray35 89 89 89 -gray36 92 92 92 -gray37 94 94 94 -gray38 97 97 97 -gray39 99 99 99 -gray40 102 102 102 -gray41 105 105 105 -gray42 107 107 107 -gray43 110 110 110 -gray44 112 112 112 -gray45 115 115 115 -gray46 117 117 117 -gray47 120 120 120 -gray48 122 122 122 -gray49 125 125 125 -gray50 127 127 127 -gray51 130 130 130 -gray52 133 133 133 -gray53 135 135 135 -gray54 138 138 138 -gray55 140 140 140 -gray56 143 143 143 -gray57 145 145 145 -gray58 148 148 148 -gray59 150 150 150 -gray60 153 153 153 -gray61 156 156 156 -gray62 158 158 158 -gray63 161 161 161 -gray64 163 163 163 -gray65 166 166 166 -gray66 168 168 168 -gray67 171 171 171 -gray68 173 173 173 -gray69 176 176 176 -gray70 179 179 179 -gray71 181 181 181 -gray72 184 184 184 -gray73 186 186 186 -gray74 189 189 189 -gray75 191 191 191 -gray76 194 194 194 -gray77 196 196 196 -gray78 199 199 199 -gray79 201 201 201 -gray80 204 204 204 -gray81 207 207 207 -gray82 209 209 209 -gray83 212 212 212 -gray84 214 214 214 -gray85 217 217 217 -gray86 219 219 219 -gray87 222 222 222 -gray88 224 224 224 -gray89 227 227 227 -gray90 229 229 229 -gray91 232 232 232 -gray92 235 235 235 -gray93 237 237 237 -gray94 240 240 240 -gray95 242 242 242 -gray96 245 245 245 -gray97 247 247 247 -gray98 250 250 250 -gray99 252 252 252 -gray100 255 255 255 -green 0 255 255 -green yellow 173 255 255 -green1 0 255 255 -green2 0 238 238 -green3 0 205 205 -green4 0 139 139 -GreenYellow 173 255 255 -grey 190 190 190 -grey0 0 0 0 -grey1 3 3 3 -grey2 5 5 5 -grey3 8 8 8 -grey4 10 10 10 -grey5 13 13 13 -grey6 15 15 15 -grey7 18 18 18 -grey8 20 20 20 -grey9 23 23 23 -grey10 26 26 26 -grey11 28 28 28 -grey12 31 31 31 -grey13 33 33 33 -grey14 36 36 36 -grey15 38 38 38 -grey16 41 41 41 -grey17 43 43 43 -grey18 46 46 46 -grey19 48 48 48 -grey20 51 51 51 -grey21 54 54 54 -grey22 56 56 56 -grey23 59 59 59 -grey24 61 61 61 -grey25 64 64 64 -grey26 66 66 66 -grey27 69 69 69 -grey28 71 71 71 -grey29 74 74 74 -grey30 77 77 77 -grey31 79 79 79 -grey32 82 82 82 -grey33 84 84 84 -grey34 87 87 87 -grey35 89 89 89 -grey36 92 92 92 -grey37 94 94 94 -grey38 97 97 97 -grey39 99 99 99 -grey40 102 102 102 -grey41 105 105 105 -grey42 107 107 107 -grey43 110 110 110 -grey44 112 112 112 -grey45 115 115 115 -grey46 117 117 117 -grey47 120 120 120 -grey48 122 122 122 -grey49 125 125 125 -grey50 127 127 127 -grey51 130 130 130 -grey52 133 133 133 -grey53 135 135 135 -grey54 138 138 138 -grey55 140 140 140 -grey56 143 143 143 -grey57 145 145 145 -grey58 148 148 148 -grey59 150 150 150 -grey60 153 153 153 -grey61 156 156 156 -grey62 158 158 158 -grey63 161 161 161 -grey64 163 163 163 -grey65 166 166 166 -grey66 168 168 168 -grey67 171 171 171 -grey68 173 173 173 -grey69 176 176 176 -grey70 179 179 179 -grey71 181 181 181 -grey72 184 184 184 -grey73 186 186 186 -grey74 189 189 189 -grey75 191 191 191 -grey76 194 194 194 -grey77 196 196 196 -grey78 199 199 199 -grey79 201 201 201 -grey80 204 204 204 -grey81 207 207 207 -grey82 209 209 209 -grey83 212 212 212 -grey84 214 214 214 -grey85 217 217 217 -grey86 219 219 219 -grey87 222 222 222 -grey88 224 224 224 -grey89 227 227 227 -grey90 229 229 229 -grey91 232 232 232 -grey92 235 235 235 -grey93 237 237 237 -grey94 240 240 240 -grey95 242 242 242 -grey96 245 245 245 -grey97 247 247 247 -grey98 250 250 250 -grey99 252 252 252 -grey100 255 255 255 -honeydew 240 255 255 -honeydew1 240 255 255 -honeydew2 224 238 238 -honeydew3 193 205 205 -honeydew4 131 139 139 -hot pink 255 105 105 -.CE -.CS -HotPink 255 105 105 -HotPink1 255 110 110 -HotPink2 238 106 106 -HotPink3 205 96 96 -HotPink4 139 58 58 -indian red 205 92 92 -IndianRed 205 92 92 -IndianRed1 255 106 106 -IndianRed2 238 99 99 -IndianRed3 205 85 85 -IndianRed4 139 58 58 -ivory 255 255 255 -ivory1 255 255 255 -ivory2 238 238 238 -ivory3 205 205 205 -ivory4 139 139 139 -khaki 240 230 230 -khaki1 255 246 246 -khaki2 238 230 230 -khaki3 205 198 198 -khaki4 139 134 134 -lavender 230 230 230 -lavender blush 255 240 240 -LavenderBlush 255 240 240 -LavenderBlush1 255 240 240 -LavenderBlush2 238 224 224 -LavenderBlush3 205 193 193 -LavenderBlush4 139 131 131 -lawn green 124 252 252 -LawnGreen 124 252 252 -lemon chiffon 255 250 250 -LemonChiffon 255 250 250 -LemonChiffon1 255 250 250 -LemonChiffon2 238 233 233 -LemonChiffon3 205 201 201 -LemonChiffon4 139 137 137 -light blue 173 216 216 -light coral 240 128 128 -light cyan 224 255 255 -light goldenrod 238 221 221 -light goldenrod yellow 250 250 250 -light gray 211 211 211 -light green 144 238 238 -light grey 211 211 211 -light pink 255 182 182 -light salmon 255 160 160 -light sea green 32 178 178 -light sky blue 135 206 206 -light slate blue 132 112 112 -light slate gray 119 136 136 -light slate grey 119 136 136 -light steel blue 176 196 196 -light yellow 255 255 255 -LightBlue 173 216 216 -LightBlue1 191 239 239 -LightBlue2 178 223 223 -LightBlue3 154 192 192 -LightBlue4 104 131 131 -LightCoral 240 128 128 -LightCyan 224 255 255 -LightCyan1 224 255 255 -LightCyan2 209 238 238 -LightCyan3 180 205 205 -LightCyan4 122 139 139 -LightGoldenrod 238 221 221 -LightGoldenrod1 255 236 236 -LightGoldenrod2 238 220 220 -LightGoldenrod3 205 190 190 -LightGoldenrod4 139 129 129 -LightGoldenrodYellow 250 250 250 -LightGray 211 211 211 -LightGreen 144 238 238 -LightGrey 211 211 211 -LightPink 255 182 182 -LightPink1 255 174 174 -LightPink2 238 162 162 -LightPink3 205 140 140 -LightPink4 139 95 95 -LightSalmon 255 160 160 -LightSalmon1 255 160 160 -LightSalmon2 238 149 149 -LightSalmon3 205 129 129 -LightSalmon4 139 87 87 -LightSeaGreen 32 178 178 -LightSkyBlue 135 206 206 -LightSkyBlue1 176 226 226 -LightSkyBlue2 164 211 211 -LightSkyBlue3 141 182 182 -LightSkyBlue4 96 123 123 -LightSlateBlue 132 112 112 -LightSlateGray 119 136 136 -LightSlateGrey 119 136 136 -LightSteelBlue 176 196 196 -LightSteelBlue1 202 225 225 -LightSteelBlue2 188 210 210 -LightSteelBlue3 162 181 181 -LightSteelBlue4 110 123 123 -LightYellow 255 255 255 -LightYellow1 255 255 255 -LightYellow2 238 238 238 -LightYellow3 205 205 205 -LightYellow4 139 139 139 -lime green 50 205 205 -LimeGreen 50 205 205 -linen 250 240 240 -magenta 255 0 0 -magenta1 255 0 0 -magenta2 238 0 0 -magenta3 205 0 0 -magenta4 139 0 0 -maroon 176 48 48 -maroon1 255 52 52 -maroon2 238 48 48 -maroon3 205 41 41 -maroon4 139 28 28 -medium aquamarine 102 205 205 -medium blue 0 0 205 -medium orchid 186 85 85 -medium purple 147 112 112 -medium sea green 60 179 179 -medium slate blue 123 104 104 -medium spring green 0 250 250 -medium turquoise 72 209 209 -medium violet red 199 21 21 -MediumAquamarine 102 205 205 -MediumBlue 0 0 205 -MediumOrchid 186 85 85 -MediumOrchid1 224 102 102 -MediumOrchid2 209 95 95 -MediumOrchid3 180 82 82 -MediumOrchid4 122 55 55 -MediumPurple 147 112 112 -MediumPurple1 171 130 130 -MediumPurple2 159 121 121 -MediumPurple3 137 104 104 -MediumPurple4 93 71 71 -MediumSeaGreen 60 179 179 -MediumSlateBlue 123 104 104 -MediumSpringGreen 0 250 250 -MediumTurquoise 72 209 209 -MediumVioletRed 199 21 21 -midnight blue 25 25 25 -MidnightBlue 25 25 25 -mint cream 245 255 255 -MintCream 245 255 255 -misty rose 255 228 228 -MistyRose 255 228 228 -MistyRose1 255 228 228 -MistyRose2 238 213 213 -MistyRose3 205 183 183 -MistyRose4 139 125 125 -moccasin 255 228 228 -navajo white 255 222 222 -NavajoWhite 255 222 222 -NavajoWhite1 255 222 222 -NavajoWhite2 238 207 207 -NavajoWhite3 205 179 179 -NavajoWhite4 139 121 121 -navy 0 0 128 -navy blue 0 0 128 -NavyBlue 0 0 128 -old lace 253 245 245 -OldLace 253 245 245 -olive drab 107 142 142 -OliveDrab 107 142 142 -OliveDrab1 192 255 255 -OliveDrab2 179 238 238 -OliveDrab3 154 205 205 -OliveDrab4 105 139 139 -orange 255 165 165 -orange red 255 69 69 -orange1 255 165 165 -orange2 238 154 154 -orange3 205 133 133 -orange4 139 90 90 -OrangeRed 255 69 69 -OrangeRed1 255 69 69 -OrangeRed2 238 64 64 -OrangeRed3 205 55 55 -OrangeRed4 139 37 37 -orchid 218 112 112 -orchid1 255 131 131 -orchid2 238 122 122 -orchid3 205 105 105 -orchid4 139 71 71 -pale goldenrod 238 232 232 -pale green 152 251 251 -pale turquoise 175 238 238 -pale violet red 219 112 112 -PaleGoldenrod 238 232 232 -PaleGreen 152 251 251 -PaleGreen1 154 255 255 -PaleGreen2 144 238 238 -PaleGreen3 124 205 205 -PaleGreen4 84 139 139 -PaleTurquoise 175 238 238 -PaleTurquoise1 187 255 255 -PaleTurquoise2 174 238 238 -PaleTurquoise3 150 205 205 -PaleTurquoise4 102 139 139 -.CE -.CS -PaleVioletRed 219 112 112 -PaleVioletRed1 255 130 130 -PaleVioletRed2 238 121 121 -PaleVioletRed3 205 104 104 -PaleVioletRed4 139 71 71 -papaya whip 255 239 239 -PapayaWhip 255 239 239 -peach puff 255 218 218 -PeachPuff 255 218 218 -PeachPuff1 255 218 218 -PeachPuff2 238 203 203 -PeachPuff3 205 175 175 -PeachPuff4 139 119 119 -peru 205 133 133 -pink 255 192 192 -pink1 255 181 181 -pink2 238 169 169 -pink3 205 145 145 -pink4 139 99 99 -plum 221 160 160 -plum1 255 187 187 -plum2 238 174 174 -plum3 205 150 150 -plum4 139 102 102 -powder blue 176 224 224 -PowderBlue 176 224 224 -purple 160 32 32 -purple1 155 48 48 -purple2 145 44 44 -purple3 125 38 38 -purple4 85 26 26 -red 255 0 0 -red1 255 0 0 -red2 238 0 0 -red3 205 0 0 -red4 139 0 0 -rosy brown 188 143 143 -RosyBrown 188 143 143 -RosyBrown1 255 193 193 -RosyBrown2 238 180 180 -RosyBrown3 205 155 155 -RosyBrown4 139 105 105 -royal blue 65 105 105 -RoyalBlue 65 105 105 -RoyalBlue1 72 118 118 -RoyalBlue2 67 110 110 -RoyalBlue3 58 95 95 -RoyalBlue4 39 64 64 -saddle brown 139 69 69 -SaddleBrown 139 69 69 -salmon 250 128 128 -salmon1 255 140 140 -salmon2 238 130 130 -salmon3 205 112 112 -salmon4 139 76 76 -sandy brown 244 164 164 -SandyBrown 244 164 164 -sea green 46 139 139 -SeaGreen 46 139 139 -SeaGreen1 84 255 255 -SeaGreen2 78 238 238 -SeaGreen3 67 205 205 -SeaGreen4 46 139 139 -seashell 255 245 245 -seashell1 255 245 245 -seashell2 238 229 229 -seashell3 205 197 197 -seashell4 139 134 134 -sienna 160 82 82 -sienna1 255 130 130 -sienna2 238 121 121 -sienna3 205 104 104 -sienna4 139 71 71 -sky blue 135 206 206 -SkyBlue 135 206 206 -SkyBlue1 135 206 206 -SkyBlue2 126 192 192 -SkyBlue3 108 166 166 -SkyBlue4 74 112 112 -slate blue 106 90 90 -slate gray 112 128 128 -slate grey 112 128 128 -SlateBlue 106 90 90 -SlateBlue1 131 111 111 -SlateBlue2 122 103 103 -SlateBlue3 105 89 89 -SlateBlue4 71 60 60 -SlateGray 112 128 128 -SlateGray1 198 226 226 -SlateGray2 185 211 211 -SlateGray3 159 182 182 -SlateGray4 108 123 123 -SlateGrey 112 128 128 -snow 255 250 250 -snow1 255 250 250 -snow2 238 233 233 -snow3 205 201 201 -snow4 139 137 137 -spring green 0 255 255 -SpringGreen 0 255 255 -SpringGreen1 0 255 255 -SpringGreen2 0 238 238 -SpringGreen3 0 205 205 -SpringGreen4 0 139 139 -steel blue 70 130 130 -SteelBlue 70 130 130 -SteelBlue1 99 184 184 -SteelBlue2 92 172 172 -SteelBlue3 79 148 148 -SteelBlue4 54 100 100 -tan 210 180 180 -tan1 255 165 165 -tan2 238 154 154 -tan3 205 133 133 -tan4 139 90 90 -thistle 216 191 191 -thistle1 255 225 225 -thistle2 238 210 210 -thistle3 205 181 181 -thistle4 139 123 123 -tomato 255 99 99 -tomato1 255 99 99 -tomato2 238 92 92 -tomato3 205 79 79 -tomato4 139 54 54 -turquoise 64 224 224 -turquoise1 0 245 245 -turquoise2 0 229 229 -turquoise3 0 197 197 -turquoise4 0 134 134 -violet 238 130 130 -violet red 208 32 32 -VioletRed 208 32 32 -VioletRed1 255 62 62 -VioletRed2 238 58 58 -VioletRed3 205 50 50 -VioletRed4 139 34 34 -wheat 245 222 222 -wheat1 255 231 231 -wheat2 238 216 216 -wheat3 205 186 186 -wheat4 139 126 126 -white 255 255 255 -white smoke 245 245 245 -WhiteSmoke 245 245 245 -yellow 255 255 255 -yellow green 154 205 205 -yellow1 255 255 255 -yellow2 238 238 238 -yellow3 205 205 205 -yellow4 139 139 139 -YellowGreen 154 205 205 -.CE - -.SH KEYWORDS -color, option diff --git a/tcl/doc/console.n b/tcl/doc/console.n deleted file mode 100644 index 8b80e4bb52..0000000000 --- a/tcl/doc/console.n +++ /dev/null @@ -1,142 +0,0 @@ -'\" -'\" Copyright (c) 2001 Donal K. Fellows -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id$ -'\" -.so man.macros -.TH console n 8.4 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -console \- Control the console on systems without a real console -.SH SYNOPSIS -\fBconsole title \fR?\fIstring\fR? -.sp -\fBconsole hide\fR -.sp -\fBconsole show\fR -.sp -\fBconsole eval \fIscript\fR -.BE - -.SH DESCRIPTION -.PP -The console window is a replacement for a real console to allow input -and output on the standard I/O channels on platforms that do not have -a real console. It is implemented as a separate interpreter with the -Tk toolkit loaded, and control over this interpreter is given through -the \fBconsole\fR command. The behaviour of the console window is -defined mainly through the contents of the \fIconsole.tcl\fR file in -the Tk library (or the \fIConsole\fR resource on Macintosh systems.) -.PP -.TP -\fBconsole eval \fIscript\fR -Evaluate the \fIscript\fR argument as a Tcl script in the console -interpreter. The normal interpreter is accessed through the -\fBconsoleinterp\fR command in the console interpreter. -.TP -\fBconsole hide\fR -Hide the console window from view. Precisely equivalent to -withdrawing the \fB.\fR window in the console interpreter. -.TP -\fBconsole show\fR -Display the console window. Precisely equivalent to deiconifying the -\fB.\fR window in the console interpreter. -.TP -\fBconsole title \fR?\fIstring\fR? -Query or modify the title of the console window. If \fIstring\fR is -not specified, queries the title of the console window, and sets the -title of the console window to \fIstring\fR otherwise. Precisely -equivalent to using the \fBwm title\fR command in the console -interpreter. - -.SH "ACCESS TO THE MAIN INTERPRETER" -.PP -The \fBconsoleinterp\fR command in the console interpreter allows -scripts to be evaluated in the main interpreter. It supports two -subcommands: \fBeval\fR and \fBrecord\fR. -.PP -.TP -\fBconsoleinterp eval \fIscript\fR -Evaluates \fIscript\fR as a Tcl script at the global level in the main -interpreter. -.TP -\fBconsoleinterp record \fIscript\fR -Records and evaluates \fIscript\fR as a Tcl script at the global level -in the main interpreter as if \fIscript\fR had been typed in at the -console. - -.SH "ADDITIONAL TRAP CALLS" -.PP -There are several additional commands in the console interpreter that -are called in response to activity in the main interpreter. -\fIThese are documented here for completeness only; they form part of -the internal implementation of the console and are likely to change or -be modified without warning.\fR -.PP -Output to the console from the main interpreter via the stdout and -stderr channels is handled by invoking the \fBtk::ConsoleOutput\fR -command in the console interpreter with two arguments. The first -argument is the name of the channel being written to, and the second -argument is the string being written to the channel (after encoding -and end-of-line translation processing has been performed.) -.PP -When the \fB.\fR window of the main interpreter is destroyed, the -\fBtk::ConsoleExit\fR command in the console interpreter is called -(assuming the console interpreter has not already been deleted itself, -that is.) - -.SH "DEFAULT BINDINGS" -.PP -The default script creates a console window (implemented using a text -widget) that has the following behaviour: -.IP [1] -Pressing the tab key inserts a TAB character (as defined by the Tcl -\et escape.) -.IP [2] -Pressing the return key causes the current line (if complete by the -rules of \fBinfo complete\fR) to be passed to the main interpreter for -evaluation. -.IP [3] -Pressing the delete key deletes the selected text (if any text is -selected) or the character to the right of the cursor (if not at the -end of the line.) -.IP [4] -Pressing the backspace key deletes the selected text (if any text is -selected) or the character to the left of the cursor (of not at the -start of the line.) -.IP [5] -Pressing either Control+A or the home key causes the cursor to go to -the start of the line (but after the prompt, if a prompt is present on -the line.) -.IP [6] -Pressing either Control+E or the end key causes the cursor to go to -the end of the line. -.IP [7] -Pressing either Control+P or the up key causes the previous entry in -the command history to be selected. -.IP [8] -Pressing either Control+N or the down key causes the next entry in the -command history to be selected. -.IP [9] -Pressing either Control+B or the left key causes the cursor to move -one character backward as long as the cursor is not at the prompt. -.IP [10] -Pressing either Control+F or the right key causes the cursor to move -one character forward. -.IP [11] -Pressing F9 rebuilds the console window by destroying all its children -and reloading the Tcl script that defined the console's behaviour. -.PP -Most other behaviour is the same as a conventional text widget except -for the way that the \fI<>\fR event is handled identically to the -\fI<>\fR event. - -.SH KEYWORDS -console, interpreter, window, interactive, output channels - -.SH "SEE ALSO" -destroy(n), fconfigure(n), history(n), interp(n), puts(n), text(n), wm(n) diff --git a/tcl/doc/cursors.n b/tcl/doc/cursors.n deleted file mode 100644 index c93d375259..0000000000 --- a/tcl/doc/cursors.n +++ /dev/null @@ -1,154 +0,0 @@ -'\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. -'\" All rights reserved. -'\" -'\" RCS: @(#) $Id$ -'\" -'\" -.so man.macros -.TH cursors n 8.3 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -cursors \- mouse cursors available in Tk - -.SH DESCRIPTION -.PP -The \fB-cursor\fR widget option allows a Tk programmer to change the -mouse cursor for a particular widget. The cursor names recognized by -Tk on all platforms are: -.CS -X_cursor -arrow -based_arrow_down -based_arrow_up -boat -bogosity -bottom_left_corner -bottom_right_corner -bottom_side -bottom_tee -box_spiral -center_ptr -circle -clock -coffee_mug -cross -cross_reverse -crosshair -diamond_cross -dot -dotbox -double_arrow -draft_large -draft_small -draped_box -exchange -fleur -gobbler -gumby -hand1 -hand2 -heart -icon -iron_cross -left_ptr -left_side -left_tee -leftbutton -ll_angle -lr_angle -man -middlebutton -mouse -pencil -pirate -plus -question_arrow -right_ptr -right_side -right_tee -rightbutton -rtl_logo -sailboat -sb_down_arrow -sb_h_double_arrow -sb_left_arrow -sb_right_arrow -sb_up_arrow -sb_v_double_arrow -shuttle -sizing -spider -spraycan -star -target -tcross -top_left_arrow -top_left_corner -top_right_corner -top_side -top_tee -trek -ul_angle -umbrella -ur_angle -watch -xterm -.CE - -.SH "PORTABILITY ISSUES" - -.TP -\fBWindows\fR -On Windows systems, the following cursors are mapped to native cursors: -.RS -.CS -arrow -center_ptr -crosshair -fleur -ibeam -icon -sb_h_double_arrow -sb_v_double_arrow -watch -xterm -.CE -And the following additional cursors are available: -.CS -no -starting -size -size_ne_sw -size_ns -size_nw_se -size_we -uparrow -wait -.CE -The \fBno\fR cursor can be specified to eliminate the cursor. -.RE - -.TP -\fBMacintosh\fR -On Macintosh systems, the following cursors are mapped to native cursors: -.RS -.CS -arrow -cross -crosshair -ibeam -plus -watch -xterm -.CE -And the following additional cursors are available: -.CS -text -cross-hair -.CE -.RE - -.SH KEYWORDS -cursor, option diff --git a/tcl/doc/destroy.n b/tcl/doc/destroy.n deleted file mode 100644 index f144ad86eb..0000000000 --- a/tcl/doc/destroy.n +++ /dev/null @@ -1,34 +0,0 @@ -'\" -'\" 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$ -'\" -.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 -.SH SYNOPSIS -\fBdestroy \fR?\fIwindow window ...\fR? -.BE - -.SH DESCRIPTION -.VS -.PP -This command deletes the windows given by the -\fIwindow\fR arguments, plus all of their descendants. -If a \fIwindow\fR ``.'' is deleted then the entire application -will be destroyed. -The \fIwindow\fRs are destroyed in order, and if an error occurs -in destroying a window the command aborts without destroying the -remaining windows. -No error is returned if \fIwindow\fR does not exist. -.VE - -.SH KEYWORDS -application, destroy, window diff --git a/tcl/doc/dialog.n b/tcl/doc/dialog.n deleted file mode 100644 index bd30e197b1..0000000000 --- a/tcl/doc/dialog.n +++ /dev/null @@ -1,65 +0,0 @@ -'\" -'\" 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$ -'\" -.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 -.SH SYNOPSIS -\fBtk_dialog \fIwindow title text bitmap default string string ...\fR -.BE - -.SH DESCRIPTION -.PP -This procedure is part of the Tk script library. -Its arguments describe a dialog box: -.TP -\fIwindow\fR -Name of top-level window to use for dialog. Any existing window -by this name is destroyed. -.TP -\fItitle\fR -Text to appear in the window manager's title bar for the dialog. -.TP -\fItext\fR -Message to appear in the top portion of the dialog box. -.TP -\fIbitmap\fR -If non-empty, specifies a bitmap to display in the top portion of -the dialog, to the left of the text. -If this is an empty string then no bitmap is displayed in the dialog. -.TP -\fIdefault\fR -If this is an integer greater than or equal to zero, then it gives -the index of the button that is to be the default button for the dialog -(0 for the leftmost button, and so on). -If less than zero or an empty string then there won't be any default -button. -.TP -\fIstring\fR -There will be one button for each of these arguments. -Each \fIstring\fR specifies text to display in a button, -in order from left to right. -.PP -After creating a dialog box, \fBtk_dialog\fR waits for the user to -select one of the buttons either by clicking on the button with the -mouse or by typing return to invoke the default button (if any). -Then it returns the index of the selected button: 0 for the leftmost -button, 1 for the button next to it, and so on. -If the dialog's window is destroyed before the user selects one -of the buttons, then -1 is returned. -.PP -While waiting for the user to respond, \fBtk_dialog\fR sets a local -grab. This prevents the user from interacting with the application -in any way except to invoke the dialog box. - -.SH KEYWORDS -bitmap, dialog, modal diff --git a/tcl/doc/entry.n b/tcl/doc/entry.n deleted file mode 100644 index a00fb6c2fb..0000000000 --- a/tcl/doc/entry.n +++ /dev/null @@ -1,549 +0,0 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" Copyright (c) 1998-2000 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$ -'\" -.so man.macros -.TH entry n 8.3 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -entry \- Create and manipulate entry widgets -.SH SYNOPSIS -\fBentry\fR \fIpathName \fR?\fIoptions\fR? -.SO -\-background \-highlightthickness \-selectbackground -\-borderwidth \-insertbackground \-selectborderwidth -\-cursor \-insertborderwidth \-selectforeground -\-exportselection \-insertofftime \-takefocus -\-font \-insertontime \-textvariable -\-foreground \-insertwidth \-xscrollcommand -\-highlightbackground \-justify -\-highlightcolor \-relief -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.VS 8.4 -.OP \-disabledbackground disabledBackground DisabledBackground -Specifies the background color to use when the entry is disabled. If -this option is the empty string, the normal background color is used. -.OP \-disabledforeground disabledForeground DisabledForeground -Specifies the foreground color to use when the entry is disabled. If -this option is the empty string, the normal foreground color is used. -.VE 8.4 -.VS 8.3 -.OP "\-invalidcommand or \-invcmd" invalidCommand InvalidCommand -Specifies a script to eval when \fBvalidateCommand\fR returns 0. -Setting it to {} disables this feature (the default). The best use -of this option is to set it to \fIbell\fR. See \fBValidation\fR -below for more information. -.VE -.VS 8.4 -.OP \-readonlybackground readonlyBackground ReadonlyBackground -Specifies the background color to use when the entry is readonly. If -this option is the empty string, the normal background color is used. -.VE -.OP \-show show Show -If this option is specified, then the true contents of the entry -are not displayed in the window. -Instead, each character in the entry's value will be displayed as -the first character in the value of this option, such as ``*''. -This is useful, for example, if the entry is to be used to enter -a password. -If characters in the entry are selected and copied elsewhere, the -information copied will be what is displayed, not the true contents -of the entry. -.VS 8.4 -.OP \-state state State -Specifies one of three states for the entry: \fBnormal\fR, -\fBdisabled\fR, or \fBreadonly\fR. If the entry is readonly, then the -value may not be changed using widget commands and no insertion cursor -will be displayed, even if the input focus is in the widget; the -contents of the widget may still be selected. If the entry is -disabled, the value may not be changed, no insertion cursor will be -displayed, the contents will not be selectable, and the entry may -be displayed in a different color, depending on the values of the -\fB-disabledforeground\fR and \fB-disabledbackground\fR options. -.VE 8.4 -.VS 8.3 -.OP \-validate validate Validate -Specifies the mode in which validation should operate: \fBnone\fR, -\fBfocus\fR, \fBfocusin\fR, \fBfocusout\fR, \fBkey\fR, or \fBall\fR. -It defaults to \fBnone\fR. When you want validation, you must explicitly -state which mode you wish to use. See \fBValidation\fR below for more. -.OP "\-validatecommand or \-vcmd" validateCommand ValidateCommand -Specifies a script to eval when you want to validate the input into -the entry widget. Setting it to {} disables this feature (the default). -This command must return a valid tcl boolean value. If it returns 0 (or -the valid tcl boolean equivalent) then it means you reject the new edition -and it will not occur and the \fBinvalidCommand\fR will be evaluated if it -is set. If it returns 1, then the new edition occurs. -See \fBValidation\fR below for more information. -.VE -.OP \-width width Width -Specifies an integer value indicating the desired width of the entry window, -in average-size characters of the widget's font. -If the value is less than or equal to zero, the widget picks a -size just large enough to hold its current text. -.BE - -.SH DESCRIPTION -.PP -The \fBentry\fR command creates a new window (given by the -\fIpathName\fR argument) and makes it into an entry widget. -Additional options, described above, may be specified on the -command line or in the option database -to configure aspects of the entry such as its colors, font, -and relief. The \fBentry\fR command returns its -\fIpathName\fR argument. At the time this command is invoked, -there must not exist a window named \fIpathName\fR, but -\fIpathName\fR's parent must exist. -.PP -An entry is a widget that displays a one-line text string and -allows that string to be edited using widget commands described below, which -are typically bound to keystrokes and mouse actions. -When first created, an entry's string is empty. -A portion of the entry may be selected as described below. -If an entry is exporting its selection (see the \fBexportSelection\fR -option), then it will observe the standard X11 protocols for handling the -selection; entry selections are available as type \fBSTRING\fR. -Entries also observe the standard Tk rules for dealing with the -input focus. When an entry has the input focus it displays an -\fIinsertion cursor\fR to indicate where new characters will be -inserted. -.PP -Entries are capable of displaying strings that are too long to -fit entirely within the widget's window. In this case, only a -portion of the string will be displayed; commands described below -may be used to change the view in the window. Entries use -the standard \fBxScrollCommand\fR mechanism for interacting with -scrollbars (see the description of the \fBxScrollCommand\fR option -for details). They also support scanning, as described below. - -.VS 8.3 -.SH VALIDATION -.PP -Validation works by setting the \fBvalidateCommand\fR -option to a script which will be evaluated according to the \fBvalidate\fR -option as follows: -.PP -.IP \fBnone\fR 10 -Default. This means no validation will occur. -.IP \fBfocus\fR 10 -\fBvalidateCommand\fR will be called when the entry receives or -loses focus. -.IP \fBfocusin\fR 10 -\fBvalidateCommand\fR will be called when the entry receives focus. -.IP \fBfocusout\fR 10 -\fBvalidateCommand\fR will be called when the entry loses focus. -.IP \fBkey\fR 10 -\fBvalidateCommand\fR will be called when the entry is edited. -.IP \fBall\fR 10 -\fBvalidateCommand\fR will be called for all above conditions. -.PP -It is possible to perform percent substitutions on the \fBvalidateCommand\fR -and \fBinvalidCommand\fR, -just as you would in a \fBbind\fR script. The following substitutions -are recognized: -.PP -.IP \fB%d\fR 5 -Type of action: 1 for \fBinsert\fR, 0 for \fBdelete\fR, -or -1 for focus, forced or textvariable validation. -.IP \fB%i\fR 5 -Index of char string to be inserted/deleted, if any, otherwise -1. -.IP \fB%P\fR 5 -The value of the entry should edition occur. If you are configuring the -entry widget to have a new textvariable, this will be the value of that -textvariable. -.IP \fB%s\fR 5 -The current value of entry before edition. -.IP \fB%S\fR 5 -The text string being inserted/deleted, if any, {} otherwise. -.IP \fB%v\fR 5 -The type of validation currently set. -.IP \fB%V\fR 5 -The type of validation that triggered the callback -(key, focusin, focusout, forced). -.IP \fB%W\fR 5 -The name of the entry widget. -.PP -In general, the \fBtextVariable\fR and \fBvalidateCommand\fR can be -dangerous to mix. Any problems have been overcome so that using the -\fBvalidateCommand\fR will not interfere with the traditional behavior of -the entry widget. Using the \fBtextVariable\fR for read-only purposes will -never cause problems. The danger comes when you try set the -\fBtextVariable\fR to something that the \fBvalidateCommand\fR would not -accept, which causes \fBvalidate\fR to become \fInone\fR (the -\fBinvalidCommand\fR will not be triggered). The same happens -when an error occurs evaluating the \fBvalidateCommand\fR. -.PP -Primarily, an error will occur when the \fBvalidateCommand\fR or -\fBinvalidCommand\fR encounters an error in its script while evaluating or -\fBvalidateCommand\fR does not return a valid tcl boolean value. The -\fBvalidate\fR option will also set itself to \fBnone\fR when you edit the -entry widget from within either the \fBvalidateCommand\fR or the -\fBinvalidCommand\fR. Such editions will override the one that was being -validated. If you wish to edit the entry widget (for example set it to {}) -during validation and still have the \fBvalidate\fR option set, you should -include the command -.CS - \fIafter idle {%W config -validate %v}\fR -.CE -in the \fBvalidateCommand\fR or \fBinvalidCommand\fR (whichever one you -were editing the entry widget from). It is also recommended to not set an -associated \fBtextVariable\fR during validation, as that can cause the -entry widget to become out of sync with the \fBtextVariable\fR. -.VE - -.SH "WIDGET COMMAND" -.PP -The \fBentry\fR command creates a new Tcl command whose -name is \fIpathName\fR. This command may be used to invoke various -operations on the widget. It has the following general form: -.CS -\fIpathName option \fR?\fIarg arg ...\fR? -.CE -\fIOption\fR and the \fIarg\fRs -determine the exact behavior of the command. -.PP -Many of the widget commands for entries take one or more indices as -arguments. An index specifies a particular character in the entry's -string, in any of the following ways: -.TP 12 -\fInumber\fR -Specifies the character as a numerical index, where 0 corresponds -to the first character in the string. -.TP 12 -\fBanchor\fR -Indicates the anchor point for the selection, which is set with the -\fBselect from\fR and \fBselect adjust\fR widget commands. -.TP 12 -\fBend\fR -Indicates the character just after the last one in the entry's string. -This is equivalent to specifying a numerical index equal to the length -of the entry's string. -.TP 12 -\fBinsert\fR -Indicates the character adjacent to and immediately following the -insertion cursor. -.TP 12 -\fBsel.first\fR -Indicates the first character in the selection. It is an error to -use this form if the selection isn't in the entry window. -.TP 12 -\fBsel.last\fR -Indicates the character just after the last one in the selection. -It is an error to use this form if the selection isn't in the -entry window. -.TP 12 -\fB@\fInumber\fR -In this form, \fInumber\fR is treated as an x-coordinate in the -entry's window; the character spanning that x-coordinate is used. -For example, ``\fB@0\fR'' indicates the left-most character in the -window. -.LP -Abbreviations may be used for any of the forms above, e.g. ``\fBe\fR'' -or ``\fBsel.f\fR''. In general, out-of-range indices are automatically -rounded to the nearest legal value. -.PP -The following commands are possible for entry widgets: -.TP -\fIpathName \fBbbox \fIindex\fR -Returns a list of four numbers describing the bounding box of the -character given by \fIindex\fR. -The first two elements of the list give the x and y coordinates of -the upper-left corner of the screen area covered by the character -(in pixels relative to the widget) and the last two elements give -the width and height of the character, in pixels. -The bounding box may refer to a region outside the visible area -of the window. -.TP -\fIpathName \fBcget\fR \fIoption\fR -Returns the current value of the configuration option given -by \fIoption\fR. -\fIOption\fR may have any of the values accepted by the \fBentry\fR -command. -.TP -\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -Query or modify the configuration options of the widget. -If no \fIoption\fR is specified, returns a list describing all of -the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for -information on the format of this list). If \fIoption\fR is specified -with no \fIvalue\fR, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no \fIoption\fR is specified). If -one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given widget option(s) to have the given value(s); in -this case the command returns an empty string. -\fIOption\fR may have any of the values accepted by the \fBentry\fR -command. -.TP -\fIpathName \fBdelete \fIfirst \fR?\fIlast\fR? -Delete one or more elements of the entry. -\fIFirst\fR is the index of the first character to delete, and -\fIlast\fR is the index of the character just after the last -one to delete. -If \fIlast\fR isn't specified it defaults to \fIfirst\fR+1, -i.e. a single character is deleted. -This command returns an empty string. -.TP -\fIpathName \fBget\fR -Returns the entry's string. -.TP -\fIpathName \fBicursor \fIindex\fR -Arrange for the insertion cursor to be displayed just before the character -given by \fIindex\fR. Returns an empty string. -.TP -\fIpathName \fBindex\fI index\fR -Returns the numerical index corresponding to \fIindex\fR. -.TP -\fIpathName \fBinsert \fIindex string\fR -Insert the characters of \fIstring\fR just before the character -indicated by \fIindex\fR. Returns an empty string. -.TP -\fIpathName \fBscan\fR \fIoption args\fR -This command is used to implement scanning on entries. It has -two forms, depending on \fIoption\fR: -.RS -.TP -\fIpathName \fBscan mark \fIx\fR -Records \fIx\fR and the current view in the entry window; used in -conjunction with later \fBscan dragto\fR commands. Typically this -command is associated with a mouse button press in the widget. It -returns an empty string. -.TP -\fIpathName \fBscan dragto \fIx\fR -This command computes the difference between its \fIx\fR argument -and the \fIx\fR argument to the last \fBscan mark\fR command for -the widget. It then adjusts the view left or right by 10 times the -difference in x-coordinates. This command is typically associated -with mouse motion events in the widget, to produce the effect of -dragging the entry at high speed through the window. The return -value is an empty string. -.RE -.TP -\fIpathName \fBselection \fIoption arg\fR -This command is used to adjust the selection within an entry. It -has several forms, depending on \fIoption\fR: -.RS -.TP -\fIpathName \fBselection adjust \fIindex\fR -Locate the end of the selection nearest to the character given by -\fIindex\fR, and adjust that end of the selection to be at \fIindex\fR -(i.e including but not going beyond \fIindex\fR). The other -end of the selection is made the anchor point for future -\fBselect to\fR commands. If the selection -isn't currently in the entry, then a new selection is created to -include the characters between \fIindex\fR and the most recent -selection anchor point, inclusive. -Returns an empty string. -.TP -\fIpathName \fBselection clear\fR -Clear the selection if it is currently in this widget. If the -selection isn't in this widget then the command has no effect. -Returns an empty string. -.TP -\fIpathName \fBselection from \fIindex\fR -Set the selection anchor point to just before the character -given by \fIindex\fR. Doesn't change the selection. -Returns an empty string. -.TP -\fIpathName \fBselection present\fR -Returns 1 if there is are characters selected in the entry, -0 if nothing is selected. -.TP -\fIpathName \fBselection range \fIstart\fR \fIend\fR -Sets the selection to include the characters starting with -the one indexed by \fIstart\fR and ending with the one just -before \fIend\fR. -If \fIend\fR refers to the same character as \fIstart\fR or an -earlier one, then the entry's selection is cleared. -.TP -\fIpathName \fBselection to \fIindex\fR -If \fIindex\fR is before the anchor point, set the selection -to the characters from \fIindex\fR up to but not including -the anchor point. -If \fIindex\fR is the same as the anchor point, do nothing. -If \fIindex\fR is after the anchor point, set the selection -to the characters from the anchor point up to but not including -\fIindex\fR. -The anchor point is determined by the most recent \fBselect from\fR -or \fBselect adjust\fR command in this widget. -If the selection isn't in this widget then a new selection is -created using the most recent anchor point specified for the widget. -Returns an empty string. -.RE -.TP -.VS 8.3 -\fIpathName \fBvalidate\fR -This command is used to force an evaluation of the \fBvalidateCommand\fR -independent of the conditions specified by the \fBvalidate\fR option. -This is done by temporarily setting the \fBvalidate\fR option to \fBall\fR. -It returns 0 or 1. -.VE -.TP -\fIpathName \fBxview \fIargs\fR -This command is used to query and change the horizontal position of the -text in the widget's window. It can take any of the following -forms: -.RS -.TP -\fIpathName \fBxview\fR -Returns a list containing two elements. -Each element is a real fraction between 0 and 1; together they describe -the horizontal span that is visible in the window. -For example, if the first element is .2 and the second element is .6, -20% of the entry's text is off-screen to the left, the middle 40% is visible -in the window, and 40% of the text is off-screen to the right. -These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR -option. -.TP -\fIpathName \fBxview\fR \fIindex\fR -Adjusts the view in the window so that the character given by \fIindex\fR -is displayed at the left edge of the window. -.TP -\fIpathName \fBxview moveto\fI fraction\fR -Adjusts the view in the window so that the character \fIfraction\fR of the -way through the text appears at the left edge of the window. -\fIFraction\fR must be a fraction between 0 and 1. -.TP -\fIpathName \fBxview scroll \fInumber what\fR -This command shifts the view in the window left or right according to -\fInumber\fR and \fIwhat\fR. -\fINumber\fR must be an integer. -\fIWhat\fR must be either \fBunits\fR or \fBpages\fR or an abbreviation -of one of these. -If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by -\fInumber\fR average-width characters on the display; if it is -\fBpages\fR then the view adjusts by \fInumber\fR screenfuls. -If \fInumber\fR is negative then characters farther to the left -become visible; if it is positive then characters farther to the right -become visible. -.RE - -.SH "DEFAULT BINDINGS" -.PP -Tk automatically creates class bindings for entries that give them -the following default behavior. -In the descriptions below, ``word'' refers to a contiguous group -of letters, digits, or ``_'' characters, or any single character -other than these. -.IP [1] -Clicking mouse button 1 positions the insertion cursor -just before the character underneath the mouse cursor, sets the -input focus to this widget, and clears any selection in the widget. -Dragging with mouse button 1 strokes out a selection between -the insertion cursor and the character under the mouse. -.IP [2] -Double-clicking with mouse button 1 selects the word under the mouse -and positions the insertion cursor at the beginning of the word. -Dragging after a double click will stroke out a selection consisting -of whole words. -.IP [3] -Triple-clicking with mouse button 1 selects all of the text in the -entry and positions the insertion cursor before the first character. -.IP [4] -The ends of the selection can be adjusted by dragging with mouse -button 1 while the Shift key is down; this will adjust the end -of the selection that was nearest to the mouse cursor when button -1 was pressed. -If the button is double-clicked before dragging then the selection -will be adjusted in units of whole words. -.IP [5] -Clicking mouse button 1 with the Control key down will position the -insertion cursor in the entry without affecting the selection. -.IP [6] -If any normal printing characters are typed in an entry, they are -inserted at the point of the insertion cursor. -.IP [7] -The view in the entry can be adjusted by dragging with mouse button 2. -If mouse button 2 is clicked without moving the mouse, the selection -is copied into the entry at the position of the mouse cursor. -.IP [8] -If the mouse is dragged out of the entry on the left or right sides -while button 1 is pressed, the entry will automatically scroll to -make more text visible (if there is more text off-screen on the side -where the mouse left the window). -.IP [9] -The Left and Right keys move the insertion cursor one character to the -left or right; they also clear any selection in the entry and set -the selection anchor. -If Left or Right is typed with the Shift key down, then the insertion -cursor moves and the selection is extended to include the new character. -Control-Left and Control-Right move the insertion cursor by words, and -Control-Shift-Left and Control-Shift-Right move the insertion cursor -by words and also extend the selection. -Control-b and Control-f behave the same as Left and Right, respectively. -Meta-b and Meta-f behave the same as Control-Left and Control-Right, -respectively. -.IP [10] -The Home key, or Control-a, will move the insertion cursor to the -beginning of the entry and clear any selection in the entry. -Shift-Home moves the insertion cursor to the beginning of the entry -and also extends the selection to that point. -.IP [11] -The End key, or Control-e, will move the insertion cursor to the -end of the entry and clear any selection in the entry. -Shift-End moves the cursor to the end and extends the selection -to that point. -.IP [12] -The Select key and Control-Space set the selection anchor to the position -of the insertion cursor. They don't affect the current selection. -Shift-Select and Control-Shift-Space adjust the selection to the -current position of the insertion cursor, selecting from the anchor -to the insertion cursor if there was not any selection previously. -.IP [13] -Control-/ selects all the text in the entry. -.IP [14] -Control-\e clears any selection in the entry. -.IP [15] -The F16 key (labelled Copy on many Sun workstations) or Meta-w -copies the selection in the widget to the clipboard, if there is a selection. -.IP [16] -The F20 key (labelled Cut on many Sun workstations) or Control-w -copies the selection in the widget to the clipboard and deletes -the selection. -If there is no selection in the widget then these keys have no effect. -.IP [17] -The F18 key (labelled Paste on many Sun workstations) or Control-y -inserts the contents of the clipboard at the position of the -insertion cursor. -.IP [18] -The Delete key deletes the selection, if there is one in the entry. -If there is no selection, it deletes the character to the right of -the insertion cursor. -.IP [19] -The BackSpace key and Control-h delete the selection, if there is one -in the entry. -If there is no selection, it deletes the character to the left of -the insertion cursor. -.IP [20] -Control-d deletes the character to the right of the insertion cursor. -.IP [21] -Meta-d deletes the word to the right of the insertion cursor. -.IP [22] -Control-k deletes all the characters to the right of the insertion -cursor. -.IP [23] -Control-t reverses the order of the two characters to the right of -the insertion cursor. -.PP -If the entry is disabled using the \fB\-state\fR option, then the entry's -view can still be adjusted and text in the entry can still be selected, -but no insertion cursor will be displayed and no text modifications will -take place -.VS -except if the entry is linked to a variable using the \fB\-textvariable\fR -option, in which case any changes to the variable are reflected by the -entry whatever the value of its \fB\-state\fR option. -.VE -.PP -The behavior of entries can be changed by defining new bindings for -individual widgets or by redefining the class bindings. - -.SH KEYWORDS -entry, widget diff --git a/tcl/doc/event.n b/tcl/doc/event.n deleted file mode 100644 index 1df47c4ada..0000000000 --- a/tcl/doc/event.n +++ /dev/null @@ -1,366 +0,0 @@ -'\" -'\" Copyright (c) 1996 Sun Microsystems, Inc. -'\" Copyright (c) 1998-2000 Ajuba Solutions. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id$ -'\" -.so man.macros -.TH event n 8.3 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 - -.SH DESCRIPTION -.PP -The \fBevent\fR command provides several facilities for dealing with -window system events, such as defining virtual events and synthesizing -events. The command has several different forms, determined by the -first argument. The following forms are currently supported: -.TP -\fBevent add <<\fIvirtual\fB>>\fI sequence \fR?\fIsequence ...\fR? -Associates the virtual event \fIvirtual\fR with the physical -event sequence(s) given by the \fIsequence\fR arguments, so that -the virtual event will trigger whenever any one of the \fIsequence\fRs -occurs. -\fIVirtual\fR may be any string value and \fIsequence\fR may have -any of the values allowed for the \fIsequence\fR argument to the -\fBbind\fR command. -If \fIvirtual\fR is already defined, the new physical event sequences -add to the existing sequences for the event. -.TP -\fBevent delete <<\fIvirtual\fB>> \fR?\fIsequence\fR \fIsequence ...\fR? -Deletes each of the \fIsequence\fRs from those associated with -the virtual event given by \fIvirtual\fR. -\fIVirtual\fR may be any string value and \fIsequence\fR may have -any of the values allowed for the \fIsequence\fR argument to the -\fBbind\fR command. -Any \fIsequence\fRs not currently associated with \fIvirtual\fR -are ignored. -If no \fIsequence\fR argument is provided, all physical event sequences -are removed for \fIvirtual\fR, so that the virtual event will not -trigger anymore. -.TP -\fBevent generate \fIwindow event \fR?\fIoption value option value ...\fR? -Generates a window event and arranges for it to be processed just as if -it had come from the window system. -\fIWindow\fR gives the path name of the window for which the event -.VS 8.3 -will be generated; it may also be an identifier (such as returned by -\fBwinfo id\fR) as long as it is for a window in the current application. -.VE -\fIEvent\fR provides a basic description of -the event, such as \fB\fR or \fB<>\fR. -If \fIWindow\fR is empty the whole screen is meant, and coordinates -are relative to the screen. -\fIEvent\fR may have any of the forms allowed for the \fIsequence\fR -argument of the \fBbind\fR command except that it must consist -of a single event pattern, not a sequence. -\fIOption-value\fR pairs may be used to specify additional -attributes of the event, such as the x and y mouse position; see -EVENT FIELDS below. If the \fB\-when\fR option is not specified, the -event is processed immediately: all of the handlers for the event -will complete before the \fBevent generate\fR command returns. -If the \fB\-when\fR option is specified then it determines when the -event is processed. Certain events, such as key events, require -that the window has focus to receive the event properly. -.TP -\fBevent info \fR?<<\fIvirtual\fB>>\fR? -Returns information about virtual events. -If the \fB<<\fIvirtual\fB>>\fR argument is omitted, the return value -is a list of all the virtual events that are currently defined. -If \fB<<\fIvirtual\fB>>\fR is specified then the return value is -a list whose elements are the physical event sequences currently -defined for the given virtual event; if the virtual event is -not defined then an empty string is returned. - -.SH "EVENT FIELDS" -.PP -The following options are supported for the \fBevent generate\fR -command. These correspond to the ``%'' expansions -allowed in binding scripts for the \fBbind\fR command. -.TP -\fB\-above\fI window\fR -\fIWindow\fR specifies the \fIabove\fR field for the event, -either as a window path name or as an integer window id. -Valid for \fBConfigure\fR events. -Corresponds to the \fB%a\fR substitution for binding scripts. -.TP -\fB\-borderwidth\fI size\fR -\fISize\fR must be a screen distance; it specifies the -\fIborder_width\fR field for the event. -Valid for \fBConfigure\fR events. -Corresponds to the \fB%B\fR substitution for binding scripts. -.TP -\fB\-button\fI number\fR -\fINumber\fR must be an integer; it specifies the \fIdetail\fR field -for a \fBButtonPress\fR or \fBButtonRelease\fR event, overriding -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 -\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. -.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 -\fBNotifyAncestor NotifyNonlinearVirtual -NotifyDetailNone NotifyPointer -NotifyInferior NotifyPointerRoot -NotifyNonlinear NotifyVirtual\fR -.DE -Valid for \fBEnter\fR, \fBLeave\fR, \fBFocusIn\fR and -\fBFocusOut\fR events. -Corresponds to the \fB%d\fR substitution for binding scripts. -.RE -.TP -\fB\-focus\fI boolean\fR -\fIBoolean\fR must be a boolean value; it specifies the \fIfocus\fR -field for the event. -Valid for \fBEnter\fR and \fBLeave\fR events. -Corresponds to the \fB%f\fR substitution for binding scripts. -.TP -\fB\-height\fI size\fR -\fISize\fR must be a screen distance; it specifies the \fIheight\fR -field for the event. Valid for \fBConfigure\fR events. -Corresponds to the \fB%h\fR substitution for binding scripts. -.TP -\fB\-keycode\fI number\fR -\fINumber\fR must be an integer; it specifies the \fIkeycode\fR -field for the event. -Valid for \fBKeyPress\fR and \fBKeyRelease\fR events. -Corresponds to the \fB%k\fR substitution for binding scripts. -.TP -\fB\-keysym\fI name\fR -\fIName\fR must be the name of a valid keysym, such as \fBg\fR, -\fBspace\fR, or \fBReturn\fR; its corresponding -keycode value is used as the \fIkeycode\fR field for event, overriding -any detail specified in the base \fIevent\fR argument. -Valid for \fBKeyPress\fR and \fBKeyRelease\fR events. -Corresponds to the \fB%K\fR substitution for binding scripts. -.TP -\fB\-mode\fI notify\fR -\fINotify\fR specifies the \fImode\fR field for the event and must be -one of \fBNotifyNormal\fR, \fBNotifyGrab\fR, \fBNotifyUngrab\fR, or -\fBNotifyWhileGrabbed\fR. -Valid for \fBEnter\fR, \fBLeave\fR, \fBFocusIn\fR, and -\fBFocusOut\fR events. -Corresponds to the \fB%m\fR substitution for binding scripts. -.TP -\fB\-override\fI boolean\fR -\fIBoolean\fR must be a boolean value; it specifies the -\fIoverride_redirect\fR field for the event. -Valid for \fBMap\fR, \fBReparent\fR, and \fBConfigure\fR events. -Corresponds to the \fB%o\fR substitution for binding scripts. -.TP -\fB\-place\fI where\fR -\fIWhere\fR specifies the \fIplace\fR field for the event; it must be -either \fBPlaceOnTop\fR or \fBPlaceOnBottom\fR. -Valid for \fBCirculate\fR events. -Corresponds to the \fB%p\fR substitution for binding scripts. -.TP -\fB\-root\fI window\fR -\fIWindow\fR must be either a window path name or an integer window -identifier; it specifies the \fIroot\fR field for the event. -Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, -\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR -events. -Corresponds to the \fB%R\fR substitution for binding scripts. -.TP -\fB\-rootx\fI coord\fR -\fICoord\fR must be a screen distance; it specifies the \fIx_root\fR -field for the event. -Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, -\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR -events. Corresponds to the \fB%X\fR substitution for binding scripts. -.TP -\fB\-rooty\fI coord\fR -\fICoord\fR must be a screen distance; it specifies th \fIy_root\fR -field for the event. -Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, -\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR -events. -Corresponds to the \fB%Y\fR substitution for binding scripts. -.TP -\fB\-sendevent\fI boolean\fR -\fBBoolean\fR must be a boolean value; it specifies the \fIsend_event\fR -field for the event. Valid for all events. Corresponds to the -\fB%E\fR substitution for binding scripts. -.TP -\fB\-serial\fI number\fR -\fINumber\fR must be an integer; it specifies the \fIserial\fR field -for the event. Valid for all events. -Corresponds to the \fB%#\fR substitution for binding scripts. -.TP -\fB\-state\fI state\fR -\fIState\fR specifies the \fIstate\fR field for the event. -For \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, -\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR events -it must be an integer value. -For \fBVisibility\fR events it must be one of \fBVisibilityUnobscured\fR, -\fBVisibilityPartiallyObscured\fR, or \fBVisibilityFullyObscured\fR. -This option overrides any modifiers such as \fBMeta\fR or \fBControl\fR -specified in the base \fIevent\fR. -Corresponds to the \fB%s\fR substitution for binding scripts. -.TP -\fB\-subwindow\fI window\fR -\fIWindow\fR specifies the \fIsubwindow\fR field for the event, either -as a path name for a Tk widget or as an integer window identifier. -Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, -\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR events. -Similar to \fB%S\fR substitution for binding scripts. -.TP -\fB\-time\fI integer\fR -\fIInteger\fR must be an integer value; it specifies the \fItime\fR field -for the event. -Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, -\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, \fBMotion\fR, -and \fBProperty\fR events. -Corresponds to the \fB%t\fR substitution for binding scripts. -.TP -\fB\-warp\fI boolean\fR -\fIboolean\fR must be a boolean value; it specifies whether -the screen pointer should be warped as well. -Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, -\fBButtonRelease\fR, and \fBMotion\fR events. The pointer will -only warp to a window if it is mapped. -.TP -\fB\-width\fI size\fR -\fISize\fR must be a screen distance; it specifies the \fIwidth\fR field -for the event. -Valid for \fBConfigure\fR events. -Corresponds to the \fB%w\fR substitution for binding scripts. -.TP -\fB\-when\fI when\fR -\fIWhen\fR determines when the event will be processed; it must have one -of the following values: -.RS -.IP \fBnow\fR 10 -Process the event immediately, before the command returns. -This also happens if the \fB\-when\fR option is omitted. -.IP \fBtail\fR 10 -Place the event on Tcl's event queue behind any events already -queued for this application. -.IP \fBhead\fR 10 -Place the event at the front of Tcl's event queue, so that it -will be handled before any other events already queued. -.IP \fBmark\fR 10 -Place the event at the front of Tcl's event queue but behind any -other events already queued with \fB\-when mark\fR. -This option is useful when generating a series of events that should -be processed in order but at the front of the queue. -.RE -.TP -\fB\-x\fI coord\fR -\fICoord\fR must be a screen distance; it specifies the \fIx\fR field -for the event. -Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, -\fBButtonRelease\fR, \fBMotion\fR, \fBEnter\fR, \fBLeave\fR, -\fBExpose\fR, \fBConfigure\fR, \fBGravity\fR, and \fBReparent\fR -events. -Corresponds to the the \fB%x\fR substitution for binding scripts. -If \fIWindow\fR is empty the coordinate is relative to the -screen, and this option corresponds to the \fB%X\fR substitution -for binding scripts. -.TP -\fB\-y\fI coord\fR -\fICoord\fR must be a screen distance; it specifies the \fIy\fR -field for the event. -Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, -\fBButtonRelease\fR, \fBMotion\fR, \fBEnter\fR, \fBLeave\fR, -\fBExpose\fR, \fBConfigure\fR, \fBGravity\fR, and \fBReparent\fR -events. -Corresponds to the the \fB%y\fR substitution for binding scripts. -If \fIWindow\fR is empty the coordinate is relative to the -screen, and this option corresponds to the \fB%Y\fR substitution -for binding scripts. -.PP -Any options that are not specified when generating an event are filled -with the value 0, except for \fIserial\fR, which is filled with the -next X event serial number. - -.SH "VIRTUAL EVENT EXAMPLES" -.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: -.CS -event add <> -event add <> -event add <> -event add <> -.CE -In the \fBbind\fR command, a virtual event can be bound like any other -builtin event type as follows: -.CS -bind Entry <> {%W insert [selection get]} -.CE -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, -then the \fB<>\fR binding will be invoked. -.PP -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: -.CS -event add <> -bind Entry {puts Control-y} -bind Entry <> {puts Paste} -.CE -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. -However, when the user types Meta-Control-y the -\fB<>\fR binding will be invoked, because the -\fBMeta\fR modifier in the physical pattern associated with the -virtual binding is more specific than the \fB sequence for -the physical event. -.PP -Bindings on a virtual event may be created before the virtual event exists. -Indeed, the virtual event never actually needs to be defined, for instance, -on platforms where the specific virtual event would meaningless or -ungeneratable. -.PP -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: -.CS -bind {} -event add <> -.CE -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. - -.SH "SEE ALSO" -bind - -.SH KEYWORDS -event, binding, define, handle, virtual event diff --git a/tcl/doc/focus.n b/tcl/doc/focus.n deleted file mode 100644 index 496563c943..0000000000 --- a/tcl/doc/focus.n +++ /dev/null @@ -1,113 +0,0 @@ -'\" -'\" 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$ -'\" -.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 -.SH SYNOPSIS -\fBfocus\fR -.sp -\fBfocus \fIwindow\fR -.sp -\fBfocus \fIoption\fR ?\fIarg arg ...\fR? -.BE - -.SH DESCRIPTION -.PP -The \fBfocus\fR command is used to manage the Tk input focus. -At any given time, one window on each display is designated as -the \fIfocus window\fR; any key press or key release events for the -display are sent to that window. -It is normally up to the window manager to redirect the focus among the -top-level windows of a display. For example, some window managers -automatically set the input focus to a top-level window whenever -the mouse enters it; others redirect the input focus only when -the user clicks on a window. -Usually the window manager will set the focus -only to top-level windows, leaving it up to the application to -redirect the focus among the children of the top-level. -.PP -Tk remembers one focus window for each top-level (the most recent -descendant of that top-level to receive the focus); when the window -manager gives the focus -to a top-level, Tk automatically redirects it to the remembered -window. Within a top-level Tk uses an \fIexplicit\fR focus model -by default. Moving the mouse within a top-level does not normally -change the focus; the focus changes only when a widget -decides explicitly to claim the focus (e.g., because of a button -click), or when the user types a key such as Tab that moves the -focus. -.PP -The Tcl procedure \fBtk_focusFollowsMouse\fR may be invoked to -create an \fIimplicit\fR focus model: it reconfigures Tk so that -the focus is set to a window whenever the mouse enters it. -The Tcl procedures \fBtk_focusNext\fR and \fBtk_focusPrev\fR -implement a focus order among the windows of a top-level; they -are used in the default bindings for Tab and Shift-Tab, among other -things. -.PP -The \fBfocus\fR command can take any of the following forms: -.TP -\fBfocus\fR -Returns the path name of the focus window on the display containing -the application's main window, or an empty string if no window in -this application has the focus on that display. Note: it is -better to specify the display explicitly using \fB\-displayof\fR -(see below) so that the code will work in applications using multiple -displays. -.TP -\fBfocus \fIwindow\fR -If the application currently has the input focus on \fIwindow\fR's -display, this command resets the input focus for \fIwindow\fR's display -to \fIwindow\fR and returns an empty string. -If the application doesn't currently have the input focus on -\fIwindow\fR's display, \fIwindow\fR will be remembered as the focus -for its top-level; the next time the focus arrives at the top-level, -Tk will redirect it to \fIwindow\fR. -If \fIwindow\fR is an empty string then the command does nothing. -.TP -\fBfocus \-displayof\fR \fIwindow\fR -Returns the name of the focus window on the display containing \fIwindow\fR. -If the focus window for \fIwindow\fR's display isn't in this -application, the return value is an empty string. -.TP -\fBfocus \-force \fIwindow\fR -Sets the focus of \fIwindow\fR's display to \fIwindow\fR, even if -the application doesn't currently have the input focus for the display. -This command should be used sparingly, if at all. -In normal usage, an application should not claim the focus for -itself; instead, it should wait for the window manager to give it -the focus. -If \fIwindow\fR is an empty string then the command does nothing. -.TP -\fBfocus \-lastfor\fR \fIwindow\fR -Returns the name of the most recent window to have the input focus -among all the windows in the same top-level as \fIwindow\fR. -If no window in that top-level has ever had the input focus, or -if the most recent focus window has been deleted, then the name -of the top-level is returned. The return value is the window that -will receive the input focus the next time the window manager gives -the focus to the top-level. - -.SH "QUIRKS" -.PP -When an internal window receives the input focus, Tk doesn't actually -set the X focus to that window; as far as X is concerned, the focus -will stay on the top-level window containing the window with the focus. -However, Tk generates FocusIn and FocusOut events just as if the X -focus were on the internal window. This approach gets around a -number of problems that would occur if the X focus were actually moved; -the fact that the X focus is on the top-level is invisible unless -you use C code to query the X server directly. - -.SH KEYWORDS -events, focus, keyboard, top-level, window manager diff --git a/tcl/doc/focusNext.n b/tcl/doc/focusNext.n deleted file mode 100644 index a98e0fc56a..0000000000 --- a/tcl/doc/focusNext.n +++ /dev/null @@ -1,60 +0,0 @@ -'\" -'\" 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$ -'\" -.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. -.SH SYNOPSIS -\fBtk_focusNext \fIwindow\fR -.sp -\fBtk_focusPrev \fIwindow\fR -.sp -\fBtk_focusFollowsMouse\fR -.BE - -.SH DESCRIPTION -.PP -\fBtk_focusNext\fR is a utility procedure used for keyboard traversal. -It returns the ``next'' window after \fIwindow\fR in focus order. -The focus order is determined by -the stacking order of windows and the structure of the window hierarchy. -Among siblings, the focus order is the same as the stacking order, with the -lowest window being first. -If a window has children, the window is visited first, followed by -its children (recursively), followed by its next sibling. -Top-level windows other than \fIwindow\fR are skipped, so that -\fBtk_focusNext\fR never returns a window in a different top-level -from \fIwindow\fR. -.PP -After computing the next window, \fBtk_focusNext\fR examines the -window's \fB\-takefocus\fR option to see whether it should be skipped. -If so, \fBtk_focusNext\fR continues on to the next window in the focus -order, until it eventually finds a window that will accept the focus -or returns back to \fIwindow\fR. -.PP -\fBtk_focusPrev\fR is similar to \fBtk_focusNext\fR except that it -returns the window just before \fIwindow\fR in the focus order. -.PP -\fBtk_focusFollowsMouse\fR changes the focus model for the application -to an implicit one where the window under the mouse gets the focus. -After this procedure is called, whenever the mouse enters a window -Tk will automatically give it the input focus. -The \fBfocus\fR command may be used to move the focus to a window -other than the one under the mouse, but as soon as the mouse moves -into a new window the focus will jump to that window. -Note: at present there is no built-in support for returning the -application to an explicit focus model; to do this you'll have -to write a script that deletes the bindings created by -\fBtk_focusFollowsMouse\fR. - -.SH KEYWORDS -focus, keyboard traversal, top-level diff --git a/tcl/doc/font.n b/tcl/doc/font.n deleted file mode 100644 index e644ebeb13..0000000000 --- a/tcl/doc/font.n +++ /dev/null @@ -1,287 +0,0 @@ -'\" -'\" 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$ -'\" -.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. -.SH SYNOPSIS -\fBfont\fI option \fR?\fIarg arg ...\fR? -.BE -.SH DESCRIPTION -.PP -The \fBfont\fR command provides several facilities for dealing with -fonts, such as defining named fonts and inspecting the actual attributes of -a font. The command has several different forms, determined by the -first argument. The following forms are currently supported: -.TP -\fBfont actual \fIfont\fR ?\fB\-displayof \fIwindow\fR? ?\fIoption\fR? -. -Returns information about the the actual attributes that are obtained when -\fIfont\fR is used on \fIwindow\fR's display; the actual attributes obtained -may differ from the attributes requested due to platform-dependant -limitations, such as the availability of font families and pointsizes. -\fIfont\fR is a font description; see FONT DESCRIPTIONS below. If the -\fIwindow\fR argument is omitted, it defaults to the main window. If -\fIoption\fR is specified, returns the value of that attribute; if it is -omitted, the return value is a list of all the attributes and their values. -See FONT OPTIONS below for a list of the possible attributes. -.TP -\fBfont configure \fIfontname\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -. -Query or modify the desired attributes for the named font called -\fIfontname\fR. If no \fIoption\fR is specified, returns a list describing -all the options and their values for \fIfontname\fR. If a single \fIoption\fR -is specified with no \fIvalue\fR, then returns the current value of that -attribute. If one or more \fIoption\fR\-\fIvalue\fR pairs are specified, -then the command modifies the given named font to have the given values; in -this case, all widgets using that font will redisplay themselves using the -new attributes for the font. See FONT OPTIONS below for a list of the -possible attributes. -.TP -\fBfont create\fR ?\fIfontname\fR? ?\fIoption value ...\fR? -. -Creates a new named font and returns its name. \fIfontname\fR specifies the -name for the font; if it is omitted, then Tk generates a new name of the -form \fBfont\fIx\fR, where \fIx\fR is an integer. There may be any number -of \fIoption\fR\-\fIvalue\fR pairs, which provide the desired attributes for -the new named font. See FONT OPTIONS below for a list of the possible -attributes. -.TP -\fBfont delete\fR \fIfontname\fR ?\fIfontname ...\fR? -. -Delete the specified named fonts. If there are widgets using the named font, -the named font won't actually be deleted until all the instances are -released. Those widgets will continue to display using the last known values -for the named font. If a deleted named font is subsequently recreated with -another call to \fBfont create\fR, the widgets will use the new named font -and redisplay themselves using the new attributes of that font. -.TP -\fBfont families\fR ?\fB\-displayof \fIwindow\fR? -. -The return value is a list of the case-insensitive names of all font families -that exist on \fIwindow\fR's display. If the \fIwindow\fR argument is -omitted, it defaults to the main window. -.TP -\fBfont measure \fIfont\fR ?\fB\-displayof \fIwindow\fR? \fItext\fR -. -Measures the amount of space the string \fItext\fR would use in the given -\fIfont\fR when displayed in \fIwindow\fR. \fIfont\fR is a font description; -see FONT DESCRIPTIONS below. If the \fIwindow\fR argument is omitted, it -defaults to the main window. The return value is the total width in pixels -of \fItext\fR, not including the extra pixels used by highly exagerrated -characters such as cursive ``f''. If the string contains newlines or tabs, -those characters are not expanded or treated specially when measuring the -string. -.TP -\fBfont metrics \fIfont\fR ?\fB\-displayof \fIwindow\fR? ?\fIoption\fR? -. -Returns information about the metrics (the font-specific data), for -\fIfont\fR when it is used on \fIwindow\fR's display. \fIfont\fR is a font -description; see FONT DESCRIPTIONS below. If the \fIwindow\fR argument is -omitted, it defaults to the main window. If \fIoption\fR is specified, -returns the value of that metric; if it is omitted, the return value is a -list of all the metrics and their values. See FONT METRICS below for a list -of the possible metrics. -.TP -\fBfont names\fR -The return value is a list of all the named fonts that are currently defined. -.SH "FONT DESCRIPTION" -.PP -The following formats are accepted as a font description anywhere -\fIfont\fR is specified as an argument above; these same forms are also -permitted when specifying the \fB\-font\fR option for widgets. -.TP -[1] \fIfontname\fR -. -The name of a named font, created using the \fBfont create\fR command. When -a widget uses a named font, it is guaranteed that this will never cause an -error, as long as the named font exists, no matter what potentially invalid -or meaningless set of attributes the named font has. If the named font -cannot be displayed with exactly the specified attributes, some other close -font will be substituted automatically. -.TP -[2] \fIsystemfont\fR -. -The platform-specific name of a font, interpreted by the graphics server. -This also includes, under X, an XLFD (see [4]) for which a single ``\fB*\fR'' -character was used to elide more than one field in the middle of the -name. See PLATFORM-SPECIFIC issues for a list of the system fonts. -.VS 8.0 br -.TP -[3] \fIfamily \fR?\fIsize\fR? ?\fIstyle\fR? ?\fIstyle ...\fR? -. -A properly formed list whose first element is the desired font -\fIfamily\fR and whose optional second element is the desired \fIsize\fR. -The interpretation of the \fIsize\fR attribute follows the same rules -described for \fB\-size\fR in FONT OPTIONS below. Any additional optional -arguments following the \fIsize\fR are font \fIstyle\fRs. Possible values -for the \fIstyle\fR arguments are as follows: -.RS -.DS -.ta 3c 6c 9c -\fBnormal bold roman italic -underline overstrike\fR -.DE -.RE -.TP -[4] X-font names (XLFD) -. -A Unix-centric font name of the form -\fI-foundry-family-weight-slant-setwidth-addstyle-pixel-point-resx-resy-spacing-width-charset-encoding\fR. -The ``\fB*\fR'' character may be used to skip individual fields that the -user does not care about. There must be exactly one ``\fB*\fR'' for each -field skipped, except that a ``\fB*\fR'' at the end of the XLFD skips any -remaining fields; the shortest valid XLFD is simply ``\fB*\fR'', signifying -all fields as defaults. Any fields that were skipped are given default -values. For compatibility, an XLFD always chooses a font of the specified -pixel size (not point size); although this interpretation is not strictly -correct, all existing applications using XLFDs assumed that one ``point'' -was in fact one pixel and would display incorrectly (generally larger) if -the correct size font were actually used. -.VE -.TP -[5] \fIoption value \fR?\fIoption value ...\fR? -. -A properly formed list of \fIoption\fR\-\fIvalue\fR pairs that specify -the desired attributes of the font, in the same format used when defining -a named font; see FONT OPTIONS below. -.LP -When font description \fIfont\fR is used, the system attempts to parse the -description according to each of the above five rules, in the order specified. -Cases [1] and [2] must match the name of an existing named font or of a -system font. Cases [3], [4], and [5] are accepted on all -platforms and the closest available font will be used. In some situations -it may not be possible to find any close font (e.g., the font family was -a garbage value); in that case, some system-dependant default font is -chosen. If the font description does not match any of the above patterns, -an error is generated. -.SH "FONT METRICS" -. -The following options are used by the \fBfont metrics\fR command to query -font-specific data determined when the font was created. These properties are -for the whole font itself and not for individual characters drawn in that -font. In the following definitions, the ``baseline'' of a font is the -horizontal line where the bottom of most letters line up; certain letters, -such as lower-case ``g'' stick below the baseline. -.TP -\fB\-ascent \0\fR -. -The amount in pixels that the tallest letter sticks up above the baseline of -the font, plus any extra blank space added by the designer of the font. -.TP -\fB\-descent \0\fR -. -The largest amount in pixels that any letter sticks down below the baseline -of the font, plus any extra blank space added by the designer of the font. -.TP -\fB\-linespace\fR -. -Returns how far apart vertically in pixels two lines of text using the same -font should be placed so that none of the characters in one line overlap any -of the characters in the other line. This is generally the sum of the ascent -above the baseline line plus the descent below the baseline. -.TP -\fB\-fixed \0\fR -. -Returns a boolean flag that is ``\fB1\fR'' if this is a fixed-width font, -where each normal character is the the same width as all the other -characters, or is ``\fB0\fR'' if this is a proportionally-spaced font, where -individual characters have different widths. The widths of control -characters, tab characters, and other non-printing characters are not -included when calculating this value. -.SH "FONT OPTIONS" -The following options are supported on all platforms, and are used when -constructing a named font or when specifying a font using style [5] as -above: -.TP -\fB\-family \fIname\fR -. -The case-insensitive font family name. Tk guarantees to support the font -families named \fBCourier\fR (a monospaced ``typewriter'' font), \fBTimes\fR -(a serifed ``newspaper'' font), and \fBHelvetica\fR (a sans-serif -``European'' font). The most closely matching native font family will -automatically be substituted when one of the above font families is used. -The \fIname\fR may also be the name of a native, platform-specific font -family; in that case it will work as desired on one platform but may not -display correctly on other platforms. If the family is unspecified or -unrecognized, a platform-specific default font will be chosen. -.VS -.TP -\fB\-size \fIsize\fR -. -The desired size of the font. If the \fIsize\fR argument is a positive -number, it is interpreted as a size in points. If \fIsize\fR is a negative -number, its absolute value is interpreted as a size in pixels. If a -font cannot be displayed at the specified size, a nearby size will be -chosen. If \fIsize\fR is unspecified or zero, a platform-dependent default -size will be chosen. -.RS -.PP -Sizes should normally be specified in points so the application will remain -the same ruler size on the screen, even when changing screen resolutions or -moving scripts across platforms. However, specifying pixels is useful in -certain circumstances such as when a piece of text must line up with respect -to a fixed-size bitmap. The mapping between points and pixels is set when -the application starts, based on properties of the installed monitor, but it -can be overridden by calling the \fBtk scaling\fR command. -.RE -.VE -.TP -\fB\-weight \fIweight\fR -. -The nominal thickness of the characters in the font. The value -\fBnormal\fR specifies a normal weight font, while \fBbold\fR specifies a -bold font. The closest available weight to the one specified will -be chosen. The default weight is \fBnormal\fR. -.TP -\fB\-slant \fIslant\fR -The amount the characters in the font are slanted away from the -vertical. Valid values for slant are \fBroman\fR and \fBitalic\fR. -A roman font is the normal, upright appearance of a font, while -an italic font is one that is tilted some number of degrees from upright. -The closest available slant to the one specified will be chosen. -The default slant is \fBroman\fR. -.TP -\fB\-underline \fIboolean\fR -The value is a boolean flag that specifies whether characters in this -font should be underlined. The default value for underline is \fBfalse\fR. -.TP -\fB\-overstrike \fIboolean\fR -The value is a boolean flag that specifies whether a horizontal line should -be drawn through the middle of characters in this font. The default value -for overstrike is \fBfalse\fR. - -.SH "PLATFORM-SPECIFIC ISSUES" -.LP -The following named system fonts are supported: -.RS -.TP -X Windows: -All valid X font names, including those listed by xlsfonts(1), are available. -.TP -MS Windows: -.DS -.ta 3c 6c -\fBsystem ansi device -systemfixed ansifixed oemfixed\fR -.DE -.TP -Macintosh: -.DS -.ta 3c 6c -\fBsystem application\fR -.DE -.RE -.SH "SEE ALSO" -options - -.SH KEYWORDS -font diff --git a/tcl/doc/frame.n b/tcl/doc/frame.n deleted file mode 100644 index b2e88d472f..0000000000 --- a/tcl/doc/frame.n +++ /dev/null @@ -1,136 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH frame n 8.4 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -frame \- Create and manipulate frame widgets -.SH SYNOPSIS -\fBframe\fR \fIpathName\fR ?\fIoptions\fR? -.SO -\-borderwidth \-highlightcolor \-pady -\-cursor \-highlightthickness \-relief -\-highlightbackground \-padx \-takefocus -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-background background Background -This option is the same as the standard \fBbackground\fR option -except that its value may also be specified as an empty string. -In this case, the widget will display no background or border, and -no colors will be consumed from its colormap for its background -and border. -.OP \-class class Class -Specifies a class for the window. -This class will be used when querying the option database for -the window's other options, and it will also be used later for -other purposes such as bindings. -The \fBclass\fR option may not be changed with the \fBconfigure\fR -widget command. -.OP \-colormap colormap Colormap -Specifies a colormap to use for the window. -The value may be either \fBnew\fR, in which case a new colormap is -created for the window and its children, or the name of another -window (which must be on the same screen and have the same visual -as \fIpathName\fR), in which case the new window will use the colormap -from the specified window. -If the \fBcolormap\fR option is not specified, the new window -uses the same colormap as its parent. -This option may not be changed with the \fBconfigure\fR -widget command. -.OP \-container container Container -The value must be a boolean. If true, it means that this window will -be used as a container in which some other application will be embedded -(for example, a Tk toplevel can be embedded using the \fB\-use\fR option). -The window will support the appropriate window manager protocols for -things like geometry requests. The window should not have any -children of its own in this application. -This option may not be changed with the \fBconfigure\fR -widget command. -.OP \-height height Height -Specifies the desired height for the window in any of the forms -acceptable to \fBTk_GetPixels\fR. -If this option is less than or equal to zero then the window will -not request any size at all. -.OP \-visual visual Visual -Specifies visual information for the new window in any of the -forms accepted by \fBTk_GetVisual\fR. -If this option is not specified, the new window will use the same -visual as its parent. -The \fBvisual\fR option may not be modified with the \fBconfigure\fR -widget command. -.OP \-width width Width -Specifies the desired width for the window in any of the forms -acceptable to \fBTk_GetPixels\fR. -If this option is less than or equal to zero then the window will -not request any size at all. -.BE - -.SH DESCRIPTION -.PP -The \fBframe\fR command creates a new window (given by the -\fIpathName\fR argument) and makes it into a frame widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the frame such as its background color -and relief. The \fBframe\fR command returns the -path name of the new window. -.PP -A frame is a simple widget. Its primary purpose is to act as a -spacer or container for complex window layouts. The only features -of a frame are its background color and an optional 3-D border to make the -frame appear raised or sunken. - -.SH "WIDGET COMMAND" -.PP -The \fBframe\fR command creates a new Tcl command whose -name is the same as the path name of the frame's window. This -command may be used to invoke various -operations on the widget. It has the following general form: -.CS -\fIpathName option \fR?\fIarg arg ...\fR? -.CE -\fIPathName\fR is the name of the command, which is the same as -the frame widget's path name. \fIOption\fR and the \fIarg\fRs -determine the exact behavior of the command. The following -commands are possible for frame widgets: -.TP -\fIpathName \fBcget\fR \fIoption\fR -Returns the current value of the configuration option given -by \fIoption\fR. -\fIOption\fR may have any of the values accepted by the \fBframe\fR -command. -.TP -\fIpathName \fBconfigure\fR ?\fIoption\fR? \fI?value option value ...\fR? -Query or modify the configuration options of the widget. -If no \fIoption\fR is specified, returns a list describing all of -the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for -information on the format of this list). If \fIoption\fR is specified -with no \fIvalue\fR, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no \fIoption\fR is specified). If -one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given widget option(s) to have the given value(s); in -this case the command returns an empty string. -\fIOption\fR may have any of the values accepted by the \fBframe\fR -command. - -.SH BINDINGS -.PP -When a new frame is created, it has no default event bindings: -frames are not intended to be interactive. - -.SH "SEE ALSO" -labelframe(n), toplevel(n) - -.SH KEYWORDS -frame, widget diff --git a/tcl/doc/getOpenFile.n b/tcl/doc/getOpenFile.n deleted file mode 100644 index 3c12dc1a7c..0000000000 --- a/tcl/doc/getOpenFile.n +++ /dev/null @@ -1,171 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH tk_getOpenFile n 4.2 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -tk_getOpenFile, tk_getSaveFile \- pop up a dialog box for the user to select a file to open or save. -.SH SYNOPSIS -\fBtk_getOpenFile \fR?\fIoption value ...\fR? -.br -\fBtk_getSaveFile \fR?\fIoption value ...\fR? -.BE - -.SH DESCRIPTION -.PP -The procedures \fBtk_getOpenFile\fR and \fBtk_getSaveFile\fR pop up a -dialog box for the user to select a file to open or save. The -\fBtk_getOpenFile\fR command is usually associated with the \fBOpen\fR -command in the \fBFile\fR menu. Its purpose is for the user to select an -existing file \fIonly\fR. If the user enters an non-existent file, the -dialog box gives the user an error prompt and requires the user to give -an alternative selection. If an application allows the user to create -new files, it should do so by providing a separate \fBNew\fR menu command. -.PP -The \fBtk_getSaveFile\fR command is usually associated with the \fBSave -as\fR command in the \fBFile\fR menu. If the user enters a file that -already exists, the dialog box prompts the user for confirmation -whether the existing file should be overwritten or not. -.PP -The following \fIoption\-value\fR pairs are possible as command line -arguments to these two commands: -.TP -\fB\-defaultextension\fR \fIextension\fR -Specifies a string that will be appended to the filename if the user -enters a filename without an extension. The defaut value is the empty -string, which means no extension will be appended to the filename in -any case. This option is ignored on the Macintosh platform, which -does not require extensions to filenames, -.VS 8.4 -and the UNIX implementation guesses reasonable values for this from -the \fB\-filetypes\fR option when this is not supplied. -.VE 8.4 -.TP -\fB\-filetypes\fR \fIfilePatternList\fR -If a \fBFile types\fR listbox exists in the file dialog on the particular -platform, this option gives the \fIfiletype\fRs in this listbox. When -the user choose a filetype in the listbox, only the files of that type -are listed. If this option is unspecified, or if it is set to the -empty list, or if the \fBFile types\fR listbox is not supported by the -particular platform then all files are listed regardless of their -types. See the section SPECIFYING FILE PATTERNS below for a -discussion on the contents of \fIfilePatternList\fR. -.TP -\fB\-initialdir\fR \fIdirectory\fR -Specifies that the files in \fIdirectory\fR should be displayed -when the dialog pops up. If this parameter is not specified, then -the files in the current working directory are displayed. If the -parameter specifies a relative path, the return value will convert the -relative path to an absolute path. This option may not always work on -the Macintosh. This is not a bug. Rather, the \fIGeneral Controls\fR -control panel on the Mac allows the end user to override the -application default directory. -.TP -\fB\-initialfile\fR \fIfilename\fR -Specifies a filename to be displayed in the dialog when it pops up. This -option is ignored on the Macintosh platform. -.TP -\fB\-multiple\fR -Allows the user to choose multiple files from the Open dialog. -On the Macintosh, this is only available when Navigation Services are -installed. -.TP -\fB\-message\fR \fIstring\fR -Specifies a message to include in the client area of the dialog. -This is only available on the Macintosh, and only when Navigation -Services are installed. -.TP -\fB\-parent\fR \fIwindow\fR -Makes \fIwindow\fR the logical parent of the file dialog. The file -dialog is displayed on top of its parent window. -.TP -\fB\-title\fR \fItitleString\fR -Specifies a string to display as the title of the dialog box. If this -option is not specified, then a default title is displayed. -.PP -If the user selects a file, both \fBtk_getOpenFile\fR and -\fBtk_getSaveFile\fR return the full pathname of this file. If the -user cancels the operation, both commands return the empty string. -.SH "SPECIFYING FILE PATTERNS" - -The \fIfilePatternList\fR value given by the \fB\-filetypes\fR option -is a list of file patterns. Each file pattern is a list of the -form -.CS -\fItypeName\fR {\fIextension\fR ?\fIextension ...\fR?} ?{\fImacType\fR ?\fImacType ...\fR?}? -.CE -\fItypeName\fR is the name of the file type described by this -file pattern and is the text string that appears in the \fBFile types\fR -listbox. \fIextension\fR is a file extension for this file pattern. -\fImacType\fR is a four-character Macintosh file type. The list of -\fImacType\fRs is optional and may be omitted for applications that do -not need to execute on the Macintosh platform. -.PP -Several file patterns may have the same \fItypeName,\fR in which case -they refer to the same file type and share the same entry in the -listbox. When the user selects an entry in the listbox, all the files -that match at least one of the file patterns corresponding -to that entry are listed. Usually, each file pattern corresponds to a -distinct type of file. The use of more than one file patterns for one -type of file is necessary on the Macintosh platform only. -.PP -On the Macintosh platform, a file matches a file pattern if its -name matches at least one of the \fIextension\fR(s) AND it -belongs to at least one of the \fImacType\fR(s) of the -file pattern. For example, the \fBC Source Files\fR file pattern in the -sample code matches with files that have a \fB\.c\fR extension AND -belong to the \fImacType\fR \fBTEXT\fR. To use the OR rule instead, -you can use two file patterns, one with the \fIextensions\fR only and -the other with the \fImacType\fR only. The \fBGIF Files\fR file type -in the sample code matches files that EITHER have a \fB\.gif\fR -extension OR belong to the \fImacType\fR \fBGIFF\fR. -.PP -On the Unix and Windows platforms, a file matches a file pattern -if its name matches at at least one of the \fIextension\fR(s) of -the file pattern. The \fImacType\fRs are ignored. -.SH "SPECIFYING EXTENSIONS" -.PP -On the Unix and Macintosh platforms, extensions are matched using -glob-style pattern matching. On the Windows platforms, extensions are -matched by the underlying operating system. The types of possible -extensions are: (1) the special extension * matches any -file; (2) the special extension "" matches any files that -do not have an extension (i.e., the filename contains no full stop -character); (3) any character string that does not contain any wild -card characters (* and ?). -.PP -Due to the different pattern matching rules on the various platforms, -to ensure portability, wild card characters are not allowed in the -extensions, except as in the special extension *. Extensions -without a full stop character (e.g, ~) are allowed but may not -work on all platforms. - -.SH EXAMPLE -.CS -set types { - {{Text Files} {.txt} } - {{TCL Scripts} {.tcl} } - {{C Source Files} {.c} TEXT} - {{GIF Files} {.gif} } - {{GIF Files} {} GIFF} - {{All Files} * } -} -set filename [tk_getOpenFile -filetypes $types] - -if {$filename != ""} { - # Open the file ... -} -.CE - -.SH "SEE ALSO" -tk_chooseDirectory - -.SH KEYWORDS -file selection dialog diff --git a/tcl/doc/grab.n b/tcl/doc/grab.n deleted file mode 100644 index 2d261d9c72..0000000000 --- a/tcl/doc/grab.n +++ /dev/null @@ -1,122 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH grab n "" Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -grab \- Confine pointer and keyboard events to a window sub-tree -.SH SYNOPSIS -\fBgrab \fR?\fB\-global\fR? \fIwindow\fR -.sp -\fBgrab \fIoption \fR?\fIarg arg \fR...? -.BE - -.SH DESCRIPTION -.PP -This command implements simple pointer and keyboard grabs for Tk. -Tk's grabs are different than the grabs -described in the Xlib documentation. -When a grab is set for a particular window, Tk restricts all pointer -events to the grab window and its descendants in Tk's window hierarchy. -Whenever the pointer is within the grab window's subtree, the pointer -will behave exactly the same as if there had been no grab at all -and all events will be reported in the normal fashion. -When the pointer is outside \fIwindow\fR's tree, button presses and -releases and -mouse motion events are reported to \fIwindow\fR, and window entry -and window exit events are ignored. -The grab subtree ``owns'' the pointer: -windows outside the grab subtree will be visible on the screen -but they will be insensitive until the grab is released. -The tree of windows underneath the grab window can include top-level -windows, in which case all of those top-level windows -and their descendants will continue to receive mouse events -during the grab. -.PP -Two forms of grabs are possible: local and global. -A local grab affects only the grabbing application: events will -be reported to other applications as if the grab had never occurred. -Grabs are local by default. -A global grab locks out all applications on the screen, -so that only the given subtree of the grabbing application will be -sensitive to pointer events (mouse button presses, mouse button releases, -pointer motions, window entries, and window exits). -During global grabs the window manager will not receive pointer -events either. -.PP -During local grabs, keyboard events (key presses and key releases) -are delivered as usual: the window -manager controls which application receives keyboard events, and -if they are sent to any window in the grabbing application then they are -redirected to the focus window. -During a global grab Tk grabs the keyboard so that all keyboard events -are always sent to the grabbing application. -The \fBfocus\fR command is still used to determine which window in the -application receives the keyboard events. -The keyboard grab is released when the grab is released. -.PP -Grabs apply to particular displays. If an application has windows -on multiple displays then it can establish a separate grab on each -display. -The grab on a particular display affects only the windows on -that display. -It is possible for different applications on a single display to have -simultaneous local grabs, but only one application can have a global -grab on a given display at once. -.PP -The \fBgrab\fR command can take any of the following forms: -.TP -\fBgrab \fR?\fB\-global\fR? \fIwindow\fR -Same as \fBgrab set\fR, described below. -.TP -\fBgrab current \fR?\fIwindow\fR? -If \fIwindow\fR is specified, returns the name of the current grab -window in this application for \fIwindow\fR's display, or an empty -string if there is no such window. -If \fIwindow\fR is omitted, the command returns a list whose elements -are all of the windows grabbed by this application for all displays, -or an empty string if the application has no grabs. -.TP -\fBgrab release \fIwindow\fR -Releases the grab on \fIwindow\fR if there is one, otherwise does -nothing. Returns an empty string. -.TP -\fBgrab set \fR?\fB\-global\fR? \fIwindow\fR -Sets a grab on \fIwindow\fR. If \fB\-global\fR is specified then the -grab is global, otherwise it is local. -If a grab was already in effect for this application on -\fIwindow\fR's display then it is automatically released. -If there is already a grab on \fIwindow\fR and it has the same -global/local form as the requested grab, then the command -does nothing. Returns an empty string. -.TP -\fBgrab status \fIwindow\fR -Returns \fBnone\fR if no grab is currently set on \fIwindow\fR, -\fBlocal\fR if a local grab is set on \fIwindow\fR, and -\fBglobal\fR if a global grab is set. - -.SH BUGS -.PP -It took an incredibly complex and gross implementation to produce -the simple grab effect described above. -Given the current implementation, it isn't safe for applications -to use the Xlib grab facilities at all except through the Tk grab -procedures. -If applications try to manipulate X's grab mechanisms directly, -things will probably break. -.PP -If a single process is managing several different Tk applications, -only one of those applications can have a local grab for a given -display at any given time. If the applications are in different -processes, this restriction doesn't exist. - -.SH KEYWORDS -grab, keyboard events, pointer events, window diff --git a/tcl/doc/grid.n b/tcl/doc/grid.n deleted file mode 100644 index ee40d2169c..0000000000 --- a/tcl/doc/grid.n +++ /dev/null @@ -1,379 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH grid n 8.4 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -grid \- Geometry manager that arranges widgets in a grid -.SH SYNOPSIS -\fBgrid \fIoption arg \fR?\fIarg ...\fR? -.BE - -.SH DESCRIPTION -.PP -The \fBgrid\fR command is used to communicate with the grid -geometry manager that arranges widgets in rows and columns inside -of another window, called the geometry master (or master window). -The \fBgrid\fR command can have any of several forms, depending -on the \fIoption\fR argument: -.TP -\fBgrid \fIslave \fR?\fIslave ...\fR? ?\fIoptions\fR? -If the first argument to \fBgrid\fR is suitable as the first slave -argument to \fBgrid configure\fR, either a window name (any value -starting with \fB.\fP) or one of the characters \fBx\fP or \fB^\fP -(see the ``RELATIVE PLACEMENT'' section below), then the command is -processed in the same way as \fBgrid configure\fR. -.TP -\fBgrid bbox \fImaster\fR ?\fIcolumn row\fR? ?\fIcolumn2 row2\fR? -With no arguments, -the bounding box (in pixels) of the grid is returned. -The return value consists of 4 integers. The first two are the pixel -offset from the master window (x then y) of the top-left corner of the -grid, and the second two integers are the width and height of the grid, -also in pixels. If a single \fIcolumn\fP and \fIrow\fP is specified on -the command line, then the bounding box for that cell is returned, where the -top left cell is numbered from zero. If both \fIcolumn\fP and \fIrow\fP -arguments are specified, then the bounding box spanning the rows and columns -indicated is returned. -.TP -\fBgrid columnconfigure \fImaster index \fR?\fI\-option value...\fR? -Query or set the column properties of the \fIindex\fP column of the -geometry master, \fImaster\fP. -.VS 8.4 -The valid options are \fB\-minsize\fP, \fB\-weight\fP, \fB\-uniform\fP -and \fB-pad\fP. -.VE -If one or more options are provided, then \fIindex\fP may be given as -a list of column indeces to which the configuration options will operate on. -The \fB\-minsize\fP option sets the minimum size, in screen units, -that will be permitted for this column. -The \fB\-weight\fP option (an integer value) -sets the relative weight for apportioning -any extra spaces among -columns. -A weight of zero (0) indicates the column will not deviate from its requested -size. A column whose weight is two will grow at twice the rate as a column -of weight one when extra space is allocated to the layout. -.VS 8.4 -The \fB-uniform\fP option, when a non-empty value is supplied, places -the column in a \fIuniform group\fP with other columns that have the -same value for \fB-uniform\fP. The space for columns belonging to a -uniform group is allocated so that their sizes are always in strict -proportion to their \fB-weight\fP values. See -``THE GRID ALGORITHM'' below for further details. -.VE -The \fB-pad\fP option specifies the number of screen units that will be -added to the largest window contained completely in that column when the -grid geometry manager requests a size from the containing window. -If only an option is specified, with no value, -the current value of that option is returned. -If only the master window and index is specified, all the current settings -are returned in an list of "-option value" pairs. -.TP -\fBgrid configure \fIslave \fR?\fIslave ...\fR? ?\fIoptions\fR? -The arguments consist of the names of one or more slave windows -followed by pairs of arguments that specify how -to manage the slaves. -The characters \fB\-\fP, \fBx\fP and \fB^\fP, -can be specified instead of a window name to alter the default -location of a \fIslave\fP, as described in the ``RELATIVE PLACEMENT'' -section, below. -The following options are supported: -.RS -.TP -\fB\-column \fIn\fR -Insert the slave so that it occupies the \fIn\fPth column in the grid. -Column numbers start with 0. If this option is not supplied, then the -slave is arranged just to the right of previous slave specified on this -call to \fIgrid\fP, or column "0" if it is the first slave. For each -\fBx\fP that immediately precedes the \fIslave\fP, the column position -is incremented by one. Thus the \fBx\fP represents a blank column -for this row in the grid. -.TP -\fB\-columnspan \fIn\fR -Insert the slave so that it occupies \fIn\fP columns in the grid. -The default is one column, unless the window name is followed by a -\fB\-\fP, in which case the columnspan is incremented once for each immediately -following \fB\-\fP. -.TP -\fB\-in \fIother\fR -Insert the slave(s) in the master -window given by \fIother\fR. The default is the first slave's -parent window. -.TP -\fB\-ipadx \fIamount\fR -The \fIamount\fR specifies how much horizontal internal padding to -leave on each side of the slave(s). This is space is added -inside the slave(s) border. -The \fIamount\fR must be a valid screen distance, such as \fB2\fR or \fB.5c\fR. -It defaults to 0. -.TP -\fB\-ipady \fIamount\fR -The \fIamount\fR specifies how much vertical internal padding to -leave on on the top and bottom of the slave(s). -This space is added inside the slave(s) border. -The \fIamount\fR defaults to 0. -.TP -\fB\-padx \fIamount\fR -The \fIamount\fR specifies how much horizontal external padding to -leave on each side of the slave(s), in screen units. -\fIAmount\fR may be a list -of two values to specify padding for left and right separately. -The \fIamount\fR defaults to 0. -This space is added outside the slave(s) border. -.TP -\fB\-pady \fIamount\fR -The \fIamount\fR specifies how much vertical external padding to -leave on the top and bottom of the slave(s), in screen units. -\fIAmount\fR may be a list -of two values to specify padding for top and bottom separately. -The \fIamount\fR defaults to 0. -This space is added outside the slave(s) border. -.TP -\fB\-row \fIn\fR -Insert the slave so that it occupies the \fIn\fPth row in the grid. -Row numbers start with 0. If this option is not supplied, then the -slave is arranged on the same row as the previous slave specified on this -call to \fBgrid\fP, or the first unoccupied row if this is the first slave. -.TP -\fB\-rowspan \fIn\fR -Insert the slave so that it occupies \fIn\fP rows in the grid. -The default is one row. If the next \fBgrid\fP command contains -\fB^\fP characters instead of \fIslaves\fP that line up with the columns -of this \fIslave\fP, then the \fBrowspan\fP of this \fIslave\fP is -extended by one. -.TP -\fB\-sticky \fIstyle\fR -If a slave's cell is larger than its requested dimensions, this -option may be used to position (or stretch) the slave within its cell. -\fIStyle\fR is a string that contains zero or more of the characters -\fBn\fP, \fBs\fP, \fBe\fP or \fBw\fP. -The string can optionally contains spaces or -commas, but they are ignored. Each letter refers to a side (north, south, -east, or west) that the slave will "stick" to. If both \fBn\fP and \fBs\fP (or -\fBe\fP and \fBw\fP) are specified, the slave will be stretched to fill the entire -height (or width) of its cavity. The \fBsticky\fP option subsumes the -combination of \fB\-anchor\fP and \fB\-fill\fP that is used by \fBpack\fP. -The default is \fB{}\fP, which causes the slave to be centered in its cavity, -at its requested size. -.LP -If any of the slaves are already managed by the geometry manager -then any unspecified options for them retain their previous values rather -than receiving default values. -.RE -.TP -\fBgrid forget \fIslave \fR?\fIslave ...\fR? -Removes each of the \fIslave\fRs from grid for its -master and unmaps their windows. -The slaves will no longer be managed by the grid geometry manager. -The configuration options for that window are forgotten, so that if the -slave is managed once more by the grid geometry manager, the initial -default settings are used. -.TP -\fBgrid info \fIslave\fR -Returns a list whose elements are the current configuration state of -the slave given by \fIslave\fR in the same option-value form that -might be specified to \fBgrid configure\fR. -The first two elements of the list are ``\fB\-in \fImaster\fR'' where -\fImaster\fR is the slave's master. -.TP -\fBgrid location \fImaster x y\fR -Given \fIx\fP and \fIy\fP values in screen units relative to the master window, -the column and row number at that \fIx\fP and \fIy\fP location is returned. -For locations that are above or to the left of the grid, \fB-1\fP is returned. -.TP -\fBgrid propagate \fImaster\fR ?\fIboolean\fR? -If \fIboolean\fR has a true boolean value such as \fB1\fR or \fBon\fR -then propagation is enabled for \fImaster\fR, which must be a window -name (see ``GEOMETRY PROPAGATION'' below). -If \fIboolean\fR has a false boolean value then propagation is -disabled for \fImaster\fR. -In either of these cases an empty string is returned. -If \fIboolean\fR is omitted then the command returns \fB0\fR or -\fB1\fR to indicate whether propagation is currently enabled -for \fImaster\fR. -Propagation is enabled by default. -.TP -\fBgrid rowconfigure \fImaster index \fR?\fI\-option value...\fR? -Query or set the row properties of the \fIindex\fP row of the -geometry master, \fImaster\fP. -.VS 8.4 -The valid options are \fB\-minsize\fP, \fB\-weight\fP, \fB\-uniform\fP -and \fB-pad\fP. -.VE -If one or more options are provided, then \fIindex\fP may be given as -a list of row indeces to which the configuration options will operate on. -The \fB\-minsize\fP option sets the minimum size, in screen units, -that will be permitted for this row. -The \fB\-weight\fP option (an integer value) -sets the relative weight for apportioning -any extra spaces among -rows. -A weight of zero (0) indicates the row will not deviate from its requested -size. A row whose weight is two will grow at twice the rate as a row -of weight one when extra space is allocated to the layout. -.VS 8.4 -The \fB-uniform\fP option, when a non-empty value is supplied, places -the row in a \fIuniform group\fP with other rows that have the -same value for \fB-uniform\fP. The space for rows belonging to a -uniform group is allocated so that their sizes are always in strict -proportion to their \fB-weight\fP values. See -``THE GRID ALGORITHM'' below for further details. -.VE -The \fB-pad\fP option specifies the number of screen units that will be -added to the largest window contained completely in that row when the -grid geometry manager requests a size from the containing window. -If only an option is specified, with no value, -the current value of that option is returned. -If only the master window and index is specified, all the current settings -are returned in an list of "-option value" pairs. -.TP -\fBgrid remove \fIslave \fR?\fIslave ...\fR? -Removes each of the \fIslave\fRs from grid for its -master and unmaps their windows. -The slaves will no longer be managed by the grid geometry manager. -However, the configuration options for that window are remembered, -so that if the -slave is managed once more by the grid geometry manager, the previous -values are retained. -.TP -\fBgrid size \fImaster\fR -Returns the size of the grid (in columns then rows) for \fImaster\fP. -The size is determined either by the \fIslave\fP occupying the largest -row or column, or the largest column or row with a \fBminsize\fP, -\fBweight\fP, or \fBpad\fP that is non-zero. -.TP -\fBgrid slaves \fImaster\fR ?\fI\-option value\fR? -If no options are supplied, a list of all of the slaves in \fImaster\fR -are returned, most recently manages first. -\fIOption\fP can be either \fB\-row\fP or \fB\-column\fP which -causes only the slaves in the row (or column) specified by \fIvalue\fP -to be returned. -.SH "RELATIVE PLACEMENT" -.PP -The \fBgrid\fP command contains a limited set of capabilities that -permit layouts to be created without specifying the row and column -information for each slave. This permits slaves to be rearranged, -added, or removed without the need to explicitly specify row and -column information. -When no column or row information is specified for a \fIslave\fP, -default values are chosen for -\fBcolumn\fP, \fBrow\fP, \fBcolumnspan\fP and \fBrowspan\fP -at the time the \fIslave\fP is managed. The values are chosen -based upon the current layout of the grid, the position of the \fIslave\fP -relative to other \fIslave\fPs in the same grid command, and the presence -of the characters \fB\-\fP, \fBx\fP, and \fB^\fP in \fBgrid\fP -command where \fIslave\fP names are normally expected. -.RS -.TP -\fB\-\fP -This increases the columnspan of the \fIslave\fP to the left. Several -\fB\-\fP's in a row will successively increase the columnspan. A \fB\-\fP -may not follow a \fB^\fP or a \fBx\fP, nor may it be the first \fIslave\fP -argument to \fBgrid configure\fR. -.TP -\fBx\fP -This leaves an empty column between the \fIslave\fP on the left and -the \fIslave\fP on the right. -.TP -\fB^\fP -This extends the \fBrowspan\fP of the \fIslave\fP above the \fB^\fP's -in the grid. The number of \fB^\fP's in a row must match the number of -columns spanned by the \fIslave\fP above it. -.RE -.SH "THE GRID ALGORITHM" -.PP -The grid geometry manager lays out its slaves in three steps. -In the first step, the minimum size needed to fit all of the slaves -is computed, then (if propagation is turned on), a request is made -of the master window to become that size. -In the second step, the requested size is compared against the actual size -of the master. If the sizes are different, then spaces is added to or taken -away from the layout as needed. -For the final step, each slave is positioned in its row(s) and column(s) -based on the setting of its \fIsticky\fP flag. -.PP -To compute the minimum size of a layout, the grid geometry manager -first looks at all slaves whose columnspan and rowspan values are one, -and computes the nominal size of each row or column to be either the -\fIminsize\fP for that row or column, or the sum of the \fIpad\fPding -plus the size of the largest slave, whichever is greater. After that -the rows or columns in each uniform group adapt to each other. Then -the slaves whose rowspans or columnspans are greater than one are -examined. If a group of rows or columns need to be increased in size -in order to accommodate these slaves, then extra space is added to each -row or column in the group according to its \fIweight\fP. For each -group whose weights are all zero, the additional space is apportioned -equally. -.PP -When multiple rows or columns belong to a uniform group, the space -allocated to them is always in proportion to their weights. (A weight -of zero is considered to be 1.) In other words, a row or column -configured with \fB-weight 1 -uniform a\fP will have exactly the same -size as any other row or column configured with \fB-weight 1 -uniform -a\fP. A row or column configured with \fB-weight 2 -uniform b\fR will -be exactly twice as large as one that is configured with \fB-weight 1 --uniform b\fP. -.PP -More technically, each row or column in the group will have a size -equal to \fIk*weight\fP for some constant \fIk\fP. The constant -\fIk\fP is chosen so that no row or column becomes smaller than its -minimum size. For example, if all rows or columns in a group have the -same weight, then each row or column will have the same size as the -largest row or column in the group. -.PP -For masters whose size is larger than the requested layout, the additional -space is apportioned according to the row and column weights. If all of -the weights are zero, the layout is centered within its master. -For masters whose size is smaller than the requested layout, space is taken -away from columns and rows according to their weights. However, once a -column or row shrinks to its minsize, its weight is taken to be zero. -If more space needs to be removed from a layout than would be permitted, as -when all the rows or columns are at there minimum sizes, the layout is -clipped on the bottom and right. -.SH "GEOMETRY PROPAGATION" -.PP -The grid geometry manager normally computes how large a master must be to -just exactly meet the needs of its slaves, and it sets the -requested width and height of the master to these dimensions. -This causes geometry information to propagate up through a -window hierarchy to a top-level window so that the entire -sub-tree sizes itself to fit the needs of the leaf windows. -However, the \fBgrid propagate\fR command may be used to -turn off propagation for one or more masters. -If propagation is disabled then grid will not set -the requested width and height of the master window. -This may be useful if, for example, you wish for a master -window to have a fixed size that you specify. - -.SH "RESTRICTIONS ON MASTER WINDOWS" -.PP -The master for each slave must either be the slave's parent -(the default) or a descendant of the slave's parent. -This restriction is necessary to guarantee that the -slave can be placed over any part of its master that is -visible without danger of the slave being clipped by its parent. -In addition, all slaves in one call to \fBgrid\fP must have the same master. -.SH "STACKING ORDER" -.PP -If the master for a slave is not its parent then you must make sure -that the slave is higher in the stacking order than the master. -Otherwise the master will obscure the slave and it will appear as -if the slave hasn't been managed correctly. -The easiest way to make sure the slave is higher than the master is -to create the master window first: the most recently created window -will be highest in the stacking order. -.SH CREDITS -.PP -The \fBgrid\fP command is based on ideas taken from the \fIGridBag\fP -geometry manager written by Doug. Stein, and the \fBblt_table\fR geometry -manager, written by George Howlett. -.SH KEYWORDS -geometry manager, location, grid, cell, propagation, size, pack diff --git a/tcl/doc/image.n b/tcl/doc/image.n deleted file mode 100644 index 7f26cbf94a..0000000000 --- a/tcl/doc/image.n +++ /dev/null @@ -1,98 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH image n 4.0 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -image \- Create and manipulate images -.SH SYNOPSIS -\fBimage\fR \fIoption \fR?\fIarg arg ...\fR? -.BE - -.SH DESCRIPTION -.PP -The \fBimage\fR command is used to create, delete, and query images. -It can take several different forms, depending on the -\fIoption\fR argument. The legal forms are: -.TP -\fBimage create \fItype \fR?\fIname\fR? ?\fIoption value ...\fR? -Creates a new image and returns its name. -\fItype\fR specifies the type of the image, which must be one of -the types currently defined (e.g., \fBbitmap\fR). -\fIname\fR specifies the name for the image; if it is omitted then -Tk picks a name of the form \fBimage\fIx\fR, where \fIx\fR is -an integer. -There may be any number of \fIoption\fR\-\fIvalue\fR pairs, -which provide configuration options for the new image. -The legal set of options is defined separately for each image -type; see below for details on the options for built-in image types. -If an image already exists by the given name then it is replaced -with the new image and any instances of that image will redisplay -with the new contents. -It is important to note that the image command will silently overwrite any -procedure that may currently be defined by the given name, so choose the -name wisely. It is recommended to use a separate namespace for image names -(e.g., \fB::img::logo\fR, \fB::img::large\fR). -.TP -\fBimage delete \fR?\fIname name\fR ...? -Deletes each of the named images and returns an empty string. -If there are instances of the images displayed in widgets, -the images won't actually be deleted until all of the instances -are released. -However, the association between the instances and the image -manager will be dropped. -Existing instances will retain their sizes but redisplay as -empty areas. -If a deleted image is recreated with another call to \fBimage create\fR, -the existing instances will use the new image. -.TP -\fBimage height \fIname\fR -Returns a decimal string giving the height of image \fIname\fR -in pixels. -.TP -\fBimage inuse \fIname\fR -Returns a boolean value indicating whether or not the image given by -\fIname\fR is in use by any widgets. -.TP -\fBimage names\fR -Returns a list containing the names of all existing images. -.TP -\fBimage type \fIname\fR -Returns the type of image \fIname\fR (the value of the \fItype\fR -argument to \fBimage create\fR when the image was created). -.TP -\fBimage types\fR -Returns a list whose elements are all of the valid image types -(i.e., all of the values that may be supplied for the \fItype\fR -argument to \fBimage create\fR). -.TP -\fBimage width \fIname\fR -Returns a decimal string giving the width of image \fIname\fR -in pixels. - -.SH "BUILT-IN IMAGE TYPES" -.PP -The following image types are defined by Tk so they will be available -in any Tk application. -Individual applications or extensions may define additional types. -.TP -\fBbitmap\fR -Each pixel in the image displays a foreground color, a background -color, or nothing. -See the \fBbitmap\fR manual entry for more information. -.TP -\fBphoto\fR -Displays a variety of full-color images, using dithering to -approximate colors on displays with limited color capabilities. -See the \fBphoto\fR manual entry for more information. - -.SH KEYWORDS -height, image, types of images, width diff --git a/tcl/doc/keysyms.n b/tcl/doc/keysyms.n deleted file mode 100644 index 0746d54357..0000000000 --- a/tcl/doc/keysyms.n +++ /dev/null @@ -1,930 +0,0 @@ -'\" -'\" Copyright (c) 1998-2000 by Scriptics Corporation. -'\" All rights reserved. -'\" -'\" RCS: @(#) $Id$ -'\" -'\" -.so man.macros -.TH keysyms n 8.3 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -keysyms \- keysyms recognized by Tk -.BE - -.SH DESCRIPTION -.PP -Tk recognizes many keysyms when specifying key bindings (eg, -\fBbind . \fR). The following list enumerates the -keysyms that will be recognized by Tk. Note that not all keysyms will -be valid on all platforms. For example, on Unix systems, the presence -of a particular keysym is dependant on the configuration of the -keyboard modifier map. This list shows keysyms along with their -decimal and hexidecimal values. -.PP -.CS -space 32 0x0020 -exclam 33 0x0021 -quotedbl 34 0x0022 -numbersign 35 0x0023 -dollar 36 0x0024 -percent 37 0x0025 -ampersand 38 0x0026 -quoteright 39 0x0027 -parenleft 40 0x0028 -parenright 41 0x0029 -asterisk 42 0x002a -plus 43 0x002b -comma 44 0x002c -minus 45 0x002d -period 46 0x002e -slash 47 0x002f -0 48 0x0030 -1 49 0x0031 -2 50 0x0032 -3 51 0x0033 -4 52 0x0034 -5 53 0x0035 -6 54 0x0036 -7 55 0x0037 -8 56 0x0038 -9 57 0x0039 -colon 58 0x003a -semicolon 59 0x003b -less 60 0x003c -equal 61 0x003d -greater 62 0x003e -question 63 0x003f -at 64 0x0040 -A 65 0x0041 -B 66 0x0042 -C 67 0x0043 -D 68 0x0044 -E 69 0x0045 -F 70 0x0046 -G 71 0x0047 -H 72 0x0048 -I 73 0x0049 -J 74 0x004a -K 75 0x004b -L 76 0x004c -M 77 0x004d -N 78 0x004e -O 79 0x004f -P 80 0x0050 -Q 81 0x0051 -R 82 0x0052 -S 83 0x0053 -T 84 0x0054 -U 85 0x0055 -V 86 0x0056 -W 87 0x0057 -X 88 0x0058 -Y 89 0x0059 -Z 90 0x005a -bracketleft 91 0x005b -backslash 92 0x005c -bracketright 93 0x005d -asciicircum 94 0x005e -underscore 95 0x005f -quoteleft 96 0x0060 -a 97 0x0061 -b 98 0x0062 -c 99 0x0063 -d 100 0x0064 -e 101 0x0065 -f 102 0x0066 -g 103 0x0067 -h 104 0x0068 -i 105 0x0069 -j 106 0x006a -k 107 0x006b -l 108 0x006c -m 109 0x006d -n 110 0x006e -o 111 0x006f -p 112 0x0070 -q 113 0x0071 -r 114 0x0072 -s 115 0x0073 -t 116 0x0074 -u 117 0x0075 -v 118 0x0076 -w 119 0x0077 -x 120 0x0078 -y 121 0x0079 -z 122 0x007a -braceleft 123 0x007b -bar 124 0x007c -braceright 125 0x007d -asciitilde 126 0x007e -nobreakspace 160 0x00a0 -exclamdown 161 0x00a1 -cent 162 0x00a2 -sterling 163 0x00a3 -currency 164 0x00a4 -yen 165 0x00a5 -brokenbar 166 0x00a6 -section 167 0x00a7 -diaeresis 168 0x00a8 -copyright 169 0x00a9 -ordfeminine 170 0x00aa -guillemotleft 171 0x00ab -notsign 172 0x00ac -hyphen 173 0x00ad -registered 174 0x00ae -macron 175 0x00af -degree 176 0x00b0 -plusminus 177 0x00b1 -twosuperior 178 0x00b2 -threesuperior 179 0x00b3 -acute 180 0x00b4 -mu 181 0x00b5 -paragraph 182 0x00b6 -periodcentered 183 0x00b7 -cedilla 184 0x00b8 -onesuperior 185 0x00b9 -masculine 186 0x00ba -guillemotright 187 0x00bb -onequarter 188 0x00bc -onehalf 189 0x00bd -threequarters 190 0x00be -questiondown 191 0x00bf -Agrave 192 0x00c0 -Aacute 193 0x00c1 -Acircumflex 194 0x00c2 -Atilde 195 0x00c3 -Adiaeresis 196 0x00c4 -Aring 197 0x00c5 -AE 198 0x00c6 -Ccedilla 199 0x00c7 -Egrave 200 0x00c8 -Eacute 201 0x00c9 -Ecircumflex 202 0x00ca -Ediaeresis 203 0x00cb -Igrave 204 0x00cc -Iacute 205 0x00cd -Icircumflex 206 0x00ce -Idiaeresis 207 0x00cf -Eth 208 0x00d0 -Ntilde 209 0x00d1 -Ograve 210 0x00d2 -Oacute 211 0x00d3 -Ocircumflex 212 0x00d4 -Otilde 213 0x00d5 -Odiaeresis 214 0x00d6 -multiply 215 0x00d7 -Ooblique 216 0x00d8 -Ugrave 217 0x00d9 -Uacute 218 0x00da -Ucircumflex 219 0x00db -Udiaeresis 220 0x00dc -Yacute 221 0x00dd -Thorn 222 0x00de -ssharp 223 0x00df -agrave 224 0x00e0 -aacute 225 0x00e1 -acircumflex 226 0x00e2 -atilde 227 0x00e3 -adiaeresis 228 0x00e4 -aring 229 0x00e5 -ae 230 0x00e6 -ccedilla 231 0x00e7 -egrave 232 0x00e8 -eacute 233 0x00e9 -ecircumflex 234 0x00ea -ediaeresis 235 0x00eb -igrave 236 0x00ec -iacute 237 0x00ed -icircumflex 238 0x00ee -idiaeresis 239 0x00ef -eth 240 0x00f0 -ntilde 241 0x00f1 -ograve 242 0x00f2 -oacute 243 0x00f3 -ocircumflex 244 0x00f4 -otilde 245 0x00f5 -odiaeresis 246 0x00f6 -division 247 0x00f7 -oslash 248 0x00f8 -ugrave 249 0x00f9 -uacute 250 0x00fa -ucircumflex 251 0x00fb -udiaeresis 252 0x00fc -yacute 253 0x00fd -thorn 254 0x00fe -ydiaeresis 255 0x00ff -Aogonek 417 0x01a1 -breve 418 0x01a2 -Lstroke 419 0x01a3 -Lcaron 421 0x01a5 -Sacute 422 0x01a6 -Scaron 425 0x01a9 -Scedilla 426 0x01aa -Tcaron 427 0x01ab -Zacute 428 0x01ac -.CE -.CS -Zcaron 430 0x01ae -Zabovedot 431 0x01af -aogonek 433 0x01b1 -ogonek 434 0x01b2 -lstroke 435 0x01b3 -lcaron 437 0x01b5 -sacute 438 0x01b6 -caron 439 0x01b7 -scaron 441 0x01b9 -scedilla 442 0x01ba -tcaron 443 0x01bb -zacute 444 0x01bc -doubleacute 445 0x01bd -zcaron 446 0x01be -zabovedot 447 0x01bf -Racute 448 0x01c0 -Abreve 451 0x01c3 -Cacute 454 0x01c6 -Ccaron 456 0x01c8 -Eogonek 458 0x01ca -Ecaron 460 0x01cc -Dcaron 463 0x01cf -Nacute 465 0x01d1 -Ncaron 466 0x01d2 -Odoubleacute 469 0x01d5 -Rcaron 472 0x01d8 -Uring 473 0x01d9 -Udoubleacute 475 0x01db -Tcedilla 478 0x01de -racute 480 0x01e0 -abreve 483 0x01e3 -cacute 486 0x01e6 -ccaron 488 0x01e8 -eogonek 490 0x01ea -ecaron 492 0x01ec -dcaron 495 0x01ef -nacute 497 0x01f1 -ncaron 498 0x01f2 -odoubleacute 501 0x01f5 -rcaron 504 0x01f8 -uring 505 0x01f9 -udoubleacute 507 0x01fb -tcedilla 510 0x01fe -abovedot 511 0x01ff -Hstroke 673 0x02a1 -Hcircumflex 678 0x02a6 -Iabovedot 681 0x02a9 -Gbreve 683 0x02ab -Jcircumflex 684 0x02ac -hstroke 689 0x02b1 -hcircumflex 694 0x02b6 -idotless 697 0x02b9 -gbreve 699 0x02bb -jcircumflex 700 0x02bc -Cabovedot 709 0x02c5 -Ccircumflex 710 0x02c6 -Gabovedot 725 0x02d5 -Gcircumflex 728 0x02d8 -Ubreve 733 0x02dd -Scircumflex 734 0x02de -cabovedot 741 0x02e5 -ccircumflex 742 0x02e6 -gabovedot 757 0x02f5 -gcircumflex 760 0x02f8 -ubreve 765 0x02fd -scircumflex 766 0x02fe -kappa 930 0x03a2 -Rcedilla 931 0x03a3 -Itilde 933 0x03a5 -Lcedilla 934 0x03a6 -Emacron 938 0x03aa -Gcedilla 939 0x03ab -Tslash 940 0x03ac -rcedilla 947 0x03b3 -itilde 949 0x03b5 -lcedilla 950 0x03b6 -emacron 954 0x03ba -gacute 955 0x03bb -tslash 956 0x03bc -ENG 957 0x03bd -eng 959 0x03bf -Amacron 960 0x03c0 -Iogonek 967 0x03c7 -Eabovedot 972 0x03cc -Imacron 975 0x03cf -Ncedilla 977 0x03d1 -Omacron 978 0x03d2 -Kcedilla 979 0x03d3 -Uogonek 985 0x03d9 -Utilde 989 0x03dd -Umacron 990 0x03de -amacron 992 0x03e0 -iogonek 999 0x03e7 -eabovedot 1004 0x03ec -imacron 1007 0x03ef -ncedilla 1009 0x03f1 -omacron 1010 0x03f2 -kcedilla 1011 0x03f3 -uogonek 1017 0x03f9 -utilde 1021 0x03fd -umacron 1022 0x03fe -overline 1150 0x047e -kana_fullstop 1185 0x04a1 -kana_openingbracket 1186 0x04a2 -kana_closingbracket 1187 0x04a3 -kana_comma 1188 0x04a4 -kana_middledot 1189 0x04a5 -kana_WO 1190 0x04a6 -kana_a 1191 0x04a7 -kana_i 1192 0x04a8 -kana_u 1193 0x04a9 -kana_e 1194 0x04aa -kana_o 1195 0x04ab -kana_ya 1196 0x04ac -kana_yu 1197 0x04ad -kana_yo 1198 0x04ae -kana_tu 1199 0x04af -prolongedsound 1200 0x04b0 -kana_A 1201 0x04b1 -kana_I 1202 0x04b2 -kana_U 1203 0x04b3 -kana_E 1204 0x04b4 -kana_O 1205 0x04b5 -kana_KA 1206 0x04b6 -kana_KI 1207 0x04b7 -kana_KU 1208 0x04b8 -kana_KE 1209 0x04b9 -kana_KO 1210 0x04ba -kana_SA 1211 0x04bb -kana_SHI 1212 0x04bc -kana_SU 1213 0x04bd -kana_SE 1214 0x04be -kana_SO 1215 0x04bf -kana_TA 1216 0x04c0 -kana_TI 1217 0x04c1 -kana_TU 1218 0x04c2 -kana_TE 1219 0x04c3 -kana_TO 1220 0x04c4 -kana_NA 1221 0x04c5 -kana_NI 1222 0x04c6 -kana_NU 1223 0x04c7 -kana_NE 1224 0x04c8 -kana_NO 1225 0x04c9 -kana_HA 1226 0x04ca -kana_HI 1227 0x04cb -kana_HU 1228 0x04cc -kana_HE 1229 0x04cd -kana_HO 1230 0x04ce -kana_MA 1231 0x04cf -kana_MI 1232 0x04d0 -kana_MU 1233 0x04d1 -kana_ME 1234 0x04d2 -kana_MO 1235 0x04d3 -kana_YA 1236 0x04d4 -kana_YU 1237 0x04d5 -kana_YO 1238 0x04d6 -kana_RA 1239 0x04d7 -kana_RI 1240 0x04d8 -kana_RU 1241 0x04d9 -kana_RE 1242 0x04da -kana_RO 1243 0x04db -kana_WA 1244 0x04dc -kana_N 1245 0x04dd -voicedsound 1246 0x04de -semivoicedsound 1247 0x04df -Arabic_comma 1452 0x05ac -Arabic_semicolon 1467 0x05bb -Arabic_question_mark 1471 0x05bf -Arabic_hamza 1473 0x05c1 -Arabic_maddaonalef 1474 0x05c2 -Arabic_hamzaonalef 1475 0x05c3 -Arabic_hamzaonwaw 1476 0x05c4 -Arabic_hamzaunderalef 1477 0x05c5 -Arabic_hamzaonyeh 1478 0x05c6 -Arabic_alef 1479 0x05c7 -Arabic_beh 1480 0x05c8 -Arabic_tehmarbuta 1481 0x05c9 -Arabic_teh 1482 0x05ca -Arabic_theh 1483 0x05cb -Arabic_jeem 1484 0x05cc -Arabic_hah 1485 0x05cd -Arabic_khah 1486 0x05ce -Arabic_dal 1487 0x05cf -Arabic_thal 1488 0x05d0 -Arabic_ra 1489 0x05d1 -Arabic_zain 1490 0x05d2 -Arabic_seen 1491 0x05d3 -Arabic_sheen 1492 0x05d4 -Arabic_sad 1493 0x05d5 -Arabic_dad 1494 0x05d6 -Arabic_tah 1495 0x05d7 -Arabic_zah 1496 0x05d8 -Arabic_ain 1497 0x05d9 -Arabic_ghain 1498 0x05da -Arabic_tatweel 1504 0x05e0 -Arabic_feh 1505 0x05e1 -Arabic_qaf 1506 0x05e2 -Arabic_kaf 1507 0x05e3 -Arabic_lam 1508 0x05e4 -Arabic_meem 1509 0x05e5 -.CE -.CS -Arabic_noon 1510 0x05e6 -Arabic_heh 1511 0x05e7 -Arabic_waw 1512 0x05e8 -Arabic_alefmaksura 1513 0x05e9 -Arabic_yeh 1514 0x05ea -Arabic_fathatan 1515 0x05eb -Arabic_dammatan 1516 0x05ec -Arabic_kasratan 1517 0x05ed -Arabic_fatha 1518 0x05ee -Arabic_damma 1519 0x05ef -Arabic_kasra 1520 0x05f0 -Arabic_shadda 1521 0x05f1 -Arabic_sukun 1522 0x05f2 -Serbian_dje 1697 0x06a1 -Macedonia_gje 1698 0x06a2 -Cyrillic_io 1699 0x06a3 -Ukranian_je 1700 0x06a4 -Macedonia_dse 1701 0x06a5 -Ukranian_i 1702 0x06a6 -Ukranian_yi 1703 0x06a7 -Serbian_je 1704 0x06a8 -Serbian_lje 1705 0x06a9 -Serbian_nje 1706 0x06aa -Serbian_tshe 1707 0x06ab -Macedonia_kje 1708 0x06ac -Byelorussian_shortu 1710 0x06ae -Serbian_dze 1711 0x06af -numerosign 1712 0x06b0 -Serbian_DJE 1713 0x06b1 -Macedonia_GJE 1714 0x06b2 -Cyrillic_IO 1715 0x06b3 -Ukranian_JE 1716 0x06b4 -Macedonia_DSE 1717 0x06b5 -Ukranian_I 1718 0x06b6 -Ukranian_YI 1719 0x06b7 -Serbian_JE 1720 0x06b8 -Serbian_LJE 1721 0x06b9 -Serbian_NJE 1722 0x06ba -Serbian_TSHE 1723 0x06bb -Macedonia_KJE 1724 0x06bc -Byelorussian_SHORTU 1726 0x06be -Serbian_DZE 1727 0x06bf -Cyrillic_yu 1728 0x06c0 -Cyrillic_a 1729 0x06c1 -Cyrillic_be 1730 0x06c2 -Cyrillic_tse 1731 0x06c3 -Cyrillic_de 1732 0x06c4 -Cyrillic_ie 1733 0x06c5 -Cyrillic_ef 1734 0x06c6 -Cyrillic_ghe 1735 0x06c7 -Cyrillic_ha 1736 0x06c8 -Cyrillic_i 1737 0x06c9 -Cyrillic_shorti 1738 0x06ca -Cyrillic_ka 1739 0x06cb -Cyrillic_el 1740 0x06cc -Cyrillic_em 1741 0x06cd -Cyrillic_en 1742 0x06ce -Cyrillic_o 1743 0x06cf -Cyrillic_pe 1744 0x06d0 -Cyrillic_ya 1745 0x06d1 -Cyrillic_er 1746 0x06d2 -Cyrillic_es 1747 0x06d3 -Cyrillic_te 1748 0x06d4 -Cyrillic_u 1749 0x06d5 -Cyrillic_zhe 1750 0x06d6 -Cyrillic_ve 1751 0x06d7 -Cyrillic_softsign 1752 0x06d8 -Cyrillic_yeru 1753 0x06d9 -Cyrillic_ze 1754 0x06da -Cyrillic_sha 1755 0x06db -Cyrillic_e 1756 0x06dc -Cyrillic_shcha 1757 0x06dd -Cyrillic_che 1758 0x06de -Cyrillic_hardsign 1759 0x06df -Cyrillic_YU 1760 0x06e0 -Cyrillic_A 1761 0x06e1 -Cyrillic_BE 1762 0x06e2 -Cyrillic_TSE 1763 0x06e3 -Cyrillic_DE 1764 0x06e4 -Cyrillic_IE 1765 0x06e5 -Cyrillic_EF 1766 0x06e6 -Cyrillic_GHE 1767 0x06e7 -Cyrillic_HA 1768 0x06e8 -Cyrillic_I 1769 0x06e9 -Cyrillic_SHORTI 1770 0x06ea -Cyrillic_KA 1771 0x06eb -Cyrillic_EL 1772 0x06ec -Cyrillic_EM 1773 0x06ed -Cyrillic_EN 1774 0x06ee -Cyrillic_O 1775 0x06ef -Cyrillic_PE 1776 0x06f0 -Cyrillic_YA 1777 0x06f1 -Cyrillic_ER 1778 0x06f2 -Cyrillic_ES 1779 0x06f3 -Cyrillic_TE 1780 0x06f4 -Cyrillic_U 1781 0x06f5 -Cyrillic_ZHE 1782 0x06f6 -Cyrillic_VE 1783 0x06f7 -Cyrillic_SOFTSIGN 1784 0x06f8 -Cyrillic_YERU 1785 0x06f9 -Cyrillic_ZE 1786 0x06fa -Cyrillic_SHA 1787 0x06fb -Cyrillic_E 1788 0x06fc -Cyrillic_SHCHA 1789 0x06fd -Cyrillic_CHE 1790 0x06fe -Cyrillic_HARDSIGN 1791 0x06ff -Greek_ALPHAaccent 1953 0x07a1 -Greek_EPSILONaccent 1954 0x07a2 -Greek_ETAaccent 1955 0x07a3 -Greek_IOTAaccent 1956 0x07a4 -Greek_IOTAdiaeresis 1957 0x07a5 -Greek_IOTAaccentdiaeresis 1958 0x07a6 -Greek_OMICRONaccent 1959 0x07a7 -Greek_UPSILONaccent 1960 0x07a8 -Greek_UPSILONdieresis 1961 0x07a9 -Greek_UPSILONaccentdieresis 1962 0x07aa -Greek_OMEGAaccent 1963 0x07ab -Greek_alphaaccent 1969 0x07b1 -Greek_epsilonaccent 1970 0x07b2 -Greek_etaaccent 1971 0x07b3 -Greek_iotaaccent 1972 0x07b4 -Greek_iotadieresis 1973 0x07b5 -Greek_iotaaccentdieresis 1974 0x07b6 -Greek_omicronaccent 1975 0x07b7 -Greek_upsilonaccent 1976 0x07b8 -Greek_upsilondieresis 1977 0x07b9 -Greek_upsilonaccentdieresis 1978 0x07ba -Greek_omegaaccent 1979 0x07bb -Greek_ALPHA 1985 0x07c1 -Greek_BETA 1986 0x07c2 -Greek_GAMMA 1987 0x07c3 -Greek_DELTA 1988 0x07c4 -Greek_EPSILON 1989 0x07c5 -Greek_ZETA 1990 0x07c6 -Greek_ETA 1991 0x07c7 -Greek_THETA 1992 0x07c8 -Greek_IOTA 1993 0x07c9 -Greek_KAPPA 1994 0x07ca -Greek_LAMBDA 1995 0x07cb -Greek_MU 1996 0x07cc -Greek_NU 1997 0x07cd -Greek_XI 1998 0x07ce -Greek_OMICRON 1999 0x07cf -Greek_PI 2000 0x07d0 -Greek_RHO 2001 0x07d1 -Greek_SIGMA 2002 0x07d2 -Greek_TAU 2004 0x07d4 -Greek_UPSILON 2005 0x07d5 -Greek_PHI 2006 0x07d6 -Greek_CHI 2007 0x07d7 -Greek_PSI 2008 0x07d8 -Greek_OMEGA 2009 0x07d9 -Greek_alpha 2017 0x07e1 -Greek_beta 2018 0x07e2 -Greek_gamma 2019 0x07e3 -Greek_delta 2020 0x07e4 -Greek_epsilon 2021 0x07e5 -Greek_zeta 2022 0x07e6 -Greek_eta 2023 0x07e7 -Greek_theta 2024 0x07e8 -Greek_iota 2025 0x07e9 -Greek_kappa 2026 0x07ea -Greek_lambda 2027 0x07eb -Greek_mu 2028 0x07ec -Greek_nu 2029 0x07ed -Greek_xi 2030 0x07ee -Greek_omicron 2031 0x07ef -Greek_pi 2032 0x07f0 -Greek_rho 2033 0x07f1 -Greek_sigma 2034 0x07f2 -Greek_finalsmallsigma 2035 0x07f3 -Greek_tau 2036 0x07f4 -Greek_upsilon 2037 0x07f5 -Greek_phi 2038 0x07f6 -Greek_chi 2039 0x07f7 -Greek_psi 2040 0x07f8 -Greek_omega 2041 0x07f9 -leftradical 2209 0x08a1 -topleftradical 2210 0x08a2 -horizconnector 2211 0x08a3 -topintegral 2212 0x08a4 -botintegral 2213 0x08a5 -vertconnector 2214 0x08a6 -topleftsqbracket 2215 0x08a7 -botleftsqbracket 2216 0x08a8 -toprightsqbracket 2217 0x08a9 -botrightsqbracket 2218 0x08aa -topleftparens 2219 0x08ab -botleftparens 2220 0x08ac -toprightparens 2221 0x08ad -botrightparens 2222 0x08ae -leftmiddlecurlybrace 2223 0x08af -rightmiddlecurlybrace 2224 0x08b0 -topleftsummation 2225 0x08b1 -botleftsummation 2226 0x08b2 -topvertsummationconnector 2227 0x08b3 -botvertsummationconnector 2228 0x08b4 -toprightsummation 2229 0x08b5 -botrightsummation 2230 0x08b6 -rightmiddlesummation 2231 0x08b7 -.CE -.CS -lessthanequal 2236 0x08bc -notequal 2237 0x08bd -greaterthanequal 2238 0x08be -integral 2239 0x08bf -therefore 2240 0x08c0 -variation 2241 0x08c1 -infinity 2242 0x08c2 -nabla 2245 0x08c5 -approximate 2248 0x08c8 -similarequal 2249 0x08c9 -ifonlyif 2253 0x08cd -implies 2254 0x08ce -identical 2255 0x08cf -radical 2262 0x08d6 -includedin 2266 0x08da -includes 2267 0x08db -intersection 2268 0x08dc -union 2269 0x08dd -logicaland 2270 0x08de -logicalor 2271 0x08df -partialderivative 2287 0x08ef -function 2294 0x08f6 -leftarrow 2299 0x08fb -uparrow 2300 0x08fc -rightarrow 2301 0x08fd -downarrow 2302 0x08fe -blank 2527 0x09df -soliddiamond 2528 0x09e0 -checkerboard 2529 0x09e1 -ht 2530 0x09e2 -ff 2531 0x09e3 -cr 2532 0x09e4 -lf 2533 0x09e5 -nl 2536 0x09e8 -vt 2537 0x09e9 -lowrightcorner 2538 0x09ea -uprightcorner 2539 0x09eb -upleftcorner 2540 0x09ec -lowleftcorner 2541 0x09ed -crossinglines 2542 0x09ee -horizlinescan1 2543 0x09ef -horizlinescan3 2544 0x09f0 -horizlinescan5 2545 0x09f1 -horizlinescan7 2546 0x09f2 -horizlinescan9 2547 0x09f3 -leftt 2548 0x09f4 -rightt 2549 0x09f5 -bott 2550 0x09f6 -topt 2551 0x09f7 -vertbar 2552 0x09f8 -emspace 2721 0x0aa1 -enspace 2722 0x0aa2 -em3space 2723 0x0aa3 -em4space 2724 0x0aa4 -digitspace 2725 0x0aa5 -punctspace 2726 0x0aa6 -thinspace 2727 0x0aa7 -hairspace 2728 0x0aa8 -emdash 2729 0x0aa9 -endash 2730 0x0aaa -signifblank 2732 0x0aac -ellipsis 2734 0x0aae -doubbaselinedot 2735 0x0aaf -onethird 2736 0x0ab0 -twothirds 2737 0x0ab1 -onefifth 2738 0x0ab2 -twofifths 2739 0x0ab3 -threefifths 2740 0x0ab4 -fourfifths 2741 0x0ab5 -onesixth 2742 0x0ab6 -fivesixths 2743 0x0ab7 -careof 2744 0x0ab8 -figdash 2747 0x0abb -leftanglebracket 2748 0x0abc -decimalpoint 2749 0x0abd -rightanglebracket 2750 0x0abe -marker 2751 0x0abf -oneeighth 2755 0x0ac3 -threeeighths 2756 0x0ac4 -fiveeighths 2757 0x0ac5 -seveneighths 2758 0x0ac6 -trademark 2761 0x0ac9 -signaturemark 2762 0x0aca -trademarkincircle 2763 0x0acb -leftopentriangle 2764 0x0acc -rightopentriangle 2765 0x0acd -emopencircle 2766 0x0ace -emopenrectangle 2767 0x0acf -leftsinglequotemark 2768 0x0ad0 -rightsinglequotemark 2769 0x0ad1 -leftdoublequotemark 2770 0x0ad2 -rightdoublequotemark 2771 0x0ad3 -prescription 2772 0x0ad4 -minutes 2774 0x0ad6 -seconds 2775 0x0ad7 -latincross 2777 0x0ad9 -hexagram 2778 0x0ada -filledrectbullet 2779 0x0adb -filledlefttribullet 2780 0x0adc -filledrighttribullet 2781 0x0add -emfilledcircle 2782 0x0ade -emfilledrect 2783 0x0adf -enopencircbullet 2784 0x0ae0 -enopensquarebullet 2785 0x0ae1 -openrectbullet 2786 0x0ae2 -opentribulletup 2787 0x0ae3 -opentribulletdown 2788 0x0ae4 -openstar 2789 0x0ae5 -enfilledcircbullet 2790 0x0ae6 -enfilledsqbullet 2791 0x0ae7 -filledtribulletup 2792 0x0ae8 -filledtribulletdown 2793 0x0ae9 -leftpointer 2794 0x0aea -rightpointer 2795 0x0aeb -club 2796 0x0aec -diamond 2797 0x0aed -heart 2798 0x0aee -maltesecross 2800 0x0af0 -dagger 2801 0x0af1 -doubledagger 2802 0x0af2 -checkmark 2803 0x0af3 -ballotcross 2804 0x0af4 -musicalsharp 2805 0x0af5 -musicalflat 2806 0x0af6 -malesymbol 2807 0x0af7 -femalesymbol 2808 0x0af8 -telephone 2809 0x0af9 -telephonerecorder 2810 0x0afa -phonographcopyright 2811 0x0afb -caret 2812 0x0afc -singlelowquotemark 2813 0x0afd -doublelowquotemark 2814 0x0afe -cursor 2815 0x0aff -leftcaret 2979 0x0ba3 -rightcaret 2982 0x0ba6 -downcaret 2984 0x0ba8 -upcaret 2985 0x0ba9 -overbar 3008 0x0bc0 -downtack 3010 0x0bc2 -upshoe 3011 0x0bc3 -downstile 3012 0x0bc4 -underbar 3014 0x0bc6 -jot 3018 0x0bca -quad 3020 0x0bcc -uptack 3022 0x0bce -circle 3023 0x0bcf -upstile 3027 0x0bd3 -downshoe 3030 0x0bd6 -rightshoe 3032 0x0bd8 -leftshoe 3034 0x0bda -lefttack 3036 0x0bdc -righttack 3068 0x0bfc -hebrew_aleph 3296 0x0ce0 -hebrew_beth 3297 0x0ce1 -hebrew_gimmel 3298 0x0ce2 -hebrew_daleth 3299 0x0ce3 -hebrew_he 3300 0x0ce4 -hebrew_waw 3301 0x0ce5 -hebrew_zayin 3302 0x0ce6 -hebrew_het 3303 0x0ce7 -hebrew_teth 3304 0x0ce8 -hebrew_yod 3305 0x0ce9 -hebrew_finalkaph 3306 0x0cea -hebrew_kaph 3307 0x0ceb -hebrew_lamed 3308 0x0cec -hebrew_finalmem 3309 0x0ced -hebrew_mem 3310 0x0cee -hebrew_finalnun 3311 0x0cef -hebrew_nun 3312 0x0cf0 -hebrew_samekh 3313 0x0cf1 -hebrew_ayin 3314 0x0cf2 -hebrew_finalpe 3315 0x0cf3 -hebrew_pe 3316 0x0cf4 -hebrew_finalzadi 3317 0x0cf5 -hebrew_zadi 3318 0x0cf6 -hebrew_kuf 3319 0x0cf7 -hebrew_resh 3320 0x0cf8 -hebrew_shin 3321 0x0cf9 -hebrew_taf 3322 0x0cfa -BackSpace 65288 0xff08 -Tab 65289 0xff09 -Linefeed 65290 0xff0a -Clear 65291 0xff0b -Return 65293 0xff0d -Pause 65299 0xff13 -Scroll_Lock 65300 0xff14 -Sys_Req 65301 0xff15 -Escape 65307 0xff1b -Multi_key 65312 0xff20 -Kanji 65313 0xff21 -Home 65360 0xff50 -Left 65361 0xff51 -Up 65362 0xff52 -Right 65363 0xff53 -Down 65364 0xff54 -Prior 65365 0xff55 -Next 65366 0xff56 -End 65367 0xff57 -Begin 65368 0xff58 -Win_L 65371 0xff5b -Win_R 65372 0xff5c -.CE -.CS -App 65373 0xff5d -Select 65376 0xff60 -Print 65377 0xff61 -Execute 65378 0xff62 -Insert 65379 0xff63 -Undo 65381 0xff65 -Redo 65382 0xff66 -Menu 65383 0xff67 -Find 65384 0xff68 -Cancel 65385 0xff69 -Help 65386 0xff6a -Break 65387 0xff6b -Hebrew_switch 65406 0xff7e -Num_Lock 65407 0xff7f -KP_Space 65408 0xff80 -KP_Tab 65417 0xff89 -KP_Enter 65421 0xff8d -KP_F1 65425 0xff91 -KP_F2 65426 0xff92 -KP_F3 65427 0xff93 -KP_F4 65428 0xff94 -KP_Multiply 65450 0xffaa -KP_Add 65451 0xffab -KP_Separator 65452 0xffac -KP_Subtract 65453 0xffad -KP_Decimal 65454 0xffae -KP_Divide 65455 0xffaf -KP_0 65456 0xffb0 -KP_1 65457 0xffb1 -KP_2 65458 0xffb2 -KP_3 65459 0xffb3 -KP_4 65460 0xffb4 -KP_5 65461 0xffb5 -KP_6 65462 0xffb6 -KP_7 65463 0xffb7 -KP_8 65464 0xffb8 -KP_9 65465 0xffb9 -KP_Equal 65469 0xffbd -F1 65470 0xffbe -F2 65471 0xffbf -F3 65472 0xffc0 -F4 65473 0xffc1 -F5 65474 0xffc2 -F6 65475 0xffc3 -F7 65476 0xffc4 -F8 65477 0xffc5 -F9 65478 0xffc6 -F10 65479 0xffc7 -L1 65480 0xffc8 -L2 65481 0xffc9 -L3 65482 0xffca -L4 65483 0xffcb -L5 65484 0xffcc -L6 65485 0xffcd -L7 65486 0xffce -L8 65487 0xffcf -L9 65488 0xffd0 -L10 65489 0xffd1 -R1 65490 0xffd2 -R2 65491 0xffd3 -R3 65492 0xffd4 -R4 65493 0xffd5 -R5 65494 0xffd6 -R6 65495 0xffd7 -R7 65496 0xffd8 -R8 65497 0xffd9 -R9 65498 0xffda -R10 65499 0xffdb -R11 65500 0xffdc -R12 65501 0xffdd -F33 65502 0xffde -R14 65503 0xffdf -R15 65504 0xffe0 -Shift_L 65505 0xffe1 -Shift_R 65506 0xffe2 -Control_L 65507 0xffe3 -Control_R 65508 0xffe4 -Caps_Lock 65509 0xffe5 -Shift_Lock 65510 0xffe6 -Meta_L 65511 0xffe7 -Meta_R 65512 0xffe8 -Alt_L 65513 0xffe9 -Alt_R 65514 0xffea -Super_L 65515 0xffeb -Super_R 65516 0xffec -Hyper_L 65517 0xffed -Hyper_R 65518 0xffee -Delete 65535 0xffff -.CE - -.SH "SEE ALSO" -bind - -.SH KEYWORDS -keysym, bind, binding diff --git a/tcl/doc/label.n b/tcl/doc/label.n deleted file mode 100644 index 274592d1e7..0000000000 --- a/tcl/doc/label.n +++ /dev/null @@ -1,114 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH label n 4.0 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -label \- Create and manipulate label widgets -.SH SYNOPSIS -\fBlabel\fR \fIpathName \fR?\fIoptions\fR? -.SO -\-activebackground \-font \-pady -\-activeforeground \-foreground \-relief -\-anchor \-highlightbackground \-takefocus -\-background \-highlightcolor \-text -\-bitmap \-highlightthickness \-textvariable -\-borderwidth \-image \-underline -\-cursor \-justify \-wraplength -\-disabledforeground \-padx -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-height height Height -Specifies a desired height for the label. -If an image or bitmap is being displayed in the label then the value is in -screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR); -for text it is in lines of text. -If this option isn't specified, the label's desired height is computed -from the size of the image or bitmap or text being displayed in it. -.OP \-state state State -Specifies one of three states for the label: \fBnormal\fR, \fBactive\fR, -or \fBdisabled\fR. In normal state the button is displayed using the -\fBforeground\fR and \fBbackground\fR options. In active state -the label is displayed using the \fBactiveForeground\fR and -\fBactiveBackground\fR options. In the disabled state the -\fBdisabledForeground\fR and \fBbackground\fR options determine how -the button is displayed. -.OP \-width width Width -Specifies a desired width for the label. -If an image or bitmap is being displayed in the label then the value is in -screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR); -for text it is in characters. -If this option isn't specified, the label's desired width is computed -from the size of the image or bitmap or text being displayed in it. -.BE - -.SH DESCRIPTION -.PP -The \fBlabel\fR command creates a new window (given by the -\fIpathName\fR argument) and makes it into a label widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the label such as its colors, font, -text, and initial relief. The \fBlabel\fR command returns its -\fIpathName\fR argument. At the time this command is invoked, -there must not exist a window named \fIpathName\fR, but -\fIpathName\fR's parent must exist. -.PP -A label is a widget that displays a textual string, bitmap or image. -If text is displayed, it must all be in a single font, but it -can occupy multiple lines on the screen (if it contains newlines -or if wrapping occurs because of the \fBwrapLength\fR option) and -one of the characters may optionally be underlined using the -\fBunderline\fR option. -The label can be manipulated in a few simple ways, such as -changing its relief or text, using the commands described below. - -.SH "WIDGET COMMAND" -.PP -The \fBlabel\fR command creates a new Tcl command whose -name is \fIpathName\fR. This -command may be used to invoke various -operations on the widget. It has the following general form: -.CS -\fIpathName option \fR?\fIarg arg ...\fR? -.CE -\fIOption\fR and the \fIarg\fRs -determine the exact behavior of the command. The following -commands are possible for label widgets: -.TP -\fIpathName \fBcget\fR \fIoption\fR -Returns the current value of the configuration option given -by \fIoption\fR. -\fIOption\fR may have any of the values accepted by the \fBlabel\fR -command. -.TP -\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -Query or modify the configuration options of the widget. -If no \fIoption\fR is specified, returns a list describing all of -the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for -information on the format of this list). If \fIoption\fR is specified -with no \fIvalue\fR, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no \fIoption\fR is specified). If -one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given widget option(s) to have the given value(s); in -this case the command returns an empty string. -\fIOption\fR may have any of the values accepted by the \fBlabel\fR -command. - -.SH BINDINGS -.PP -When a new label is created, it has no default event bindings: -labels are not intended to be interactive. - -.SH KEYWORDS -label, widget diff --git a/tcl/doc/labelframe.n b/tcl/doc/labelframe.n deleted file mode 100644 index 29ac99c29c..0000000000 --- a/tcl/doc/labelframe.n +++ /dev/null @@ -1,147 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH labelframe n 8.4 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -labelframe \- Create and manipulate labelframe widgets -.SH SYNOPSIS -\fBlabelframe\fR \fIpathName\fR ?\fIoptions\fR? -.SO -\-borderwidth \-highlightbackground \-pady -\-cursor \-highlightcolor \-relief -\-font \-highlightthickness \-takefocus -\-foreground \-padx \-text -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-background background Background -This option is the same as the standard \fBbackground\fR option -except that its value may also be specified as an empty string. -In this case, the widget will display no background or border, and -no colors will be consumed from its colormap for its background -and border. -.OP \-class class Class -Specifies a class for the window. -This class will be used when querying the option database for -the window's other options, and it will also be used later for -other purposes such as bindings. -The \fBclass\fR option may not be changed with the \fBconfigure\fR -widget command. -.OP \-colormap colormap Colormap -Specifies a colormap to use for the window. -The value may be either \fBnew\fR, in which case a new colormap is -created for the window and its children, or the name of another -window (which must be on the same screen and have the same visual -as \fIpathName\fR), in which case the new window will use the colormap -from the specified window. -If the \fBcolormap\fR option is not specified, the new window -uses the same colormap as its parent. -This option may not be changed with the \fBconfigure\fR -widget command. -.OP \-container container Container -The value must be a boolean. If true, it means that this window will -be used as a container in which some other application will be embedded -(for example, a Tk toplevel can be embedded using the \fB\-use\fR option). -The window will support the appropriate window manager protocols for -things like geometry requests. The window should not have any -children of its own in this application. -This option may not be changed with the \fBconfigure\fR -widget command. -.OP \-height height Height -Specifies the desired height for the window in any of the forms -acceptable to \fBTk_GetPixels\fR. -If this option is less than or equal to zero then the window will -not request any size at all. -.OP \-labelanchor labelAnchor LabelAnchor -Specifies where to place the label. A label is only displayed if the -\fB\-text\fR option is not the empty string. -Valid values for this option are (listing them clockwise) -\fBnw\fR, \fBn\fR, \fBne\fR, \fBen\fR, \fBe\fR, \fBes\fR, -\fBse\fR, \fBs\fR,\fBsw\fR, \fBws\fR, \fBw\fR and \fBwn\fR. -The default value is \fBnw\fR. -.OP \-labelwidget labelWidget LabelWidget -Specifies a widget to use as label. This overrides any \fB\-text\fR -option. The widget must exist before being used as \fB\-labelwidget\fR -and if it is not a descendant of this window, it will be raised -above it in the stacking order. -.OP \-visual visual Visual -Specifies visual information for the new window in any of the -forms accepted by \fBTk_GetVisual\fR. -If this option is not specified, the new window will use the same -visual as its parent. -The \fBvisual\fR option may not be modified with the \fBconfigure\fR -widget command. -.OP \-width width Width -Specifies the desired width for the window in any of the forms -acceptable to \fBTk_GetPixels\fR. -If this option is less than or equal to zero then the window will -not request any size at all. -.BE - -.SH DESCRIPTION -.PP -The \fBlabelframe\fR command creates a new window (given by the -\fIpathName\fR argument) and makes it into a labelframe widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the labelframe such as its background color -and relief. The \fBlabelframe\fR command returns the -path name of the new window. -.PP -A labelframe is a simple widget. Its primary purpose is to act as a -spacer or container for complex window layouts. It has the features -of a \fBframe\fR plus the ability to display a label. -.SH "WIDGET COMMAND" -.PP -The \fBlabelframe\fR command creates a new Tcl command whose -name is the same as the path name of the labelframe's window. This -command may be used to invoke various -operations on the widget. It has the following general form: -.CS -\fIpathName option \fR?\fIarg arg ...\fR? -.CE -\fIPathName\fR is the name of the command, which is the same as -the labelframe widget's path name. \fIOption\fR and the \fIarg\fRs -determine the exact behavior of the command. The following -commands are possible for frame widgets: -.TP -\fIpathName \fBcget\fR \fIoption\fR -Returns the current value of the configuration option given -by \fIoption\fR. -\fIOption\fR may have any of the values accepted by the \fBlabelframe\fR -command. -.TP -\fIpathName \fBconfigure\fR ?\fIoption\fR? \fI?value option value ...\fR? -Query or modify the configuration options of the widget. -If no \fIoption\fR is specified, returns a list describing all of -the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for -information on the format of this list). If \fIoption\fR is specified -with no \fIvalue\fR, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no \fIoption\fR is specified). If -one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given widget option(s) to have the given value(s); in -this case the command returns an empty string. -\fIOption\fR may have any of the values accepted by the \fBlabelframe\fR -command. - -.SH BINDINGS -.PP -When a new labelframe is created, it has no default event bindings: -labelframes are not intended to be interactive. - -.SH "SEE ALSO" -frame(n), label(n) - -.SH KEYWORDS -labelframe, widget diff --git a/tcl/doc/listbox.n b/tcl/doc/listbox.n deleted file mode 100644 index ad86edf567..0000000000 --- a/tcl/doc/listbox.n +++ /dev/null @@ -1,556 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH listbox n 8.4 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -listbox \- Create and manipulate listbox widgets -.SH SYNOPSIS -\fBlistbox\fR \fIpathName \fR?\fIoptions\fR? -.SO -\-activestyle \-height \-selectforeground -\-background \-highlightbackground \-setgrid -\-borderwidth \-highlightcolor \-state -\-cursor \-highlightthickness \-takefocus -\-disabledforeground \-relief \-width -\-exportselection \-selectbackground \-xscrollcommand -\-font \-selectborderwidth \-yscrollcommand -\-foreground -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.VS 8.4 -.OP \-activestyle activeStyle ActiveStyle -Specifies the style in which to draw the active element. This must be -one of \fBdotbox\fR (show a focus ring around the active element), -\fBnone\fR (nospecial indication of active element) or -\fBunderline\fR (underline the active element). -The default is \fBunderline\fR. -.VS 8.4 -.OP \-height height Height -Specifies the desired height for the window, in lines. -If zero or less, then the desired height for the window is made just -large enough to hold all the elements in the listbox. -.OP \-listvariable listVariable Variable -Specifies the name of a variable. The value of the variable is a list to -be displayed inside the widget; if the variable value changes then the -widget will automatically update itself to reflect the new value. Attempts -to assign a variable with an invalid list value to \fB\-listvariable\fR -will cause an error. Attempts to unset a variable in use as a -\fB\-listvariable\fR will fail but will not generate an error. -.OP \-selectmode selectMode SelectMode -Specifies one of several styles for manipulating the selection. -The value of the option may be arbitrary, but the default bindings -expect it to be either \fBsingle\fR, \fBbrowse\fR, \fBmultiple\fR, -or \fBextended\fR; the default value is \fBbrowse\fR. -.OP \-state state State -Specifies one of two states for the listbox: \fBnormal\fR or \fBdisabled\fR. -If the listbox is disabled then items may not be inserted or deleted, -items are drawn in the \fB-disabledforeground\fR color, and selection -cannot be modified and is not shown (though selection information is retained). -.OP \-width width Width -Specifies the desired width for the window in characters. -If the font doesn't have a uniform width then the width of the -character ``0'' is used in translating from character units to -screen units. -If zero or less, then the desired width for the window is made just -large enough to hold all the elements in the listbox. -.BE - -.SH DESCRIPTION -.PP -The \fBlistbox\fR command creates a new window (given by the -\fIpathName\fR argument) and makes it into a listbox widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the listbox such as its colors, font, -text, and relief. The \fBlistbox\fR command returns its -\fIpathName\fR argument. At the time this command is invoked, -there must not exist a window named \fIpathName\fR, but -\fIpathName\fR's parent must exist. -.PP -A listbox is a widget that displays a list of strings, one per line. -When first created, a new listbox has no elements. -Elements may be added or deleted using widget commands described -below. In addition, one or more elements may be selected as described -below. -If a listbox is exporting its selection (see \fBexportSelection\fR -option), then it will observe the standard X11 protocols -for handling the selection. -Listbox selections are available as type \fBSTRING\fR; -the value of the selection will be the text of the selected elements, with -newlines separating the elements. -.PP -It is not necessary for all the elements to be -displayed in the listbox window at once; commands described below -may be used to change the view in the window. Listboxes allow -scrolling in both directions using the standard \fBxScrollCommand\fR -and \fByScrollCommand\fR options. -They also support scanning, as described below. - -.SH "INDICES" -.PP -Many of the widget commands for listboxes take one or more indices -as arguments. -An index specifies a particular element of the listbox, in any of -the following ways: -.TP 12 -\fInumber\fR -Specifies the element as a numerical index, where 0 corresponds -to the first element in the listbox. -.TP 12 -\fBactive\fR -Indicates the element that has the location cursor. This element -will be displayed as specified by \fB\-activestyle\fR when the listbox -has the keyboard focus, and it is specified with the \fBactivate\fR -widget command. -.TP 12 -\fBanchor\fR -Indicates the anchor point for the selection, which is set with the -\fBselection anchor\fR widget command. -.TP 12 -\fBend\fR -Indicates the end of the listbox. -.VS 8.0 -For most commands this refers to the last element in the listbox, -but for a few commands such as \fBindex\fR and \fBinsert\fR -it refers to the element just after the last one. -.VE -.TP 12 -\fB@\fIx\fB,\fIy\fR -Indicates the element that covers the point in the listbox window -specified by \fIx\fR and \fIy\fR (in pixel coordinates). If no -element covers that point, then the closest element to that -point is used. -.LP -In the widget command descriptions below, arguments named \fIindex\fR, -\fIfirst\fR, and \fIlast\fR always contain text indices in one of -the above forms. - -.SH "WIDGET COMMAND" -.PP -The \fBlistbox\fR command creates a new Tcl command whose -name is \fIpathName\fR. This -command may be used to invoke various -operations on the widget. It has the following general form: -.CS -\fIpathName option \fR?\fIarg arg ...\fR? -.CE -\fIOption\fR and the \fIarg\fRs -determine the exact behavior of the command. The following -commands are possible for listbox widgets: -.TP -\fIpathName \fBactivate\fR \fIindex\fR -Sets the active element to the one indicated by \fIindex\fR. -.VS 8.0 -If \fIindex\fR is outside the range of elements in the listbox -then the closest element is activated. -.VE -The active element is drawn as specified by \fB\-activestyle\fR when the -widget has the input focus, and its index may be retrieved with the -index \fBactive\fR. -.TP -\fIpathName \fBbbox\fR \fIindex\fR -Returns a list of four numbers describing the bounding box of -the text in the element given by \fIindex\fR. -The first two elements of the list give the x and y coordinates -of the upper-left corner of the screen area covered by the text -(specified in pixels relative to the widget) and the last two -elements give the width and height of the area, in pixels. -If no part of the element given by \fIindex\fR is visible on the -screen, -.VS 8.0 -or if \fIindex\fR refers to a non-existent element, -.VE -then the result is an empty string; if the element is -partially visible, the result gives the full area of the element, -including any parts that are not visible. -.TP -\fIpathName \fBcget\fR \fIoption\fR -Returns the current value of the configuration option given -by \fIoption\fR. -\fIOption\fR may have any of the values accepted by the \fBlistbox\fR -command. -.TP -\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -Query or modify the configuration options of the widget. -If no \fIoption\fR is specified, returns a list describing all of -the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for -information on the format of this list). If \fIoption\fR is specified -with no \fIvalue\fR, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no \fIoption\fR is specified). If -one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given widget option(s) to have the given value(s); in -this case the command returns an empty string. -\fIOption\fR may have any of the values accepted by the \fBlistbox\fR -command. -.TP -\fIpathName \fBcurselection\fR -Returns a list containing the numerical indices of -all of the elements in the listbox that are currently selected. -If there are no elements selected in the listbox then an empty -string is returned. -.TP -\fIpathName \fBdelete \fIfirst \fR?\fIlast\fR? -Deletes one or more elements of the listbox. \fIFirst\fR and \fIlast\fR -are indices specifying the first and last elements in the range -to delete. If \fIlast\fR isn't specified it defaults to -\fIfirst\fR, i.e. a single element is deleted. -.TP -\fIpathName \fBget \fIfirst\fR ?\fIlast\fR? -If \fIlast\fR is omitted, returns the contents of the listbox -element indicated by \fIfirst\fR, -.VS 8.0 -or an empty string if \fIfirst\fR refers to a non-existent element. -.VE -If \fIlast\fR is specified, the command returns a list whose elements -are all of the listbox elements between \fIfirst\fR and \fIlast\fR, -inclusive. -Both \fIfirst\fR and \fIlast\fR may have any of the standard -forms for indices. -.TP -\fIpathName \fBindex \fIindex\fR -Returns the integer index value that corresponds to \fIindex\fR. -.VS 8.0 -If \fIindex\fR is \fBend\fR the return value is a count of the number -of elements in the listbox (not the index of the last element). -.VE -.TP -\fIpathName \fBinsert \fIindex \fR?\fIelement element ...\fR? -Inserts zero or more new elements in the list just before the -element given by \fIindex\fR. If \fIindex\fR is specified as -\fBend\fR then the new elements are added to the end of the -list. Returns an empty string. -.TP -\fIpathName \fBitemcget \fIindex option\fR -Returns the current value of the item configuration option given -by \fIoption\fR. \fIOption\fR may have any of the values accepted -by the \fBlistbox itemconfigure\fR command. -.TP -\fIpathName \fBitemconfigure \fIindex\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? -Query or modify the configuration options of an item in the listbox. -If no \fIoption\fR is specified, returns a list describing all of -the available options for the item (see \fBTk_ConfigureInfo\fR for -information on the format of this list). If \fIoption\fR is specified -with no \fIvalue\fR, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no \fIoption\fR is specified). If -one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given widget option(s) to have the given value(s); in -this case the command returns an empty string. The following options -are currently supported for items: -.RS -.TP -\fB\-background \fIcolor\fR -\fIColor\fR specifies the background color to use when displaying the -item. It may have any of the forms accepted by \fBTk_GetColor\fR. -.TP -\fB\-foreground \fIcolor\fR -\fIColor\fR specifies the foreground color to use when displaying the -item. It may have any of the forms accepted by \fBTk_GetColor\fR. -.TP -\fB\-selectbackground \fIcolor\fR -\fIcolor\fR specifies the background color to use when displaying the -item while it is selected. It may have any of the forms accepted by -\fBTk_GetColor\fR. -.TP -\fB\-selectforeground \fIcolor\fR -\fIcolor\fR specifies the foreground color to use when displaying the -item while it is selected. It may have any of the forms accepted by -\fBTk_GetColor\fR. -.RE -.TP -\fIpathName \fBnearest \fIy\fR -Given a y-coordinate within the listbox window, this command returns -the index of the (visible) listbox element nearest to that y-coordinate. -.TP -\fIpathName \fBscan\fR \fIoption args\fR -This command is used to implement scanning on listboxes. It has -two forms, depending on \fIoption\fR: -.RS -.TP -\fIpathName \fBscan mark \fIx y\fR -Records \fIx\fR and \fIy\fR and the current view in the listbox -window; used in conjunction with later \fBscan dragto\fR commands. -Typically this command is associated with a mouse button press in -the widget. It returns an empty string. -.TP -\fIpathName \fBscan dragto \fIx y\fR. -This command computes the difference between its \fIx\fR and \fIy\fR -arguments and the \fIx\fR and \fIy\fR arguments to the last -\fBscan mark\fR command for the widget. -It then adjusts the view by 10 times the -difference in coordinates. This command is typically associated -with mouse motion events in the widget, to produce the effect of -dragging the list at high speed through the window. The return -value is an empty string. -.RE -.TP -\fIpathName \fBsee \fIindex\fR -Adjust the view in the listbox so that the element given by \fIindex\fR -is visible. -If the element is already visible then the command has no effect; -if the element is near one edge of the window then the listbox -scrolls to bring the element into view at the edge; otherwise -the listbox scrolls to center the element. -.TP -\fIpathName \fBselection \fIoption arg\fR -This command is used to adjust the selection within a listbox. It -has several forms, depending on \fIoption\fR: -.RS -.TP -\fIpathName \fBselection anchor \fIindex\fR -Sets the selection anchor to the element given by \fIindex\fR. -.VS 8.0 -If \fIindex\fR refers to a non-existent element, then the closest -element is used. -.VE -The selection anchor is the end of the selection that is fixed -while dragging out a selection with the mouse. -The index \fBanchor\fR may be used to refer to the anchor -element. -.TP -\fIpathName \fBselection clear \fIfirst \fR?\fIlast\fR? -If any of the elements between \fIfirst\fR and \fIlast\fR -(inclusive) are selected, they are deselected. -The selection state is not changed for elements outside -this range. -.TP -\fIpathName \fBselection includes \fIindex\fR -Returns 1 if the element indicated by \fIindex\fR is currently -selected, 0 if it isn't. -.TP -\fIpathName \fBselection set \fIfirst \fR?\fIlast\fR? -Selects all of the elements in the range between -\fIfirst\fR and \fIlast\fR, inclusive, without affecting -the selection state of elements outside that range. -.RE -.TP -\fIpathName \fBsize\fR -Returns a decimal string indicating the total number of elements -in the listbox. -.TP -\fIpathName \fBxview \fIargs\fR -This command is used to query and change the horizontal position of the -information in the widget's window. It can take any of the following -forms: -.RS -.TP -\fIpathName \fBxview\fR -Returns a list containing two elements. -Each element is a real fraction between 0 and 1; together they describe -the horizontal span that is visible in the window. -For example, if the first element is .2 and the second element is .6, -20% of the listbox's text is off-screen to the left, the middle 40% is visible -in the window, and 40% of the text is off-screen to the right. -These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR -option. -.TP -\fIpathName \fBxview\fR \fIindex\fR -Adjusts the view in the window so that the character position given by -\fIindex\fR is displayed at the left edge of the window. -Character positions are defined by the width of the character \fB0\fR. -.TP -\fIpathName \fBxview moveto\fI fraction\fR -Adjusts the view in the window so that \fIfraction\fR of the -total width of the listbox text is off-screen to the left. -\fIfraction\fR must be a fraction between 0 and 1. -.TP -\fIpathName \fBxview scroll \fInumber what\fR -This command shifts the view in the window left or right according to -\fInumber\fR and \fIwhat\fR. -\fINumber\fR must be an integer. -\fIWhat\fR must be either \fBunits\fR or \fBpages\fR or an abbreviation -of one of these. -If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by -\fInumber\fR character units (the width of the \fB0\fR character) -on the display; if it is \fBpages\fR then the view adjusts by -\fInumber\fR screenfuls. -If \fInumber\fR is negative then characters farther to the left -become visible; if it is positive then characters farther to the right -become visible. -.RE -.TP -\fIpathName \fByview \fI?args\fR? -This command is used to query and change the vertical position of the -text in the widget's window. -It can take any of the following forms: -.RS -.TP -\fIpathName \fByview\fR -Returns a list containing two elements, both of which are real fractions -between 0 and 1. -The first element gives the position of the listbox element at the -top of the window, relative to the listbox as a whole (0.5 means -it is halfway through the listbox, for example). -The second element gives the position of the listbox element just after -the last one in the window, relative to the listbox as a whole. -These are the same values passed to scrollbars via the \fB\-yscrollcommand\fR -option. -.TP -\fIpathName \fByview\fR \fIindex\fR -Adjusts the view in the window so that the element given by -\fIindex\fR is displayed at the top of the window. -.TP -\fIpathName \fByview moveto\fI fraction\fR -Adjusts the view in the window so that the element given by \fIfraction\fR -appears at the top of the window. -\fIFraction\fR is a fraction between 0 and 1; 0 indicates the first -element in the listbox, 0.33 indicates the element one-third the -way through the listbox, and so on. -.TP -\fIpathName \fByview scroll \fInumber what\fR -This command adjusts the view in the window up or down according to -\fInumber\fR and \fIwhat\fR. -\fINumber\fR must be an integer. -\fIWhat\fR must be either \fBunits\fR or \fBpages\fR. -If \fIwhat\fR is \fBunits\fR, the view adjusts up or down by -\fInumber\fR lines; if it is \fBpages\fR then -the view adjusts by \fInumber\fR screenfuls. -If \fInumber\fR is negative then earlier elements -become visible; if it is positive then later elements -become visible. -.RE - -.SH "DEFAULT BINDINGS" -.PP -Tk automatically creates class bindings for listboxes that give them -Motif-like behavior. Much of the behavior of a listbox is determined -by its \fBselectMode\fR option, which selects one of four ways -of dealing with the selection. -.PP -If the selection mode is \fBsingle\fR or \fBbrowse\fR, at most one -element can be selected in the listbox at once. -In both modes, clicking button 1 on an element selects -it and deselects any other selected item. -In \fBbrowse\fR mode it is also possible to drag the selection -with button 1. -.PP -If the selection mode is \fBmultiple\fR or \fBextended\fR, -any number of elements may be selected at once, including discontiguous -ranges. In \fBmultiple\fR mode, clicking button 1 on an element -toggles its selection state without affecting any other elements. -In \fBextended\fR mode, pressing button 1 on an element selects -it, deselects everything else, and sets the anchor to the element -under the mouse; dragging the mouse with button 1 -down extends the selection to include all the elements between -the anchor and the element under the mouse, inclusive. -.PP -Most people will probably want to use \fBbrowse\fR mode for -single selections and \fBextended\fR mode for multiple selections; -the other modes appear to be useful only in special situations. -.PP -Any time the selection changes in the listbox, the virtual event -\fB<>\fR will be generated. It is easiest to bind -to this event to be made aware of any changes to listbox selection. -.PP -In addition to the above behavior, the following additional behavior -is defined by the default bindings: -.IP [1] -In \fBextended\fR mode, the selected range can be adjusted by pressing -button 1 with the Shift key down: this modifies the selection to -consist of the elements between the anchor and the element under -the mouse, inclusive. -The un-anchored end of this new selection can also be dragged with -the button down. -.IP [2] -In \fBextended\fR mode, pressing button 1 with the Control key down -starts a toggle operation: the anchor is set to the element under -the mouse, and its selection state is reversed. The selection state -of other elements isn't changed. -If the mouse is dragged with button 1 down, then the selection state -of all elements between the anchor and the element under the mouse -is set to match that of the anchor element; the selection state of -all other elements remains what it was before the toggle operation -began. -.IP [3] -If the mouse leaves the listbox window with button 1 down, the window -scrolls away from the mouse, making information visible that used -to be off-screen on the side of the mouse. -The scrolling continues until the mouse re-enters the window, the -button is released, or the end of the listbox is reached. -.IP [4] -Mouse button 2 may be used for scanning. -If it is pressed and dragged over the listbox, the contents of -the listbox drag at high speed in the direction the mouse moves. -.IP [5] -If the Up or Down key is pressed, the location cursor (active -element) moves up or down one element. -If the selection mode is \fBbrowse\fR or \fBextended\fR then the -new active element is also selected and all other elements are -deselected. -In \fBextended\fR mode the new active element becomes the -selection anchor. -.IP [6] -In \fBextended\fR mode, Shift-Up and Shift-Down move the location -cursor (active element) up or down one element and also extend -the selection to that element in a fashion similar to dragging -with mouse button 1. -.IP [7] -The Left and Right keys scroll the listbox view left and right -by the width of the character \fB0\fR. -Control-Left and Control-Right scroll the listbox view left and -right by the width of the window. -Control-Prior and Control-Next also scroll left and right by -the width of the window. -.IP [8] -The Prior and Next keys scroll the listbox view up and down -by one page (the height of the window). -.IP [9] -The Home and End keys scroll the listbox horizontally to -the left and right edges, respectively. -.IP [10] -Control-Home sets the location cursor to the the first element in -the listbox, selects that element, and deselects everything else -in the listbox. -.IP [11] -Control-End sets the location cursor to the the last element in -the listbox, selects that element, and deselects everything else -in the listbox. -.IP [12] -In \fBextended\fR mode, Control-Shift-Home extends the selection -to the first element in the listbox and Control-Shift-End extends -the selection to the last element. -.IP [13] -In \fBmultiple\fR mode, Control-Shift-Home moves the location cursor -to the first element in the listbox and Control-Shift-End moves -the location cursor to the last element. -.IP [14] -The space and Select keys make a selection at the location cursor -(active element) just as if mouse button 1 had been pressed over -this element. -.IP [15] -In \fBextended\fR mode, Control-Shift-space and Shift-Select -extend the selection to the active element just as if button 1 -had been pressed with the Shift key down. -.IP [16] -In \fBextended\fR mode, the Escape key cancels the most recent -selection and restores all the elements in the selected range -to their previous selection state. -.IP [17] -Control-slash selects everything in the widget, except in -\fBsingle\fR and \fBbrowse\fR modes, in which case it selects -the active element and deselects everything else. -.IP [18] -Control-backslash deselects everything in the widget, except in -\fBbrowse\fR mode where it has no effect. -.IP [19] -The F16 key (labelled Copy on many Sun workstations) or Meta-w -copies the selection in the widget to the clipboard, if there is -a selection. - -.PP -The behavior of listboxes can be changed by defining new bindings for -individual widgets or by redefining the class bindings. - -.SH KEYWORDS -listbox, widget diff --git a/tcl/doc/loadTk.n b/tcl/doc/loadTk.n deleted file mode 100644 index 4a1ca940b5..0000000000 --- a/tcl/doc/loadTk.n +++ /dev/null @@ -1,76 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH "Safe Tk" n 8.0 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -loadTk \- Load Tk into a safe interpreter. -.SH SYNOPSIS -\fB::safe::loadTk \fIslave\fR ?\fB\-use\fR \fIwindowId\fR? ?\fB\-display\fR \fIdisplayName\fR? -.BE - -Safe Tk is based on Safe Tcl, which provides a mechanism -that allows restricted and mediated -access to auto-loading and packages for safe interpreters. -Safe Tk adds the ability to configure the interpreter -for safe Tk operations and load Tk into safe -interpreters. - -.SH DESCRIPTION -.PP -The \fB::safe::loadTk\fR command initializes the required data structures -in the named safe interpreter and then loads Tk into it. -The command returns the name of the safe interpreter. -If \fB\-use\fR is specified, the window identified by the specified system -dependent identifier \fIwindowId\fR is used to contain the ``.'' -window of the safe interpreter; it can be any valid id, eventually -referencing a window belonging to another application. As a convenience, -if the window you plan to use is a Tk Window of the application you -can use the window name (eg: \fB.x.y\fR) instead of its window Id -(\fB[winfo id .x.y]\fR). -When \fB\-use\fR is not specified, -a new toplevel window is created for the ``.'' window of -the safe interpreter. On X11 if you want the embedded window -to use another display than the default one, specify it with -\fB\-display\fR. -See the \fBSECURITY ISSUES\fR section below for implementation details. - -.SH "SECURITY ISSUES" -.PP -Please read the \fBsafe\fR manual page for Tcl to learn about the basic -security considerations for Safe Tcl. -.PP -\fB::safe::loadTk\fR adds the value of \fBtk_library\fR taken from the master -interpreter to the virtual access path of the safe interpreter so that -auto-loading will work in the safe interpreter. -.PP -.PP -Tk initialization is now safe with respect to not trusting -the slave's state for startup. \fB::safe::loadTk\fR -registers the slave's name so -when the Tk initialization (\fBTk_SafeInit\fR) is called -and in turn calls the master's \fB::safe::InitTk\fR it will -return the desired \fBargv\fR equivalent (\fB\-use\fR -\fIwindowId\fR, correct \fB\-display\fR, etc...). -.PP -When \fB\-use\fR is not used, the new toplevel created is specially -decorated so the user is always aware that the user interface presented comes -from a potentially unsafe code and can easily delete the corresponding -interpreter. -.PP -On X11, conflicting \fB\-use\fR and \fB\-display\fR are likely -to generate a fatal X error. - -.SH "SEE ALSO" -safe(n), interp(n), library(n), load(n), package(n), source(n), unknown(n) - -.SH KEYWORDS -alias, auto\-loading, auto_mkindex, load, master interpreter, safe -interpreter, slave interpreter, source diff --git a/tcl/doc/lower.n b/tcl/doc/lower.n deleted file mode 100644 index 8738c23e46..0000000000 --- a/tcl/doc/lower.n +++ /dev/null @@ -1,38 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH lower n 3.3 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -lower \- Change a window's position in the stacking order -.SH SYNOPSIS -\fBlower \fIwindow \fR?\fIbelowThis\fR? -.BE - -.SH DESCRIPTION -.PP -If the \fIbelowThis\fR argument is omitted then the command lowers -\fIwindow\fR so that it is below all of its siblings in the stacking -order (it will be obscured by any siblings that overlap it and -will not obscure any siblings). -If \fIbelowThis\fR is specified then it must be the path name of -a window that is either a sibling of \fIwindow\fR or the descendant -of a sibling of \fIwindow\fR. -In this case the \fBlower\fR command will insert -\fIwindow\fR into the stacking order just below \fIbelowThis\fR -(or the ancestor of \fIbelowThis\fR that is a sibling of \fIwindow\fR); -this could end up either raising or lowering \fIwindow\fR. - -.SH "SEE ALSO" -raise - -.SH KEYWORDS -lower, obscure, stacking order diff --git a/tcl/doc/menu.n b/tcl/doc/menu.n deleted file mode 100644 index b14c6a050f..0000000000 --- a/tcl/doc/menu.n +++ /dev/null @@ -1,784 +0,0 @@ -'\" -'\" Copyright (c) 1990-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$ -'\" -.so man.macros -.TH menu n 4.1 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -menu, tk_menuSetFocus \- Create and manipulate menu widgets -.SH SYNOPSIS -.nf -\fBmenu\fR \fIpathName \fR?\fIoptions\fR? -\fBtk_menuSetFocus\fR \fIpathName\fR -.SO -\-activebackground \-borderwidth \-foreground -\-activeborderwidth \-cursor \-relief -\-activeforeground \-disabledforeground \-takefocus -\-background \-font - -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.VS -.OP \-postcommand postCommand Command -If this option is specified then it provides a Tcl command to execute -each time the menu is posted. The command is invoked by the \fBpost\fR -widget command before posting the menu. Note that in 8.0 on Macintosh -and Windows, all commands in a menu systems are executed before any -are posted. This is due to the limitations in the individual platforms' -menu managers. -.VE -.OP \-selectcolor selectColor Background -For menu entries that are check buttons or radio buttons, this option -specifies the color to display in the indicator when the check button -or radio button is selected. -.OP \-tearoff tearOff TearOff -This option must have a proper boolean value, which specifies -whether or not the menu should include a tear-off entry at the -top. If so, it will exist as entry 0 of the menu and the other -entries will number starting at 1. The default -menu bindings arrange for the menu to be torn off when the tear-off -entry is invoked. -.OP \-tearoffcommand tearOffCommand TearOffCommand -If this option has a non-empty value, then it specifies a Tcl command -to invoke whenever the menu is torn off. The actual command will -consist of the value of this option, followed by a space, followed -by the name of the menu window, followed by a space, followed by -the name of the name of the torn off menu window. For example, if -the option's is ``\fBa b\fR'' and menu \fB.x.y\fR is torn off to -create a new menu \fB.x.tearoff1\fR, then the command -``\fBa b .x.y .x.tearoff1\fR'' will be invoked. -.VS -.OP \-title title Title -The string will be used to title the window created when this menu is -torn off. If the title is NULL, then the window will have the title -of the menubutton or the text of the cascade item from which this menu -was invoked. -.OP \-type type Type -This option can be one of \fBmenubar\fR, \fBtearoff\fR, or -\fBnormal\fR, and is set when the menu is created. While the string -returned by the configuration database will change if this option is -changed, this does not affect the menu widget's behavior. This is used -by the cloning mechanism and is not normally set outside of the Tk -library. -.VE -.BE - -.SH INTRODUCTION -.PP -The \fBmenu\fR command creates a new top-level window (given -by the \fIpathName\fR argument) and makes it into a menu widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the menu such as its colors and font. -The \fBmenu\fR command returns its -\fIpathName\fR argument. At the time this command is invoked, -there must not exist a window named \fIpathName\fR, but -\fIpathName\fR's parent must exist. -.PP -.VS -A menu is a widget that displays a collection of one-line entries arranged -in one or more columns. There exist several different types of entries, -each with different properties. Entries of different types may be -combined in a single menu. Menu entries are not the same as -entry widgets. In fact, menu entries are not even distinct widgets; -the entire menu is one widget. -.VE -.PP -Menu entries are displayed with up to three separate fields. -The main field is a label in the form of a text string, -a bitmap, or an image, controlled by the \fB\-label\fR, -\fB\-bitmap\fR, and \fB\-image\fR options for the entry. -If the \fB\-accelerator\fR option is specified for an entry then a second -textual field is displayed to the right of the label. The accelerator -typically describes a keystroke sequence that may be typed in the -application to cause the same result as invoking the menu entry. -The third field is an \fIindicator\fR. The indicator is present only for -checkbutton or radiobutton entries. It indicates whether the entry -is selected or not, and is displayed to the left of the entry's -string. -.PP -In normal use, an entry becomes active (displays itself differently) -whenever the mouse pointer is over the entry. If a mouse -button is released over the entry then the entry is \fIinvoked\fR. -The effect of invocation is different for each type of entry; -these effects are described below in the sections on individual -entries. -.PP -Entries may be \fIdisabled\fR, which causes their labels -and accelerators to be displayed -with dimmer colors. -The default menu bindings will not allow -a disabled entry to be activated or invoked. -Disabled entries may be re-enabled, at which point it becomes -possible to activate and invoke them again. -.VS -.PP -Whenever a menu's active entry is changed, a <> virtual -event is send to the menu. The active item can then be queried from -the menu, and an action can be taken, such as setting -context-sensitive help text for the entry. -.VE - -.SH "COMMAND ENTRIES" -.PP -The most common kind of menu entry is a command entry, which -behaves much like a button widget. When a command entry is -invoked, a Tcl command is executed. The Tcl -command is specified with the \fB\-command\fR option. - -.SH "SEPARATOR ENTRIES" -.PP -A separator is an entry that is displayed as a horizontal dividing -line. A separator may not be activated or invoked, and it has -no behavior other than its display appearance. - -.SH "CHECKBUTTON ENTRIES" -.PP -A checkbutton menu entry behaves much like a checkbutton widget. -When it is invoked it toggles back and forth between the selected -and deselected states. When the entry is selected, a particular -value is stored in a particular global variable (as determined by -the \fB\-onvalue\fR and \fB\-variable\fR options for the entry); when -the entry is deselected another value (determined by the -\fB\-offvalue\fR option) is stored in the global variable. -An indicator box is displayed to the left of the label in a checkbutton -entry. If the entry is selected then the indicator's center is displayed -in the color given by the \fB-selectcolor\fR option for the entry; -otherwise the indicator's center is displayed in the background color for -the menu. If a \fB\-command\fR option is specified for a checkbutton -entry, then its value is evaluated as a Tcl command each time the entry -is invoked; this happens after toggling the entry's -selected state. - -.SH "RADIOBUTTON ENTRIES" -.PP -A radiobutton menu entry behaves much like a radiobutton widget. -Radiobutton entries are organized in groups of which only one -entry may be selected at a time. Whenever a particular entry -becomes selected it stores a particular value into a particular -global variable (as determined by the \fB\-value\fR and -\fB\-variable\fR options for the entry). This action -causes any previously-selected entry in the same group -to deselect itself. -Once an entry has become selected, any change to the entry's -associated variable will cause the entry to deselect itself. -Grouping of radiobutton entries is determined by their -associated variables: if two entries have the same associated -variable then they are in the same group. -An indicator diamond is displayed to the left of the label in each -radiobutton entry. If the entry is selected then the indicator's -center is displayed in the color given by the \fB\-selectcolor\fR option -for the entry; -otherwise the indicator's center is displayed in the background color for -the menu. If a \fB\-command\fR option is specified for a radiobutton -entry, then its value is evaluated as a Tcl command each time the entry -is invoked; this happens after selecting the entry. - -.SH "CASCADE ENTRIES" -.PP -A cascade entry is one with an associated menu (determined -by the \fB\-menu\fR option). Cascade entries allow the construction -of cascading menus. -The \fBpostcascade\fR widget command can be used to post and unpost -the associated menu just next to of the cascade entry. -The associated menu must be a child of the menu containing -the cascade entry (this is needed in order for menu traversal to -work correctly). -.PP -A cascade entry posts its associated menu by invoking a -Tcl command of the form -.CS -\fImenu\fB post \fIx y\fR -.CE -where \fImenu\fR is the path name of the associated menu, and \fIx\fR -and \fIy\fR are the root-window coordinates of the upper-right -corner of the cascade entry. -.VS -On Unix, the lower-level menu is unposted by executing a Tcl command with -the form -.CS -\fImenu\fB unpost\fR -.CE -where \fImenu\fR is the name of the associated menu. -On other platforms, the platform's native code takes care of unposting the -menu. -.VE -.PP -.VS -If a \fB\-command\fR option is specified for a cascade entry then it is -evaluated as a Tcl command whenever the entry is invoked. This is not -supported on Windows. -.VE - -.SH "TEAR-OFF ENTRIES" -.PP -A tear-off entry appears at the top of the menu if enabled with the -\fBtearOff\fR option. It is not like other menu entries in that -it cannot be created with the \fBadd\fR widget command and -cannot be deleted with the \fBdelete\fR widget command. -When a tear-off entry is created it appears as a dashed line at -the top of the menu. Under the default bindings, invoking the -tear-off entry causes a torn-off copy to be made of the menu and -all of its submenus. - -.VS -.SH "MENUBARS" -.PP -Any menu can be set as a menubar for a toplevel window (see -\fBtoplevel\fR command for syntax). On the Macintosh, whenever the -toplevel is in front, this menu's cascade items will appear in the -menubar across the top of the main monitor. On Windows and Unix, this -menu's items will be displayed in a menubar accross the top of the -window. These menus will behave according to the interface guidelines -of their platforms. For every menu set as a menubar, a clone menu is -made. See the \fBCLONES\fR section for more information. -.PP -As noted, menubars may behave differently on different platforms. One -example of this concerns the handling of checkbuttons and radiobuttons -within the menu. While it is permitted to put these menu elements on -menubars, they may not be drawn with indicators on some platforms, due -to system restrictions. -.VE - -.VS -.SH "SPECIAL MENUS IN MENUBARS" -.PP -Certain menus in a menubar will be treated specially. On the Macintosh, -access to the special Apple and Help menus is provided. On Windows, -access to the Windows System menu in each window is provided. On X Windows, -a special right-justified help menu is provided. In all cases, these -menus must be created with the command name of the menubar menu concatenated -with the special name. So for a menubar named .menubar, on the Macintosh, -the special menus would be .menubar.apple and .menubar.help; on Windows, -the special menu would be .menubar.system; on X Windows, the help -menu would be .menubar.help. -.PP -When Tk sees an Apple menu on the Macintosh, that menu's contents make -up the first items of the Apple menu on the screen whenever the window -containing the menubar is in front. The menu is the -first one that the user sees and has a title which is an Apple logo. -After all of the Tk-defined items, the menu will have a separator, -followed by all of the items in the user's Apple Menu Items folder. -Since the System uses a different menu definition procedure for -the Apple menu than Tk uses for its menus, and the system APIs do -not fully support everything Tk tries to do, the menu item will only -have its text displayed. No font attributes, images, bitmaps, or colors -will be displayed. In addition, a menu with a tearoff item will have -the tearoff item displayed as "(TearOff)". -.PP -When Tk see a Help menu on the Macintosh, the menu's contents are -appended to the standard help menu on the right of the user's menubar -whenever the user's menubar is in front. The first items in the menu -are provided by Apple. Similar to the Apple Menu, cusomization in this -menu is limited to what the system provides. -.PP -When Tk sees a System menu on Windows, its items are appended to the -system menu that the menubar is attached to. This menu has an icon -representing a spacebar, and can be invoked with the mouse or by typing -Alt+Spacebar. Due to limitations in the Windows API, any font changes, -colors, images, bitmaps, or tearoff images will not appear in the -system menu. -.PP -When Tk see a Help menu on X Windows, the menu is moved to be last in -the menubar and is right justified. -.VE - -.VS -.SH "CLONES" -.PP -When a menu is set as a menubar for a toplevel window, or when a menu -is torn off, a clone of the menu is made. This clone is a menu widget -in its own right, but it is a child of the original. Changes in the -configuration of the original are reflected in the -clone. Additionally, any cascades that are pointed to are also cloned -so that menu traversal will work right. Clones are destroyed when -either the tearoff or menubar goes away, or when the original menu is -destroyed. -.VE - -.SH "WIDGET COMMAND" -.PP -The \fBmenu\fR command creates a new Tcl command whose -name is \fIpathName\fR. This -command may be used to invoke various -operations on the widget. It has the following general form: -.CS -\fIpathName option \fR?\fIarg arg ...\fR? -.CE -\fIOption\fR and the \fIarg\fRs -determine the exact behavior of the command. -.PP -Many of the widget commands for a menu take as one argument an -indicator of which entry of the menu to operate on. These -indicators are called \fIindex\fRes and may be specified in -any of the following forms: -.TP 12 -\fInumber\fR -Specifies the entry numerically, where 0 corresponds -to the top-most entry of the menu, 1 to the entry below it, and -so on. -.TP 12 -\fBactive\fR -Indicates the entry that is currently active. If no entry is -active then this form is equivalent to \fBnone\fR. This form may -not be abbreviated. -.TP 12 -\fBend\fR -Indicates the bottommost entry in the menu. If there are no -entries in the menu then this form is equivalent to \fBnone\fR. -This form may not be abbreviated. -.TP 12 -\fBlast\fR -Same as \fBend\fR. -.TP 12 -\fBnone\fR -Indicates ``no entry at all''; this is used most commonly with -the \fBactivate\fR option to deactivate all the entries in the -menu. In most cases the specification of \fBnone\fR causes -nothing to happen in the widget command. -This form may not be abbreviated. -.TP 12 -\fB@\fInumber\fR -In this form, \fInumber\fR is treated as a y-coordinate in the -menu's window; the entry closest to that y-coordinate is used. -For example, ``\fB@0\fR'' indicates the top-most entry in the -window. -.TP 12 -\fIpattern\fR -If the index doesn't satisfy one of the above forms then this -form is used. \fIPattern\fR is pattern-matched against the label of -each entry in the menu, in order from the top down, until a -matching entry is found. The rules of \fBTcl_StringMatch\fR -are used. -.PP -The following widget commands are possible for menu widgets: -.TP -\fIpathName \fBactivate \fIindex\fR -Change the state of the entry indicated by \fIindex\fR to \fBactive\fR -and redisplay it using its active colors. -Any previously-active entry is deactivated. If \fIindex\fR -is specified as \fBnone\fR, or if the specified entry is -disabled, then the menu ends up with no active entry. -Returns an empty string. -.TP -\fIpathName \fBadd \fItype \fR?\fIoption value option value ...\fR? -Add a new entry to the bottom of the menu. The new entry's type -is given by \fItype\fR and must be one of \fBcascade\fR, -\fBcheckbutton\fR, \fBcommand\fR, \fBradiobutton\fR, or \fBseparator\fR, -or a unique abbreviation of one of the above. If additional arguments -are present, they specify any of the following options: -.RS -.TP -\fB\-activebackground \fIvalue\fR -Specifies a background color to use for displaying this entry when it -is active. -If this option is specified as an empty string (the default), then the -\fBactiveBackground\fR option for the overall menu is used. -If the \fBtk_strictMotif\fR variable has been set to request strict -Motif compliance, then this option is ignored and the \fB\-background\fR -option is used in its place. -This option is not available for separator or tear-off entries. -.TP -\fB\-activeforeground \fIvalue\fR -Specifies a foreground color to use for displaying this entry when it -is active. -If this option is specified as an empty string (the default), then the -\fBactiveForeground\fR option for the overall menu is used. -This option is not available for separator or tear-off entries. -.TP -\fB\-accelerator \fIvalue\fR -Specifies a string to display at the right side of the menu entry. -Normally describes an accelerator keystroke sequence that may be -typed to invoke the same function as the menu entry. This option -is not available for separator or tear-off entries. -.TP -\fB\-background \fIvalue\fR -Specifies a background color to use for displaying this entry when it -is in the normal state (neither active nor disabled). -If this option is specified as an empty string (the default), then the -\fBbackground\fR option for the overall menu is used. -This option is not available for separator or tear-off entries. -.TP -\fB\-bitmap \fIvalue\fR -Specifies a bitmap to display in the menu instead of a textual -label, in any of the forms accepted by \fBTk_GetBitmap\fR. -This option overrides the \fB\-label\fR option but may be reset -to an empty string to enable a textual label to be displayed. -If a \fB\-image\fR option has been specified, it overrides -\fB\-bitmap\fR. -This option is not available for separator or tear-off entries. -.VS -.TP -\fB\-columnbreak \fIvalue\fR -When this option is zero, the appears below the previous entry. When -this option is one, the menu appears at the top of a new column in the -menu. -.VE -.TP -\fB\-command \fIvalue\fR -Specifies a Tcl command to execute when the menu entry is invoked. -Not available for separator or tear-off entries. -.TP -.VS 8.4 -\fB\-compound \fIvalue\fR -Specifies whether the menu entry should display both an image and text, -and if so, where the image should be placed relative to the text. -Valid values for this option are \fBbottom\fR, \fBcenter\fR, -\fBleft\fR, \fBnone\fR, \fBright\fR and \fBtop\fR. The default value -is \fBnone\fR, meaning that the button will display either an image or -text, depending on the values of the \fB\-image\fR and \fB\-bitmap\fR -options. -.VE -.TP -\fB\-font \fIvalue\fR -Specifies the font to use when drawing the label or accelerator -string in this entry. -If this option is specified as an empty string (the default) then -the \fBfont\fR option for the overall menu is used. -This option is not available for separator or tear-off entries. -.TP -\fB\-foreground \fIvalue\fR -Specifies a foreground color to use for displaying this entry when it -is in the normal state (neither active nor disabled). -If this option is specified as an empty string (the default), then the -\fBforeground\fR option for the overall menu is used. -This option is not available for separator or tear-off entries. -.VS -.TP -\fB\-hidemargin \fIvalue\fR -Specifies whether the standard margins should be drawn for this menu -entry. This is useful when creating palette with images in them, i.e., -color palettes, pattern palettes, etc. 1 indicates that the margin for -the entry is hidden; 0 means that the margin is used. -.VE -.TP -\fB\-image \fIvalue\fR -Specifies an image to display in the menu instead of a text string -or bitmap -The image must have been created by some previous invocation of -\fBimage create\fR. -This option overrides the \fB\-label\fR and \fB\-bitmap\fR options -but may be reset to an empty string to enable a textual or -bitmap label to be displayed. -This option is not available for separator or tear-off entries. -.TP -\fB\-indicatoron \fIvalue\fR -Available only for checkbutton and radiobutton entries. -\fIValue\fR is a boolean that determines whether or not the -indicator should be displayed. -.TP -\fB\-label \fIvalue\fR -Specifies a string to display as an identifying label in the menu -entry. Not available for separator or tear-off entries. -.TP -\fB\-menu \fIvalue\fR -Available only for cascade entries. Specifies the path name of -the submenu associated with this entry. -The submenu must be a child of the menu. -.TP -\fB\-offvalue \fIvalue\fR -Available only for checkbutton entries. Specifies the value to -store in the entry's associated variable when the entry is -deselected. -.TP -\fB\-onvalue \fIvalue\fR -Available only for checkbutton entries. Specifies the value to -store in the entry's associated variable when the entry is selected. -.TP -\fB\-selectcolor \fIvalue\fR -Available only for checkbutton and radiobutton entries. -Specifies the color to display in the indicator when the entry is -selected. -If the value is an empty string (the default) then the \fBselectColor\fR -option for the menu determines the indicator color. -.TP -\fB\-selectimage \fIvalue\fR -Available only for checkbutton and radiobutton entries. -Specifies an image to display in the entry (in place of -the \fB\-image\fR option) when it is selected. -\fIValue\fR is the name of an image, which must have been created -by some previous invocation of \fBimage create\fR. -This option is ignored unless the \fB\-image\fR option has -been specified. -.TP -\fB\-state \fIvalue\fR -Specifies one of three states for the entry: \fBnormal\fR, \fBactive\fR, -or \fBdisabled\fR. In normal state the entry is displayed using the -\fBforeground\fR option for the menu and the \fBbackground\fR -option from the entry or the menu. -The active state is typically used when the pointer is over the entry. -In active state the entry is displayed using the \fBactiveForeground\fR -option for the menu along with the \fBactivebackground\fR option from -the entry. Disabled state means that the entry -should be insensitive: the default bindings will refuse to activate -or invoke the entry. -In this state the entry is displayed according to the -\fBdisabledForeground\fR option for the menu and the -\fBbackground\fR option from the entry. -This option is not available for separator entries. -.TP -\fB\-underline \fIvalue\fR -Specifies the integer index of a character to underline in the entry. -This option is also queried by the default bindings and used to -implement keyboard traversal. -0 corresponds to the first character of the text displayed in the entry, -1 to the next character, and so on. -If a bitmap or image is displayed in the entry then this option is ignored. -This option is not available for separator or tear-off entries. -.TP -\fB\-value \fIvalue\fR -Available only for radiobutton entries. Specifies the value to -store in the entry's associated variable when the entry is selected. -If an empty string is specified, then the \fB\-label\fR option -for the entry as the value to store in the variable. -.TP -\fB\-variable \fIvalue\fR -Available only for checkbutton and radiobutton entries. Specifies -the name of a global value to set when the entry is selected. -For checkbutton entries the variable is also set when the entry -is deselected. For radiobutton entries, changing the variable -causes the currently-selected entry to deselect itself. -.LP -The \fBadd\fR widget command returns an empty string. -.RE -.TP -\fIpathName \fBcget\fR \fIoption\fR -Returns the current value of the configuration option given -by \fIoption\fR. -\fIOption\fR may have any of the values accepted by the \fBmenu\fR -command. -.VS -.TP -\fIpathName\fR \fBclone\fR \fInewPathname ?cloneType?\fR -Makes a clone of the current menu named \fInewPathName\fR. This clone -is a menu in its own right, but any changes to the clone are -propogated to the original menu and vice versa. \fIcloneType\fR can be -\fBnormal\fR, \fBmenubar\fR, or \fBtearoff\fR. Should not normally be -called outside of the Tk library. See the \fBCLONES\fR section for -more information. -.VE -.TP -\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -Query or modify the configuration options of the widget. -If no \fIoption\fR is specified, returns a list describing all of -the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for -information on the format of this list). If \fIoption\fR is specified -with no \fIvalue\fR, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no \fIoption\fR is specified). If -one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given widget option(s) to have the given value(s); in -this case the command returns an empty string. -\fIOption\fR may have any of the values accepted by the \fBmenu\fR -command. -.TP -\fIpathName \fBdelete \fIindex1\fR ?\fIindex2\fR? -Delete all of the menu entries between \fIindex1\fR and -\fIindex2\fR inclusive. -If \fIindex2\fR is omitted then it defaults to \fIindex1\fR. -Attempts to delete a tear-off menu entry are ignored (instead, you -should change the \fBtearOff\fR option to remove the tear-off entry). -.TP -\fIpathName \fBentrycget\fR \fIindex option\fR -Returns the current value of a configuration option for -the entry given by \fIindex\fR. -\fIOption\fR may have any of the values accepted by the \fBadd\fR -widget command. -.TP -\fIpathName \fBentryconfigure \fIindex \fR?\fIoptions\fR? -This command is similar to the \fBconfigure\fR command, except that -it applies to the options for an individual entry, whereas \fBconfigure\fR -applies to the options for the menu as a whole. -\fIOptions\fR may have any of the values accepted by the \fBadd\fR -widget command. If \fIoptions\fR are specified, options are modified -as indicated -in the command and the command returns an empty string. -If no \fIoptions\fR are specified, returns a list describing -the current options for entry \fIindex\fR (see \fBTk_ConfigureInfo\fR for -information on the format of this list). -.TP -\fIpathName \fBindex \fIindex\fR -Returns the numerical index corresponding to \fIindex\fR, or -\fBnone\fR if \fIindex\fR was specified as \fBnone\fR. -.TP -\fIpathName \fBinsert \fIindex\fR \fItype \fR?\fIoption value option value ...\fR? -Same as the \fBadd\fR widget command except that it inserts the new -entry just before the entry given by \fIindex\fR, instead of appending -to the end of the menu. The \fItype\fR, \fIoption\fR, and \fIvalue\fR -arguments have the same interpretation as for the \fBadd\fR widget -command. It is not possible to insert new menu entries before the -tear-off entry, if the menu has one. -.TP -\fIpathName \fBinvoke \fIindex\fR -Invoke the action of the menu entry. See the sections on the -individual entries above for details on what happens. If the -menu entry is disabled then nothing happens. If the -entry has a command associated with it then the result of that -command is returned as the result of the \fBinvoke\fR widget -command. Otherwise the result is an empty string. Note: invoking -a menu entry does not automatically unpost the menu; the default -bindings normally take care of this before invoking the \fBinvoke\fR -widget command. -.TP -\fIpathName \fBpost \fIx y\fR -Arrange for the menu to be displayed on the screen at the root-window -coordinates given by \fIx\fR and \fIy\fR. These coordinates are -adjusted if necessary to guarantee that the entire menu is visible on -the screen. This command normally returns an empty string. -If the \fBpostCommand\fR option has been specified, then its value is -executed as a Tcl script before posting the menu and the result of -that script is returned as the result of the \fBpost\fR widget -command. -If an error returns while executing the command, then the error is -returned without posting the menu. -.TP -\fIpathName \fBpostcascade \fIindex\fR -Posts the submenu associated with the cascade entry given by -\fIindex\fR, and unposts any previously posted submenu. -If \fIindex\fR doesn't correspond to a cascade entry, -or if \fIpathName\fR isn't posted, -the command has no effect except to unpost any currently posted -submenu. -.TP -\fIpathName \fBtype \fIindex\fR -Returns the type of the menu entry given by \fIindex\fR. -This is the \fItype\fR argument passed to the \fBadd\fR widget -command when the entry was created, such as \fBcommand\fR -or \fBseparator\fR, or \fBtearoff\fR for a tear-off entry. -.TP -.VS -\fIpathName \fBunpost\fR -Unmap the window so that it is no longer displayed. If a -lower-level cascaded menu is posted, unpost that menu. Returns an -empty string. This subcommand does not work on Windows and the -Macintosh, as those platforms have their own way of unposting menus. -.VE -.TP -\fIpathName \fByposition \fIindex\fR -Returns a decimal string giving the y-coordinate within the menu -window of the topmost pixel in the entry specified by \fIindex\fR. - -.SH "MENU CONFIGURATIONS" -.PP -The default bindings support four different ways of using menus: -.VS -.TP -\fBPulldown Menus in Menubar\fR -This is the most command case. You create a menu widget that will become the -menu bar. You then add cascade entries to this menu, specifying the -pull down menus you wish to use in your menu bar. You then create all -of the pulldowns. Once you have done this, specify the menu using the -\fB-menu\fR option of the toplevel's widget command. See the -\fBtoplevel\fR manual entry for details. -.VE -.TP -\fBPulldown Menus in Menu Buttons\fR -This is the compatable way to do menu bars. You create one menubutton -widget for each top-level menu, and typically you arrange a series of -menubuttons in a row in a menubar window. You also create the top-level menus -and any cascaded submenus, and tie them together with \fB\-menu\fR -options in menubuttons and cascade menu entries. The top-level menu must -be a child of the menubutton, and each submenu must be a child of the -menu that refers to it. Once you have done this, the default bindings -will allow users to traverse and invoke the tree of menus via its -menubutton; see the \fBmenubutton\fR manual entry for details. -.TP -\fBPopup Menus\fR -Popup menus typically post in response to a mouse button press or -keystroke. You create the popup menus and any cascaded submenus, -then you call the \fBtk_popup\fR procedure at the appropriate time -to post the top-level menu. -.TP -\fBOption Menus\fR -An option menu consists of a menubutton with an associated menu -that allows you to select one of several values. The current value -is displayed in the menubutton and is also stored in a global -variable. Use the \fBtk_optionMenu\fR procedure to create option -menubuttons and their menus. -.TP -\fBTorn-off Menus\fR -You create a torn-off menu by invoking the tear-off entry at -the top of an existing menu. The default bindings will create a new menu -that is a copy of the original menu and leave it permanently -posted as a top-level window. The torn-off menu behaves just -the same as the original menu. - -.SH "DEFAULT BINDINGS" -.PP -Tk automatically creates class bindings for menus that give them -the following default behavior: -.IP [1] -When the mouse enters a menu, the entry underneath the mouse -cursor activates; as the mouse moves around the menu, the active -entry changes to track the mouse. -.IP [2] -When the mouse leaves a menu all of the entries in the menu -deactivate, except in the special case where the mouse moves from -a menu to a cascaded submenu. -.IP [3] -When a button is released over a menu, the active entry (if any) is invoked. -The menu also unposts unless it is a torn-off menu. -.IP [4] -The Space and Return keys invoke the active entry and -unpost the menu. -.IP [5] -If any of the entries in a menu have letters underlined with -with \fB\-underline\fR option, then pressing one of the underlined -letters (or its upper-case or lower-case equivalent) invokes that -entry and unposts the menu. -.IP [6] -The Escape key aborts a menu selection in progress without invoking any -entry. It also unposts the menu unless it is a torn-off menu. -.IP [7] -The Up and Down keys activate the next higher or lower entry -in the menu. When one end of the menu is reached, the active -entry wraps around to the other end. -.IP [8] -The Left key moves to the next menu to the left. -If the current menu is a cascaded submenu, then the submenu is -unposted and the current menu entry becomes the cascade entry -in the parent. -If the current menu is a top-level menu posted from a -menubutton, then the current menubutton is unposted and the -next menubutton to the left is posted. -Otherwise the key has no effect. -The left-right order of menubuttons is determined by their stacking -order: Tk assumes that the lowest menubutton (which by default -is the first one created) is on the left. -.IP [9] -The Right key moves to the next menu to the right. -If the current entry is a cascade entry, then the submenu is -posted and the current menu entry becomes the first entry -in the submenu. -Otherwise, if the current menu was posted from a -menubutton, then the current menubutton is unposted and the -next menubutton to the right is posted. -.PP -Disabled menu entries are non-responsive: they don't activate and -they ignore mouse button presses and releases. -.PP -.VS 8.4 -Several of the bindings make use of the command \fBtk_menuSetFocus\fR. -It saves the current focus and sets the focus to its \fIpathName\fR -argument, which is a menu widget. -.VE -.PP -The behavior of menus can be changed by defining new bindings for -individual widgets or by redefining the class bindings. - -.SH BUGS -.PP -At present it isn't possible to use the -option database to specify values for the options to individual -entries. - -.SH KEYWORDS -menu, widget diff --git a/tcl/doc/menubar.n b/tcl/doc/menubar.n deleted file mode 100644 index 59fc252860..0000000000 --- a/tcl/doc/menubar.n +++ /dev/null @@ -1,33 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH tk_menuBar n "" Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -tk_menuBar, tk_bindForTraversal \- Obsolete support for menu bars -.SH SYNOPSIS -\fBtk_menuBar \fIframe \fR?\fImenu menu ...\fR? -.sp -\fBtk_bindForTraversal \fIarg arg ... \fR -.BE - -.SH DESCRIPTION -.PP -These procedures were used in Tk 3.6 and earlier releases to help -manage pulldown menus and to implement keyboard traversal of menus. -In Tk 4.0 and later releases they are no -longer needed. Stubs for these procedures have been retained for -backward compatibility, but they have no effect. You should remove -calls to these procedures from your code, since eventually the -procedures will go away. - -.SH KEYWORDS -keyboard traversal, menu, menu bar, post diff --git a/tcl/doc/menubutton.n b/tcl/doc/menubutton.n deleted file mode 100644 index c0cb46625c..0000000000 --- a/tcl/doc/menubutton.n +++ /dev/null @@ -1,203 +0,0 @@ -'\" -'\" Copyright (c) 1990-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$ -'\" -.so man.macros -.TH menubutton n 4.0 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -menubutton \- Create and manipulate menubutton widgets -.SH SYNOPSIS -\fBmenubutton\fR \fIpathName \fR?\fIoptions\fR? -.SO -\-activebackground \-font \-pady -\-activeforeground \-foreground \-relief -\-anchor \-highlightbackground \-takefocus -\-background \-highlightcolor \-text -\-bitmap \-highlightthickness \-textvariable -\-borderwidth \-image \-underline -\-cursor \-justify \-wraplength -\-disabledforeground \-padx -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-compound compound Compound -Specifies whether the menubutton should display both an image and text, -and if so, where the image should be placed relative to the text. -Valid values for this option are \fBbottom\fR, \fBcenter\fR, -\fBleft\fR, \fBnone\fR, \fBright\fR and \fBtop\fR. The default value -is \fBnone\fR, meaning that the menubutton will display either an image or -text, depending on the values of the \fB\-image\fR and \fB\-bitmap\fR -options. -.VS -.OP \-direction direction Height -Specifies where the menu is going to be popup up. \fBabove\fR tries to -pop the menu above the menubutton. \fBbelow\fR tries to pop the menu -below the menubutton. \fBleft\fR tries to pop the menu to the left of -the menubutton. \fBright\fR tries to pop the menu to the right of the -menu button. \fBflush\fR pops the menu directly over the menubutton. -.VE -.OP \-height height Height -Specifies a desired height for the menubutton. -If an image or bitmap is being displayed in the menubutton then the value is in -screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR); -for text it is in lines of text. -If this option isn't specified, the menubutton's desired height is computed -from the size of the image or bitmap or text being displayed in it. -.OP \-indicatoron indicatorOn IndicatorOn -The value must be a proper boolean value. If it is true then -a small indicator rectangle will be displayed on the right side -of the menubutton and the default menu bindings will treat this -as an option menubutton. If false then no indicator will be -displayed. -.OP \-menu menu MenuName -Specifies the path name of the menu associated with this menubutton. -The menu must be a child of the menubutton. -.OP \-state state State -Specifies one of three states for the menubutton: \fBnormal\fR, \fBactive\fR, -or \fBdisabled\fR. In normal state the menubutton is displayed using the -\fBforeground\fR and \fBbackground\fR options. The active state is -typically used when the pointer is over the menubutton. In active state -the menubutton is displayed using the \fBactiveForeground\fR and -\fBactiveBackground\fR options. Disabled state means that the menubutton -should be insensitive: the default bindings will refuse to activate -the widget and will ignore mouse button presses. -In this state the \fBdisabledForeground\fR and -\fBbackground\fR options determine how the button is displayed. -.OP \-width width Width -Specifies a desired width for the menubutton. -If an image or bitmap is being displayed in the menubutton then the value is in -screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR); -for text it is in characters. -If this option isn't specified, the menubutton's desired width is computed -from the size of the image or bitmap or text being displayed in it. -.BE - -.SH INTRODUCTION -.PP -The \fBmenubutton\fR command creates a new window (given by the -\fIpathName\fR argument) and makes it into a menubutton widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the menubutton such as its colors, font, -text, and initial relief. The \fBmenubutton\fR command returns its -\fIpathName\fR argument. At the time this command is invoked, -there must not exist a window named \fIpathName\fR, but -\fIpathName\fR's parent must exist. -.PP -A menubutton is a widget that displays a textual string, bitmap, or image -and is associated with a menu widget. -If text is displayed, it must all be in a single font, but it -can occupy multiple lines on the screen (if it contains newlines -or if wrapping occurs because of the \fBwrapLength\fR option) and -one of the characters may optionally be underlined using the -\fBunderline\fR option. In normal usage, pressing -mouse button 1 over the menubutton causes the associated menu to -be posted just underneath the menubutton. If the mouse is moved over -the menu before releasing the mouse button, the button release -causes the underlying menu entry to be invoked. When the button -is released, the menu is unposted. -.PP -Menubuttons are typically organized into groups called menu bars -that allow scanning: -if the mouse button is pressed over one menubutton (causing it -to post its menu) and the mouse is moved over another menubutton -in the same menu bar without releasing the mouse button, then the -menu of the first menubutton is unposted and the menu of the -new menubutton is posted instead. -.PP -There are several interactions between menubuttons and menus; see -the \fBmenu\fR manual entry for information on various menu configurations, -such as pulldown menus and option menus. - -.SH "WIDGET COMMAND" -.PP -The \fBmenubutton\fR command creates a new Tcl command whose -name is \fIpathName\fR. This -command may be used to invoke various -operations on the widget. It has the following general form: -.CS -\fIpathName option \fR?\fIarg arg ...\fR? -.CE -\fIOption\fR and the \fIarg\fRs -determine the exact behavior of the command. The following -commands are possible for menubutton widgets: -.TP -\fIpathName \fBcget\fR \fIoption\fR -Returns the current value of the configuration option given -by \fIoption\fR. -\fIOption\fR may have any of the values accepted by the \fBmenubutton\fR -command. -.TP -\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -Query or modify the configuration options of the widget. -If no \fIoption\fR is specified, returns a list describing all of -the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for -information on the format of this list). If \fIoption\fR is specified -with no \fIvalue\fR, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no \fIoption\fR is specified). If -one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given widget option(s) to have the given value(s); in -this case the command returns an empty string. -\fIOption\fR may have any of the values accepted by the \fBmenubutton\fR -command. - -.SH "DEFAULT BINDINGS" -.PP -Tk automatically creates class bindings for menubuttons that give them -the following default behavior: -.IP [1] -A menubutton activates whenever the mouse passes over it and deactivates -whenever the mouse leaves it. -.IP [2] -Pressing mouse button 1 over a menubutton posts the menubutton: -its relief changes to raised and its associated menu is posted -under the menubutton. If the mouse is dragged down into the menu -with the button still down, and if the mouse button is then -released over an entry in the menu, the menubutton is unposted -and the menu entry is invoked. -.IP [3] -If button 1 is pressed over a menubutton and then released over that -menubutton, the menubutton stays posted: you can still move the mouse -over the menu and click button 1 on an entry to invoke it. -Once a menu entry has been invoked, the menubutton unposts itself. -.IP [4] -If button 1 is pressed over a menubutton and then dragged over some -other menubutton, the original menubutton unposts itself and the -new menubutton posts. -.IP [5] -If button 1 is pressed over a menubutton and released outside -any menubutton or menu, the menubutton unposts without invoking -any menu entry. -.IP [6] -When a menubutton is posted, its associated menu claims the input -focus to allow keyboard traversal of the menu and its submenus. -See the \fBmenu\fR manual entry for details on these bindings. -.IP [7] -If the \fBunderline\fR option has been specified for a menubutton -then keyboard traversal may be used to post the menubutton: -Alt+\fIx\fR, where \fIx\fR is the underlined character (or its -lower-case or upper-case equivalent), may be typed in any window -under the menubutton's toplevel to post the menubutton. -.IP [8] -The F10 key may be typed in any window to post the first menubutton -under its toplevel window that isn't disabled. -.IP [9] -If a menubutton has the input focus, the space and return keys -post the menubutton. -.PP -If the menubutton's state is \fBdisabled\fR then none of the above -actions occur: the menubutton is completely non-responsive. -.PP -The behavior of menubuttons can be changed by defining new bindings for -individual widgets or by redefining the class bindings. - -.SH KEYWORDS -menubutton, widget diff --git a/tcl/doc/message.n b/tcl/doc/message.n deleted file mode 100644 index dedbf7e899..0000000000 --- a/tcl/doc/message.n +++ /dev/null @@ -1,149 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH message n 4.0 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -message \- Create and manipulate message widgets -.SH SYNOPSIS -\fBmessage\fR \fIpathName \fR?\fIoptions\fR? -.SO -\-anchor \-highlightbackground \-takefocus -\-background \-highlightcolor \-text -\-borderwidth \-highlightthickness \-textvariable -\-cursor \-padx \-width -\-font \-pady -\-foreground \-relief -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-aspect aspect Aspect -Specifies a non-negative integer value indicating desired -aspect ratio for the text. The aspect ratio is specified as -100*width/height. 100 means the text should -be as wide as it is tall, 200 means the text should -be twice as wide as it is tall, 50 means the text should -be twice as tall as it is wide, and so on. -Used to choose line length for text if \fBwidth\fR option -isn't specified. -Defaults to 150. -.OP \-justify justify Justify -Specifies how to justify lines of text. -Must be one of \fBleft\fR, \fBcenter\fR, or \fBright\fR. Defaults -to \fBleft\fR. -This option works together with the \fBanchor\fR, \fBaspect\fR, -\fBpadX\fR, \fBpadY\fR, and \fBwidth\fR options to provide a variety -of arrangements of the text within the window. -The \fBaspect\fR and \fBwidth\fR options determine the amount of -screen space needed to display the text. -The \fBanchor\fR, \fBpadX\fR, and \fBpadY\fR options determine where this -rectangular area is displayed within the widget's window, and the -\fBjustify\fR option determines how each line is displayed within that -rectangular region. -For example, suppose \fBanchor\fR is \fBe\fR and \fBjustify\fR is -\fBleft\fR, and that the message window is much larger than needed -for the text. -The the text will displayed so that the left edges of all the lines -line up and the right edge of the longest line is \fBpadX\fR from -the right side of the window; the entire text block will be centered -in the vertical span of the window. -.OP \-width width Width -Specifies the length of lines in the window. -The value may have any of the forms acceptable to \fBTk_GetPixels\fR. -If this option has a value greater than zero then the \fBaspect\fR -option is ignored and the \fBwidth\fR option determines the line -length. -If this option has a value less than or equal to zero, then -the \fBaspect\fR option determines the line length. -.BE - -.SH DESCRIPTION -.PP -The \fBmessage\fR command creates a new window (given by the -\fIpathName\fR argument) and makes it into a message widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the message such as its colors, font, -text, and initial relief. The \fBmessage\fR command returns its -\fIpathName\fR argument. At the time this command is invoked, -there must not exist a window named \fIpathName\fR, but -\fIpathName\fR's parent must exist. -.PP -A message is a widget that displays a textual string. A message -widget has three special features. First, it breaks up -its string into lines in order to produce a given aspect ratio -for the window. The line breaks are chosen at word boundaries -wherever possible (if not even a single word would fit on a -line, then the word will be split across lines). Newline characters -in the string will force line breaks; they can be used, for example, -to leave blank lines in the display. -.PP -The second feature of a message widget is justification. The text -may be displayed left-justified (each line starts at the left side of -the window), centered on a line-by-line basis, or right-justified -(each line ends at the right side of the window). -.PP -The third feature of a message widget is that it handles control -characters and non-printing characters specially. Tab characters -are replaced with enough blank space to line up on the next -8-character boundary. Newlines cause line breaks. Other control -characters (ASCII code less than 0x20) and characters not defined -in the font are displayed as a four-character sequence \fB\ex\fIhh\fR where -\fIhh\fR is the two-digit hexadecimal number corresponding to -the character. In the unusual case where the font doesn't contain -all of the characters in ``0123456789abcdef\ex'' then control -characters and undefined characters are not displayed at all. - -.SH "WIDGET COMMAND" -.PP -The \fBmessage\fR command creates a new Tcl command whose -name is \fIpathName\fR. This -command may be used to invoke various -operations on the widget. It has the following general form: -.CS -\fIpathName option \fR?\fIarg arg ...\fR? -.CE -\fIOption\fR and the \fIarg\fRs -determine the exact behavior of the command. The following -commands are possible for message widgets: -.TP -\fIpathName \fBcget\fR \fIoption\fR -Returns the current value of the configuration option given -by \fIoption\fR. -\fIOption\fR may have any of the values accepted by the \fBmessage\fR -command. -.TP -\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -Query or modify the configuration options of the widget. -If no \fIoption\fR is specified, returns a list describing all of -the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for -information on the format of this list). If \fIoption\fR is specified -with no \fIvalue\fR, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no \fIoption\fR is specified). If -one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given widget option(s) to have the given value(s); in -this case the command returns an empty string. -\fIOption\fR may have any of the values accepted by the \fBmessage\fR -command. - -.SH "DEFAULT BINDINGS" -.PP -When a new message is created, it has no default event bindings: -messages are intended for output purposes only. - -.SH BUGS -.PP -Tabs don't work very well with text that is centered or right-justified. -The most common result is that the line is justified wrong. - -.SH KEYWORDS -message, widget diff --git a/tcl/doc/messageBox.n b/tcl/doc/messageBox.n deleted file mode 100644 index e06ee51454..0000000000 --- a/tcl/doc/messageBox.n +++ /dev/null @@ -1,89 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH tk_messageBox n 4.2 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -tk_messageBox \- pops up a message window and waits for user response. -.SH SYNOPSIS -\fBtk_messageBox \fR?\fIoption value ...\fR? -.BE - -.SH DESCRIPTION -.PP -This procedure creates and displays a message window with an -application-specified message, an icon and a set of buttons. Each of -the buttons in the message window is identified by a unique symbolic -name (see the \fB\-type\fR options). After the message window is -popped up, \fBtk_messageBox\fR waits for the user to select one of the -buttons. Then it returns the symbolic name of the selected button. - -The following option-value pairs are supported: -.TP -\fB\-default\fR \fIname\fR -\fIName\fR gives the symbolic name of the default button for -this message window ('ok', 'cancel', and so on). See \fB\-type\fR -for a list of the symbolic names. If this option is not specified, -the first button in the dialog will be made the default. -.TP -\fB\-icon\fR \fIiconImage\fR -Specifies an icon to display. \fIIconImage\fR must be one of the -following: \fBerror\fR, \fBinfo\fR, \fBquestion\fR or -\fBwarning\fR. If this option is not specified, then the info icon will be -displayed. -.TP -\fB\-message\fR \fIstring\fR -Specifies the message to display in this message box. -.TP -\fB\-parent\fR \fIwindow\fR -Makes \fIwindow\fR the logical parent of the message box. The message -box is displayed on top of its parent window. -.TP -\fB\-title\fR \fItitleString\fR -Specifies a string to display as the title of the message box. The -default value is an empty string. -.TP -\fB\-type\fR \fIpredefinedType\fR -Arranges for a predefined set of buttons to be displayed. The -following values are possible for \fIpredefinedType\fR: -.RS -.TP 18 -\fBabortretryignore\fR -Displays three buttons whose symbolic names are \fBabort\fR, -\fBretry\fR and \fBignore\fR. -.TP 18 -\fBok\fR -Displays one button whose symbolic name is \fBok\fR. -.TP 18 -\fBokcancel\fR -Displays two buttons whose symbolic names are \fBok\fR and \fBcancel\fR. -.TP 18 -\fBretrycancel\fR -Displays two buttons whose symbolic names are \fBretry\fR and \fBcancel\fR. -.TP 18 -\fByesno\fR -Displays two buttons whose symbolic names are \fByes\fR and \fBno\fR. -.TP 18 -\fByesnocancel\fR -Displays three buttons whose symbolic names are \fByes\fR, \fBno\fR -and \fBcancel\fR. -.RE -.PP -.SH EXAMPLE -.CS -set answer [tk_messageBox \-message "Really quit?" \-type yesno \-icon question] -switch -- $answer { - yes exit - no {tk_messageBox \-message "I know you like this application!" \-type ok} -} -.CE - -.SH KEYWORDS -message box diff --git a/tcl/doc/option.n b/tcl/doc/option.n deleted file mode 100644 index 8f0dd6ad5d..0000000000 --- a/tcl/doc/option.n +++ /dev/null @@ -1,91 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH option n "" Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -option \- Add/retrieve window options to/from the option database -.SH SYNOPSIS -\fBoption add \fIpattern value \fR?\fIpriority\fR? -.sp -\fBoption clear\fR -.sp -\fBoption get \fIwindow name class\fR -.sp -\fBoption readfile \fIfileName \fR?\fIpriority\fR? -.BE - -.SH DESCRIPTION -.PP -The \fBoption\fR command allows you to add entries to the Tk option -database or to retrieve options from the database. The \fBadd\fR -form of the command adds a new option to the database. -\fIPattern\fR contains -the option being specified, and consists of names and/or classes -separated by asterisks or dots, in the usual X format. \fIValue\fR -contains a text string to associate with \fIpattern\fR; this is the -value that will be returned in calls to \fBTk_GetOption\fR or by -invocations of the \fBoption get\fR command. If \fIpriority\fR -is specified, it indicates the priority level for this option (see -below for legal values); it defaults to \fBinteractive\fR. -This command always returns an empty string. -.PP -The \fBoption clear\fR command clears the option database. Default -options (from the -\fBRESOURCE_MANAGER\fR property or the \fB.Xdefaults\fR -file) will be reloaded automatically the next time an -option is added to the database or removed from it. This command -always returns an empty string. -.PP -The \fBoption get\fR command returns the value of the option -specified for \fIwindow\fR -under \fIname\fR and \fIclass\fR. If several entries in the option -database match \fIwindow\fR, \fIname\fR, and \fIclass\fR, then -the command returns whichever was created with highest -\fIpriority\fR level. If there are several matching -entries at the same priority level, then it returns whichever entry -was most recently entered into the option database. If there are -no matching entries, then the empty string is returned. -.PP -The \fBreadfile\fR form of the command reads \fIfileName\fR, -which should have the standard format for an -X resource database such as \fB.Xdefaults\fR, and adds all the -options specified in that file to the option database. If \fIpriority\fR -is specified, it indicates the priority level at which to enter the -options; \fIpriority\fR defaults to \fBinteractive\fR. -.PP -The \fIpriority\fR arguments to the \fBoption\fR command are -normally specified symbolically using one of the following values: -.TP -\fBwidgetDefault\fR -Level 20. Used for default values hard-coded into widgets. -.TP -\fBstartupFile\fR -Level 40. Used for options specified in application-specific -startup files. -.TP -\fBuserDefault\fR -Level 60. Used for options specified in user-specific defaults -files, such as \fB.Xdefaults\fR, resource databases loaded into -the X server, or user-specific startup files. -.TP -\fBinteractive\fR -Level 80. Used for options specified interactively after the application -starts running. If \fIpriority\fR isn't specified, it defaults to -this level. -.LP -Any of the above keywords may be abbreviated. In addition, priorities -may be specified numerically using integers between 0 and 100, -inclusive. The numeric form is probably a bad idea except for new priority -levels other than the ones given above. - -.SH KEYWORDS -database, option, priority, retrieve diff --git a/tcl/doc/optionMenu.n b/tcl/doc/optionMenu.n deleted file mode 100644 index 9dd7147ed1..0000000000 --- a/tcl/doc/optionMenu.n +++ /dev/null @@ -1,40 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH tk_optionMenu n 4.0 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -tk_optionMenu \- Create an option menubutton and its menu -.SH SYNOPSIS -\fBtk_optionMenu \fIw varName value \fR?\fIvalue value ...\fR? -.BE - -.SH DESCRIPTION -.PP -This procedure creates an option menubutton whose name is \fIw\fR, -plus an associated menu. -Together they allow the user to select one of the values -given by the \fIvalue\fR arguments. -The current value will be stored in the global variable whose -name is given by \fIvarName\fR and it will also be displayed as the label -in the option menubutton. -The user can click on the menubutton to display a menu containing -all of the \fIvalue\fRs and thereby select a new value. -Once a new value is selected, it will be stored in the variable -and appear in the option menubutton. -The current value can also be changed by setting the variable. -.PP -The return value from \fBtk_optionMenu\fR is the name of the menu -associated with \fIw\fR, so that the caller can change its configuration -options or manipulate it in other ways. - -.SH KEYWORDS -option menu diff --git a/tcl/doc/options.n b/tcl/doc/options.n deleted file mode 100644 index 16e9a49edd..0000000000 --- a/tcl/doc/options.n +++ /dev/null @@ -1,333 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH options n 4.4 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -options \- Standard options supported by widgets -.BE - -.SH DESCRIPTION -This manual entry describes the common configuration options supported -by widgets in the Tk toolkit. Every widget does not necessarily support -every option (see the manual entries for individual widgets for a list -of the standard options supported by that widget), but if a widget does -support an option with one of the names listed below, then the option -has exactly the effect described below. -.PP -In the descriptions below, ``Command-Line Name'' refers to the -switch used in class commands and \fBconfigure\fR widget commands to -set this value. For example, if an option's command-line switch is -\fB\-foreground\fR and there exists a widget \fB.a.b.c\fR, then the -command -.CS -\&\fB.a.b.c\0\0configure\0\0\-foreground black\fR -.CE -may be used to specify the value \fBblack\fR for the option in the -the widget \fB.a.b.c\fR. Command-line switches may be abbreviated, -as long as the abbreviation is unambiguous. -``Database Name'' refers to the option's name in the option database (e.g. -in .Xdefaults files). ``Database Class'' refers to the option's class value -in the option database. -.OP \-activebackground activeBackground Foreground -Specifies background color to use when drawing active elements. -An element (a widget or portion of a widget) is active if the -mouse cursor is positioned over the element and pressing a mouse button -will cause some action to occur. -If strict Motif compliance has been requested by setting the -\fBtk_strictMotif\fR variable, this option will normally be -ignored; the normal background color will be used instead. -.VS -For some elements on Windows and Macintosh systems, the active color -will only be used while mouse button 1 is pressed over the element. -.VE -.OP \-activeborderwidth activeBorderWidth BorderWidth -Specifies a non-negative value indicating -the width of the 3-D border drawn around active elements. See above for -definition of active elements. -The value may have any of the forms acceptable to \fBTk_GetPixels\fR. -This option is typically only available in widgets displaying more -than one element at a time (e.g. menus but not buttons). -.OP \-activeforeground activeForeground Background -Specifies foreground color to use when drawing active elements. -See above for definition of active elements. -.OP \-anchor anchor Anchor -Specifies how the information in a widget (e.g. text or a bitmap) -is to be displayed in the widget. -Must be one of the values \fBn\fR, \fBne\fR, \fBe\fR, \fBse\fR, -\fBs\fR, \fBsw\fR, \fBw\fR, \fBnw\fR, or \fBcenter\fR. -For example, \fBnw\fR means display the information such that its -top-left corner is at the top-left corner of the widget. -.OP "\-background or \-bg" background Background -Specifies the normal background color to use when displaying the -widget. -.OP \-bitmap bitmap Bitmap -Specifies a bitmap to display in the widget, in any of the forms -acceptable to \fBTk_GetBitmap\fR. -The exact way in which the bitmap is displayed may be affected by -other options such as \fBanchor\fR or \fBjustify\fR. -Typically, if this option is specified then it overrides other -options that specify a textual value to display in the widget; -the \fBbitmap\fR option may be reset to an empty string to re-enable -a text display. -In widgets that support both \fBbitmap\fR and \fBimage\fR options, -\fBimage\fR will usually override \fBbitmap\fR. -.OP "\-borderwidth or \-bd" borderWidth BorderWidth -Specifies a non-negative value indicating the width -of the 3-D border to draw around the outside of the widget (if such a -border is being drawn; the \fBrelief\fR option typically determines -this). The value may also be used when drawing 3-D effects in the -interior of the widget. -The value may have any of the forms acceptable to \fBTk_GetPixels\fR. -.OP \-cursor cursor Cursor -Specifies the mouse cursor to be used for the widget. -The value may have any of the forms acceptable to \fBTk_GetCursor\fR. -.OP \-disabledforeground disabledForeground DisabledForeground -Specifies foreground color to use when drawing a disabled element. -If the option is specified as an empty string (which is typically the -case on monochrome displays), disabled elements are drawn with the -normal foreground color but they are dimmed by drawing them -with a stippled fill pattern. -.OP \-exportselection exportSelection ExportSelection -Specifies whether or not a selection in the widget should also be -the X selection. -The value may have any of the forms accepted by \fBTcl_GetBoolean\fR, -such as \fBtrue\fR, \fBfalse\fR, \fB0\fR, \fB1\fR, \fByes\fR, or \fBno\fR. -If the selection is exported, then selecting in the widget deselects -the current X selection, selecting outside the widget deselects any -widget selection, and the widget will respond to selection retrieval -requests when it has a selection. The default is usually for widgets -to export selections. -.OP \-font font Font -Specifies the font to use when drawing text inside the widget. -The value may have any of the forms accepted by \fBTk_GetFont\fR. -.OP "\-foreground or \-fg" foreground Foreground -Specifies the normal foreground color to use when displaying the widget. -.OP \-highlightbackground highlightBackground HighlightBackground -Specifies the color to display in the traversal highlight region when -the widget does not have the input focus. -.OP \-highlightcolor highlightColor HighlightColor -Specifies the color to use for the traversal highlight rectangle that is -drawn around the widget when it has the input focus. -.OP \-highlightthickness highlightThickness HighlightThickness -Specifies a non-negative value indicating the width of the highlight -rectangle to draw around the outside of the widget when it has the -input focus. -The value may have any of the forms acceptable to \fBTk_GetPixels\fR. -If the value is zero, no focus highlight is drawn around the widget. -.OP \-image image Image -Specifies an image to display in the widget, which must have been -created with the \fBimage create\fR command. -Typically, if the \fBimage\fR option is specified then it overrides other -options that specify a bitmap or textual value to display in the widget; -the \fBimage\fR option may be reset to an empty string to re-enable -a bitmap or text display. -.OP \-insertbackground insertBackground Foreground -Specifies the color to use as background in the area covered by the -insertion cursor. This color will normally override either the normal -background for the widget (or the selection background if the insertion -cursor happens to fall in the selection). -.OP \-insertborderwidth insertBorderWidth BorderWidth -Specifies a non-negative value indicating the width -of the 3-D border to draw around the insertion cursor. -The value may have any of the forms acceptable to \fBTk_GetPixels\fR. -.OP \-insertofftime insertOffTime OffTime -Specifies a non-negative integer value indicating the number of -milliseconds the insertion cursor should remain ``off'' in each blink cycle. -If this option is zero then the cursor doesn't blink: it is on -all the time. -.OP \-insertontime insertOnTime OnTime -Specifies a non-negative integer value indicating the number of -milliseconds the insertion cursor should remain ``on'' in each blink cycle. -.OP \-insertwidth insertWidth InsertWidth -Specifies a value indicating the total width of the insertion cursor. -The value may have any of the forms acceptable to \fBTk_GetPixels\fR. -If a border has been specified for the insertion -cursor (using the \fBinsertBorderWidth\fR option), the border -will be drawn inside the width specified by the \fBinsertWidth\fR -option. -.OP \-jump jump Jump -For widgets with a slider that can be dragged to adjust a value, -such as scrollbars, this option determines when -notifications are made about changes in the value. -The option's value must be a boolean of the form accepted by -\fBTcl_GetBoolean\fR. -If the value is false, updates are made continuously as the -slider is dragged. -If the value is true, updates are delayed until the mouse button -is released to end the drag; at that point a single notification -is made (the value ``jumps'' rather than changing smoothly). -.OP \-justify justify Justify -When there are multiple lines of text displayed in a widget, this -option determines how the lines line up with each other. -Must be one of \fBleft\fR, \fBcenter\fR, or \fBright\fR. -\fBLeft\fR means that the lines' left edges all line up, \fBcenter\fR -means that the lines' centers are aligned, and \fBright\fR means -that the lines' right edges line up. -.OP \-orient orient Orient -For widgets that can lay themselves out with either a horizontal -or vertical orientation, such as scrollbars, this option specifies -which orientation should be used. Must be either \fBhorizontal\fR -or \fBvertical\fR or an abbreviation of one of these. -.OP \-padx padX Pad -Specifies a non-negative value indicating how much extra space -to request for the widget in the X-direction. -The value may have any of the forms acceptable to \fBTk_GetPixels\fR. -When computing how large a window it needs, the widget will -add this amount to the width it would normally need (as determined -by the width of the things displayed in the widget); if the geometry -manager can satisfy this request, the widget will end up with extra -internal space to the left and/or right of what it displays inside. -Most widgets only use this option for padding text: if they are -displaying a bitmap or image, then they usually ignore padding -options. -.OP \-pady padY Pad -Specifies a non-negative value indicating how much extra space -to request for the widget in the Y-direction. -The value may have any of the forms acceptable to \fBTk_GetPixels\fR. -When computing how large a window it needs, the widget will add -this amount to the height it would normally need (as determined by -the height of the things displayed in the widget); if the geometry -manager can satisfy this request, the widget will end up with extra -internal space above and/or below what it displays inside. -Most widgets only use this option for padding text: if they are -displaying a bitmap or image, then they usually ignore padding -options. -.OP \-relief relief Relief -Specifies the 3-D effect desired for the widget. Acceptable -values are \fBraised\fR, \fBsunken\fR, \fBflat\fR, \fBridge\fR, -\fBsolid\fR, and \fBgroove\fR. -The value -indicates how the interior of the widget should appear relative -to its exterior; for example, \fBraised\fR means the interior of -the widget should appear to protrude from the screen, relative to -the exterior of the widget. -.OP \-repeatdelay repeatDelay RepeatDelay -Specifies the number of milliseconds a button or key must be held -down before it begins to auto-repeat. Used, for example, on the -up- and down-arrows in scrollbars. -.OP \-repeatinterval repeatInterval RepeatInterval -Used in conjunction with \fBrepeatDelay\fR: once auto-repeat -begins, this option determines the number of milliseconds between -auto-repeats. -.OP \-selectbackground selectBackground Foreground -Specifies the background color to use when displaying selected -items. -.OP \-selectborderwidth selectBorderWidth BorderWidth -Specifies a non-negative value indicating the width -of the 3-D border to draw around selected items. -The value may have any of the forms acceptable to \fBTk_GetPixels\fR. -.OP \-selectforeground selectForeground Background -Specifies the foreground color to use when displaying selected -items. -.OP \-setgrid setGrid SetGrid -Specifies a boolean value that determines whether this widget controls the -resizing grid for its top-level window. -This option is typically used in text widgets, where the information -in the widget has a natural size (the size of a character) and it makes -sense for the window's dimensions to be integral numbers of these units. -These natural window sizes form a grid. -If the \fBsetGrid\fR option is set to true then the widget will -communicate with the window manager so that when the user interactively -resizes the top-level window that contains the widget, the dimensions of -the window will be displayed to the user in grid units and the window -size will be constrained to integral numbers of grid units. -See the section GRIDDED GEOMETRY MANAGEMENT in the \fBwm\fR manual -entry for more details. -.OP \-takefocus takeFocus TakeFocus -Determines whether the window accepts the focus during keyboard -traversal (e.g., Tab and Shift-Tab). -Before setting the focus to a window, the traversal scripts -consult the value of the \fBtakeFocus\fR option. -A value of \fB0\fR means that the window should be skipped entirely -during keyboard traversal. -\fB1\fR means that the window should receive the input -focus as long as it is viewable (it and all of its ancestors are mapped). -An empty value for the option means that the traversal scripts make -the decision about whether or not to focus on the window: the current -algorithm is to skip the window if it is -disabled, if it has no key bindings, or if it is not viewable. -If the value has any other form, then the traversal scripts take -the value, append the name of the window to it (with a separator space), -and evaluate the resulting string as a Tcl script. -The script must return \fB0\fR, \fB1\fR, or an empty string: a -\fB0\fR or \fB1\fR value specifies whether the window will receive -the input focus, and an empty string results in the default decision -described above. -Note: this interpretation of the option is defined entirely by -the Tcl scripts that implement traversal: the widget implementations -ignore the option entirely, so you can change its meaning if you -redefine the keyboard traversal scripts. -.OP \-text text Text -Specifies a string to be displayed inside the widget. The way in which -the string is displayed depends on the particular widget and may be -determined by other options, such as \fBanchor\fR or \fBjustify\fR. -.OP \-textvariable textVariable Variable -Specifies the name of a variable. The value of the variable is a text -string to be displayed inside the widget; if the variable value changes -then the widget will automatically update itself to reflect the new value. -The way in which the string is displayed in the widget depends on the -particular widget and may be determined by other options, such as -\fBanchor\fR or \fBjustify\fR. -.OP \-troughcolor troughColor Background -Specifies the color to use for the rectangular trough areas -in widgets such as scrollbars and scales. This option is ignored for -scrollbars on Windows (native widget doesn't recognize this option). -.OP \-underline underline Underline -Specifies the integer index of a character to underline in the widget. -This option is used by the default bindings to implement keyboard -traversal for menu buttons and menu entries. -0 corresponds to the first character of the text displayed in the -widget, 1 to the next character, and so on. -.OP \-wraplength wrapLength WrapLength -For widgets that can perform word-wrapping, this option specifies -the maximum line length. -Lines that would exceed this length are wrapped onto the next line, -so that no line is longer than the specified length. -The value may be specified in any of the standard forms for -screen distances. -If this value is less than or equal to 0 then no wrapping is done: lines -will break only at newline characters in the text. -.OP \-xscrollcommand xScrollCommand ScrollCommand -Specifies the prefix for a command used to communicate with horizontal -scrollbars. -When the view in the widget's window changes (or -whenever anything else occurs that could change the display in a -scrollbar, such as a change in the total size of the widget's -contents), the widget will -generate a Tcl command by concatenating the scroll command and -two numbers. -Each of the numbers is a fraction between 0 and 1, which indicates -a position in the document. 0 indicates the beginning of the document, -1 indicates the end, .333 indicates a position one third the way through -the document, and so on. -The first fraction indicates the first information in the document -that is visible in the window, and the second fraction indicates -the information just after the last portion that is visible. -The command is -then passed to the Tcl interpreter for execution. Typically the -\fBxScrollCommand\fR option consists of the path name of a scrollbar -widget followed by ``set'', e.g. ``.x.scrollbar set'': this will cause -the scrollbar to be updated whenever the view in the window changes. -If this option is not specified, then no command will be executed. -.OP \-yscrollcommand yScrollCommand ScrollCommand -Specifies the prefix for a command used to communicate with vertical -scrollbars. This option is treated in the same way as the -\fBxScrollCommand\fR option, except that it is used for vertical -scrollbars and is provided by widgets that support vertical scrolling. -See the description of \fBxScrollCommand\fR for details -on how this option is used. - -.SH "SEE ALSO" -colors, cursors, font - -.SH KEYWORDS -class, name, standard option, switch diff --git a/tcl/doc/pack-old.n b/tcl/doc/pack-old.n deleted file mode 100644 index 902fcc5970..0000000000 --- a/tcl/doc/pack-old.n +++ /dev/null @@ -1,196 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH pack-old n 4.0 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -pack \- Obsolete syntax for packer geometry manager -.SH SYNOPSIS -\fBpack after \fIsibling \fIwindow options\fR ?\fIwindow options \fR...? -.sp -\fBpack append \fIparent \fIwindow options\fR ?\fIwindow options \fR...? -.sp -\fBpack before \fIsibling \fIwindow options\fR ?\fIwindow options \fR...? -.sp -\fBpack unpack \fIwindow\fR -.BE - -.SH DESCRIPTION -.PP -\fINote: this manual entry describes the syntax for the \fBpack\fI -command as it existed before Tk version 3.3. -Although this syntax continues to be supported for backward -compatibility, it is obsolete and should not be used anymore. -At some point in the future it may cease to be supported.\fR -.PP -The packer is a geometry manager that arranges the -children of a parent by packing them in order around the edges of -the parent. The first child is placed against one side of -the window, occupying the entire span of the window along that -side. This reduces the space remaining for other children as -if the side had been moved in by the size of the first child. -Then the next child is placed against one side of the remaining -cavity, and so on until all children have been placed or there -is no space left in the cavity. -.PP -The \fBbefore\fR, \fBafter\fR, and \fBappend\fR forms of the \fBpack\fR -command are used to insert one or more children into the packing order -for their parent. The \fBbefore\fR form inserts the children before -window \fIsibling\fR in the order; all of the other windows must be -siblings of \fIsibling\fR. The \fBafter\fR form inserts the windows -after \fIsibling\fR, and the \fBappend\fR form appends one or more -windows to the end of the packing order for \fIparent\fR. If a -\fIwindow\fR named in any of these commands is already packed in -its parent, it is removed from its current position in the packing -order and repositioned as indicated by the command. All of these -commands return an empty string as result. -.PP -The \fBunpack\fR form of the \fBpack\fR command removes \fIwindow\fR -from the packing order of its parent and unmaps it. After the -execution of this command the packer will no longer manage -\fIwindow\fR's geometry. -.PP -The placement of each child is actually a four-step process; -the \fIoptions\fR argument following each \fIwindow\fR consists of -a list of one or more fields that govern the placement of that -window. In the discussion below, the term \fIcavity\fR refers -to the space left in a parent when a particular child is placed -(i.e. all the space that wasn't claimed by earlier children in -the packing order). The term \fIparcel\fR refers to the space -allocated to a particular child; this is not necessarily the -same as the child window's final geometry. -.PP -The first step in placing a child is to determine which side of -the cavity it will lie against. Any one of the following options -may be used to specify a side: -.TP -\fBtop\fR -Position the child's parcel against the top of the cavity, -occupying the full width of the cavity. -.TP -\fBbottom\fR -Position the child's parcel against the bottom of the cavity, -occupying the full width of the cavity. -.TP -\fBleft\fR -Position the child's parcel against the left side of the cavity, -occupying the full height of the cavity. -.TP -\fBright\fR -Position the child's parcel against the right side of the cavity, -occupying the full height of the cavity. -.LP -At most one of these options should be specified for any given window. -If no side is specified, then the default is \fBtop\fR. -.PP -The second step is to decide on a parcel for the child. For \fBtop\fR -and \fBbottom\fR windows, the desired parcel width is normally the cavity -width and the desired parcel height is the window's requested height, -as passed to \fBTk_GeometryRequest\fR. For \fBleft\fR and \fBright\fR -windows, the desired parcel height is normally the cavity height and the -desired width is the window's requested width. However, extra -space may be requested for the window using any of the following -options: -.TP 12 -\fBpadx \fInum\fR -Add \fInum\fR pixels to the window's requested width before computing -the parcel size as described above. -.TP 12 -\fBpady \fInum\fR -Add \fInum\fR pixels to the window's requested height before computing -the parcel size as described above. -.TP 12 -\fBexpand\fR -This option requests that the window's parcel absorb any extra space left over -in the parent's cavity after packing all the children. -The amount of space left over depends on the sizes requested by the -other children, and may be zero. If several windows have all specified -\fBexpand\fR then the extra width will be divided equally among all the -\fBleft\fR and \fBright\fR windows that specified \fBexpand\fR and -the extra height will be divided equally among all the \fBtop\fR and -\fBbottom\fR windows that specified \fBexpand\fR. -.LP -If the desired width or height for a parcel is larger than the corresponding -dimension of the cavity, then the cavity's dimension is used instead. -.PP -The third step in placing the window is to decide on the window's -width and height. The default is for the window to receive either -its requested width and height or the those of the parcel, whichever -is smaller. If the parcel is larger than the window's requested -size, then the following options may be used to expand the -window to partially or completely fill the parcel: -.TP -\fBfill\fR -Set the window's size to equal the parcel size. -.TP -\fBfillx\fR -Increase the window's width to equal the parcel's width, but retain -the window's requested height. -.TP -\fBfilly\fR -Increase the window's height to equal the parcel's height, but retain -the window's requested width. -.PP -The last step is to decide the window's location within its parcel. -If the window's size equals the parcel's size, then the window simply -fills the entire parcel. If the parcel is larger than the window, -then one of -the following options may be used to specify where the window should -be positioned within its parcel: -.TP 15 -\fBframe center\fR -Center the window in its parcel. This is the default if no framing -option is specified. -.TP 15 -\fBframe n\fR -Position the window with its top edge centered on the top edge of -the parcel. -.TP 15 -\fBframe ne\fR -Position the window with its upper-right corner at the upper-right corner -of the parcel. -.TP 15 -\fBframe e\fR -Position the window with its right edge centered on the right edge of -the parcel. -.TP 15 -\fBframe se\fR -Position the window with its lower-right corner at the lower-right corner -of the parcel. -.TP 15 -\fBframe s\fR -Position the window with its bottom edge centered on the bottom edge of -the parcel. -.TP 15 -\fBframe sw\fR -Position the window with its lower-left corner at the lower-left corner -of the parcel. -.TP 15 -\fBframe w\fR -Position the window with its left edge centered on the left edge of -the parcel. -.TP 15 -\fBframe nw\fR -Position the window with its upper-left corner at the upper-left corner -of the parcel. -.PP -The packer manages the mapped/unmapped state of all the packed -children windows. It automatically maps the windows when it packs -them, and it unmaps any windows for which there was no space left -in the cavity. -.PP -The packer makes geometry requests on behalf of the parent windows -it manages. For each parent window it requests a size large enough -to accommodate all the options specified by all the packed children, -such that zero space would be leftover for \fBexpand\fR options. - -.SH KEYWORDS -geometry manager, location, packer, parcel, size diff --git a/tcl/doc/pack.n b/tcl/doc/pack.n deleted file mode 100644 index 2ece2c9295..0000000000 --- a/tcl/doc/pack.n +++ /dev/null @@ -1,268 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH pack n 4.0 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -pack \- Geometry manager that packs around edges of cavity -.SH SYNOPSIS -\fBpack \fIoption arg \fR?\fIarg ...\fR? -.BE - -.SH DESCRIPTION -.PP -The \fBpack\fR command is used to communicate with the packer, -a geometry manager that arranges the children of a parent by -packing them in order around the edges of the parent. -The \fBpack\fR command can have any of several forms, depending -on the \fIoption\fR argument: -.TP -\fBpack \fIslave \fR?\fIslave ...\fR? ?\fIoptions\fR? -If the first argument to \fBpack\fR is a window name (any value -starting with ``.''), then the command is processed in the same -way as \fBpack configure\fR. -.TP -\fBpack configure \fIslave \fR?\fIslave ...\fR? ?\fIoptions\fR? -The arguments consist of the names of one or more slave windows -followed by pairs of arguments that specify how -to manage the slaves. -See ``THE PACKER ALGORITHM'' below for details on how the options -are used by the packer. -The following options are supported: -.RS -.TP -\fB\-after \fIother\fR -\fIOther\fR must the name of another window. -Use its master as the master for the slaves, and insert -the slaves just after \fIother\fR in the packing order. -.TP -\fB\-anchor \fIanchor\fR -\fIAnchor\fR must be a valid anchor position such as \fBn\fR -or \fBsw\fR; it specifies where to position each slave in its -parcel. -Defaults to \fBcenter\fR. -.TP -\fB\-before \fIother\fR -\fIOther\fR must the name of another window. -Use its master as the master for the slaves, and insert -the slaves just before \fIother\fR in the packing order. -.TP -\fB\-expand \fIboolean\fR -Specifies whether the slaves should be expanded to consume -extra space in their master. -\fIBoolean\fR may have any proper boolean value, such as \fB1\fR -or \fBno\fR. -Defaults to 0. -.TP -\fB\-fill \fIstyle\fR -If a slave's parcel is larger than its requested dimensions, this -option may be used to stretch the slave. -\fIStyle\fR must have one of the following values: -.RS -.TP -\fBnone\fR -Give the slave its requested dimensions plus any internal padding -requested with \fB\-ipadx\fR or \fB\-ipady\fR. This is the default. -.TP -\fBx\fR -Stretch the slave horizontally to fill the entire width of its -parcel (except leave external padding as specified by \fB\-padx\fR). -.TP -\fBy\fR -Stretch the slave vertically to fill the entire height of its -parcel (except leave external padding as specified by \fB\-pady\fR). -.TP -\fBboth\fR -Stretch the slave both horizontally and vertically. -.RE -.TP -\fB\-in \fIother\fR -Insert the slave(s) at the end of the packing order for the master -window given by \fIother\fR. -.TP -\fB\-ipadx \fIamount\fR -\fIAmount\fR specifies how much horizontal internal padding to -leave on each side of the slave(s). -\fIAmount\fR must be a valid screen distance, such as \fB2\fR or \fB.5c\fR. -It defaults to 0. -.TP -\fB\-ipady \fIamount\fR -\fIAmount\fR specifies how much vertical internal padding to -leave on each side of the slave(s). -\fIAmount\fR defaults to 0. -.TP -\fB\-padx \fIamount\fR -\fIAmount\fR specifies how much horizontal external padding to -leave on each side of the slave(s). \fIAmount\fR may be a list -of two values to specify padding for left and right separately. -\fIAmount\fR defaults to 0. -.TP -\fB\-pady \fIamount\fR -\fIAmount\fR specifies how much vertical external padding to -leave on each side of the slave(s). \fIAmount\fR may be a list -of two values to specify padding for top and bottom separtely. -\fIAmount\fR defaults to 0. -.TP -\fB\-side \fIside\fR -Specifies which side of the master the slave(s) will be packed against. -Must be \fBleft\fR, \fBright\fR, \fBtop\fR, or \fBbottom\fR. -Defaults to \fBtop\fR. -.LP -If no \fB\-in\fR, \fB\-after\fR or \fB\-before\fR option is specified -then each of the slaves will be inserted at the end of the packing list -for its parent unless it is already managed by the packer (in which -case it will be left where it is). -If one of these options is specified then all the slaves will be -inserted at the specified point. -If any of the slaves are already managed by the geometry manager -then any unspecified options for them retain their previous values rather -than receiving default values. -.RE -.TP -\fBpack forget \fIslave \fR?\fIslave ...\fR? -Removes each of the \fIslave\fRs from the packing order for its -master and unmaps their windows. -The slaves will no longer be managed by the packer. -.TP -\fBpack info \fIslave\fR -Returns a list whose elements are the current configuration state of -the slave given by \fIslave\fR in the same option-value form that -might be specified to \fBpack configure\fR. -The first two elements of the list are ``\fB\-in \fImaster\fR'' where -\fImaster\fR is the slave's master. -.TP -\fBpack propagate \fImaster\fR ?\fIboolean\fR? -If \fIboolean\fR has a true boolean value such as \fB1\fR or \fBon\fR -then propagation is enabled for \fImaster\fR, which must be a window -name (see ``GEOMETRY PROPAGATION'' below). -If \fIboolean\fR has a false boolean value then propagation is -disabled for \fImaster\fR. -In either of these cases an empty string is returned. -If \fIboolean\fR is omitted then the command returns \fB0\fR or -\fB1\fR to indicate whether propagation is currently enabled -for \fImaster\fR. -Propagation is enabled by default. -.TP -\fBpack slaves \fImaster\fR -Returns a list of all of the slaves in the packing order for \fImaster\fR. -The order of the slaves in the list is the same as their order in -the packing order. -If \fImaster\fR has no slaves then an empty string is returned. - -.SH "THE PACKER ALGORITHM" -.PP -For each master the packer maintains an ordered list of slaves -called the \fIpacking list\fR. -The \fB\-in\fR, \fB\-after\fR, and \fB\-before\fR configuration -options are used to specify the master for each slave and the slave's -position in the packing list. -If none of these options is given for a slave then the slave -is added to the end of the packing list for its parent. -.PP -The packer arranges the slaves for a master by scanning the -packing list in order. -At the time it processes each slave, a rectangular area within -the master is still unallocated. -This area is called the \fIcavity\fR; for the first slave it -is the entire area of the master. -.PP -For each slave the packer carries out the following steps: -.IP [1] -The packer allocates a rectangular \fIparcel\fR for the slave -along the side of the cavity given by the slave's \fB\-side\fR option. -If the side is top or bottom then the width of the parcel is -the width of the cavity and its height is the requested height -of the slave plus the \fB\-ipady\fR and \fB\-pady\fR options. -For the left or right side the height of the parcel is -the height of the cavity and the width is the requested width -of the slave plus the \fB\-ipadx\fR and \fB\-padx\fR options. -The parcel may be enlarged further because of the \fB\-expand\fR -option (see ``EXPANSION'' below) -.IP [2] -The packer chooses the dimensions of the slave. -The width will normally be the slave's requested width plus -twice its \fB\-ipadx\fR option and the height will normally be -the slave's requested height plus twice its \fB\-ipady\fR -option. -However, if the \fB\-fill\fR option is \fBx\fR or \fBboth\fR -then the width of the slave is expanded to fill the width of the parcel, -minus twice the \fB\-padx\fR option. -If the \fB\-fill\fR option is \fBy\fR or \fBboth\fR -then the height of the slave is expanded to fill the width of the parcel, -minus twice the \fB\-pady\fR option. -.IP [3] -The packer positions the slave over its parcel. -If the slave is smaller than the parcel then the \fB\-anchor\fR -option determines where in the parcel the slave will be placed. -If \fB\-padx\fR or \fB\-pady\fR is non-zero, then the given -amount of external padding will always be left between the -slave and the edges of the parcel. -.PP -Once a given slave has been packed, the area of its parcel -is subtracted from the cavity, leaving a smaller rectangular -cavity for the next slave. -If a slave doesn't use all of its parcel, the unused space -in the parcel will not be used by subsequent slaves. -If the cavity should become too small to meet the needs of -a slave then the slave will be given whatever space is -left in the cavity. -If the cavity shrinks to zero size, then all remaining slaves -on the packing list will be unmapped from the screen until -the master window becomes large enough to hold them again. - -.SH "EXPANSION" -.PP -If a master window is so large that there will be extra space -left over after all of its slaves have been packed, then the -extra space is distributed uniformly among all of the slaves -for which the \fB\-expand\fR option is set. -Extra horizontal space is distributed among the expandable -slaves whose \fB\-side\fR is \fBleft\fR or \fBright\fR, -and extra vertical space is distributed among the expandable -slaves whose \fB\-side\fR is \fBtop\fR or \fBbottom\fR. - -.SH "GEOMETRY PROPAGATION" -.PP -The packer normally computes how large a master must be to -just exactly meet the needs of its slaves, and it sets the -requested width and height of the master to these dimensions. -This causes geometry information to propagate up through a -window hierarchy to a top-level window so that the entire -sub-tree sizes itself to fit the needs of the leaf windows. -However, the \fBpack propagate\fR command may be used to -turn off propagation for one or more masters. -If propagation is disabled then the packer will not set -the requested width and height of the packer. -This may be useful if, for example, you wish for a master -window to have a fixed size that you specify. - -.SH "RESTRICTIONS ON MASTER WINDOWS" -.PP -The master for each slave must either be the slave's parent -(the default) or a descendant of the slave's parent. -This restriction is necessary to guarantee that the -slave can be placed over any part of its master that is -visible without danger of the slave being clipped by its parent. - -.SH "PACKING ORDER" -.PP -If the master for a slave is not its parent then you must make sure -that the slave is higher in the stacking order than the master. -Otherwise the master will obscure the slave and it will appear as -if the slave hasn't been packed correctly. -The easiest way to make sure the slave is higher than the master is -to create the master window first: the most recently created window -will be highest in the stacking order. -Or, you can use the \fBraise\fR and \fBlower\fR commands to change -the stacking order of either the master or the slave. - -.SH KEYWORDS -geometry manager, location, packer, parcel, propagation, size diff --git a/tcl/doc/palette.n b/tcl/doc/palette.n deleted file mode 100644 index a0a3433e36..0000000000 --- a/tcl/doc/palette.n +++ /dev/null @@ -1,73 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH tk_setPalette n 4.0 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -tk_setPalette, tk_bisque \- Modify the Tk color palette -.SH SYNOPSIS -\fBtk_setPalette \fIbackground\fR -.sp -\fBtk_setPalette \fIname value \fR?\fIname value ...\fR? -.sp -\fBtk_bisque\fR -.BE - -.SH DESCRIPTION -.PP -The \fBtk_setPalette\fR procedure changes the color scheme for Tk. -It does this by modifying the colors of existing widgets and by changing -the option database so that future widgets will use the new color scheme. -If \fBtk_setPalette\fR is invoked with a single argument, the -argument is the name of a color to use as the normal background -color; \fBtk_setPalette\fR will compute a complete color palette -from this background color. -Alternatively, the arguments to \fBtk_setPalette\fR may consist of any number -of \fIname\fR\-\fIvalue\fR pairs, where the first argument of the pair -is the name of an option in the Tk option database and the second -argument is the new value to use for that option. The following -database names are currently supported: -.DS L -.ta 4c 8c -\fBactiveBackground foreground selectColor -activeForeground highlightBackground selectBackground -background highlightColor selectForeground -disabledForeground insertBackground troughColor\fR -.DE -\fBtk_setPalette\fR tries to compute reasonable defaults for any -options that you don't specify. You can specify options other -than the above ones and Tk will change those options on widgets as -well. This feature may be useful if you are using custom widgets with -additional color options. -.PP -Once it has computed the new value to use for each of the color options, -\fBtk_setPalette\fR scans the widget hierarchy to modify the options -of all existing widgets. For each widget, it checks to see if any -of the above options is defined for the widget. If so, and if the -option's current value is the default, then the value is changed; if -the option has a value other than the default, \fBtk_setPalette\fR -will not change it. The default for an option is the one provided by -the widget (\fB[lindex [$w configure $option] 3]\fR) unless -\fBtk_setPalette\fR has been run previously, in which case it is the -value specified in the previous invocation of \fBtk_setPalette\fR. -.PP -After modifying all the widgets in the application, \fBtk_setPalette\fR -adds options to the option database to change the defaults for -widgets created in the future. The new options are added at -priority \fBwidgetDefault\fR, so they will be overridden by options -from the .Xdefaults file or options specified on the command-line -that creates a widget. -.PP -The procedure \fBtk_bisque\fR is provided for backward compatibility: -it restores the application's colors to the light brown (``bisque'') -color scheme used in Tk 3.6 and earlier versions. - -.SH KEYWORDS -bisque, color, palette diff --git a/tcl/doc/panedwindow.n b/tcl/doc/panedwindow.n deleted file mode 100644 index 23edc37b2c..0000000000 --- a/tcl/doc/panedwindow.n +++ /dev/null @@ -1,246 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH panedwindow n 8.4 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -panedwindow \- Create and manipulate panedwindow widgets -.SH SYNOPSIS -\fBpanedwindow\fR \fIpathName \fR?\fIoptions\fR? -.SO -\-background \-height \-width -\-borderwidth \-orient -\-cursor \-relief -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-handlepad handlePad HandlePad -When sash handles are drawn, specifies the distance from the top or -left end of the sash (depending on the orientation of the widget) at -which to draw the handle. May be any value accepted by \fBTk_GetPixels\fR. -.OP \-handlesize handleSize HandleSize -Specifies the side length of a sash handle. Handles are always -drawn as squares. May be any value accepted by \fBTk_GetPixels\fR. -.OP \-opaqueresize opaqueResize OpaqueResize -Specifies whether panes should be resized as a sash is moved (true), -or if resizing should be deferred until the sash is placed (false). -.OP \-sashcursor sashCursor SashCursor -Mouse cursor to use when over a sash. If null, -\fBsb_h_double_arrow\fR will be used for horizontal panedwindows, and -\fBsb_v_double_arrow\fR will be used for vertical panedwindows. -.OP \-sashpad sashPad SashPad -Specifies the amount of padding to leave of each side of a sash. May -be any value accepted by \fBTk_GetPixels\fR. -.OP \-sashrelief sashRelief SashRelief -Relief to use when drawing a sash. May be any of the standard Tk -relief values. -.OP \-sashwidth sashWidth SashWidth -Specifies the width of each sash. May be any value accepted by -\fBTk_GetPixels\fR. -.OP \-showhandle showHandle ShowHandle -Specifies whether sash handles should be shown. May be any valid Tcl -boolean value. -.BE - -.SH DESCRIPTION -.PP -The \fBpanedwindow\fR command creates a new window (given by the -\fIpathName\fR argument) and makes it into a panedwindow widget. -Additional options, described above, may be specified on the command -line or in the option database to configure aspects of the panedwindow -such as its default background color and relief. The -\fBpanedwindow\fR command returns the path name of the new window. -.PP -A panedwindow widget contains any number of panes, arranged -horizontally or vertically, according to the value of the -\fB\-orient\fR option. Each pane contains one widget, and each pair of -panes is separated by a moveable (via mouse movements) sash. Moving a -sash causes the widgets on either side of the sash to be resized. - -.SH "WIDGET COMMAND" -.PP -The \fBpanedwindow\fR command creates a new Tcl command whose name is -the same as the path name of the panedwindow's window. This command -may be used to invoke various operations on the widget. It has the -following general form: -.CS -\fIpathName option \fR?\fIarg arg ...\fR? -.CE -\fIPathName\fR is the name of the command, which is the same as -the panedwindow widget's path name. \fIOption\fR and the \fIarg\fRs -determine the exact behavior of the command. The following -commands are possible for panedwindow widgets: -.TP -\fIpathName \fBadd \fIwindow ?window ...? ?option value ...?\fR -Add one or more windows to the panedwindow, each in a separate pane. -The arguments consist of the names of one or more windows -followed by pairs of arguments that specify how to manage the windows. -\fIOption\fR may have any of the values accepted by the -\fBconfigure\fR subcommand. -.TP -\fIpathName \fBcget \fIoption\fR -Returns the current value of the configuration option given by -\fIoption\fR. \fIOption\fR may have any of the values accepted by the -\fBpanedwindow\fR command. -.TP -\fIpathName \fBconfigure \fI?option? ?value option value ...?\fR -Query or modify the configuration options of the widget. If no -\fIoption\fR is specified, returns a list describing all of the -available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for -information on the format of this list). If \fIoption\fR is specified -with no \fIvalue\fR, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no \fIoption\fR is specified). If -one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given widget option(s) to have the given value(s); in -this case the command returns an empty string. \fIOption\fR may have -any of the values accepted by the \fBpanedwindow\fR command. -.TP -\fIpathName \fBforget \fIwindow ?window ...?\fR -Remove the pane containing \fIwindow\fR from the panedwindow. All -geometry management options for \fIwindow\fR will be forgotten. -.TP -\fIpathName \fBidentify \fIx y\fR -Identify the panedwindow component underneath the point given by -\fIx\fR and \fIy\fR, in window coordinates. If the point is over a -sash or a sash handle, the result is a two element list containing the -index of the sash or handle, and a word indicating whether it is over -a sash or a handle, such as {0 sash} or {2 handle}. If the point is -over any other part of the panedwindow, the result is an empty list. -.TP -\fIpathName \fBproxy \fI?args?\fR -This command is used to query and change the position of the sash -proxy, used for rubberband-style pane resizing. It can take any of -the following forms: -.RS -.TP -\fIpathName \fBproxy coord\fR -Return a list containing the x and y coordinates of the most recent -proxy location. -.TP -\fIpathname \fBproxy forget\fR -Remove the proxy from the display. -.TP -\fIpathName \fBproxy place \fIx y\fR -Place the proxy at the given \fIx\fR and \fIy\fR coordinates. -.RE -.TP -\fIpathName \fBsash \fI?args?\fR -This command is used to query and change the position of sashes in the -panedwindow. It can take any of the following forms: -.RS -.TP -\fIpathName \fBsash coord \fIindex\fR -Return the current x and y coordinate pair for the sash given by -\fIindex\fR. \fIIndex\fR must be an integer between 0 and 1 less than -the number of panes in the panedwindow. The coordinates given are -those of the top left corner of the region containing the sash. -\fIpathName \fBsash dragto \fIindex x y\fR -This command computes the difference between the given coordinates and the -coordinates given to the last \fBsash coord\fR command for the given -sash. It then moves that sash the computed difference. The return -value is the empty string. -.TP -\fIpathName \fBsash mark \fIindex x y\fR -Records \fIx\fR and \fIy\fR for the sash given by \fIindex\fR; used in -conjunction with later dragto commands to move the sash. -.TP -\fIpathName \fBsash place \fIindex x y\fR -Place the sash given by \fIindex\fR at the given coordinates. -.RE -.TP -\fIpathName \fBpanecget \fIwindow option\fR -Query a management option for \fIwindow\fR. \fIOption\fR may be any -value allowed by the \fBpaneconfigure\fR subcommand. -.TP -\fIpathName \fBpaneconfigure \fIwindow ?option? ?value option value ...?\fR -Query or modify the management options for \fIwindow\fR. If no -\fIoption\fR is specified, returns a list describing all of the -available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for -information on the format of this list). If \fIoption\fR is specified -with no \fIvalue\fR, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no \fIoption\fR is specified). If -one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given widget option(s) to have the given value(s); in -this case the command returns an empty string. The following options -are supported: -.RS -.TP -\fB\-after \fIwindow\fR -Insert the window after the window specified. \fIwindow\fR should be the -name of a window already managed by \fIpathName\fR. -.TP -\fB\-before \fIwindow\fR -Insert the window before the window specified. \fIwindow\fR should be -the name of a window already managed by \fIpathName\fR. -.TP -\fB\-height \fIsize\fR -Specify a height for the window. The height will be the outer -dimension of the window including its border, if any. If \fIsize\fR -is an empty string, or if \fB\-height\fR is not specified, then the -height requested internally by the window will be used initially; the -height may later be adjusted by the movement of sashes in the -panedwindow. \fISize\fR may be any value accepted by \fBTk_GetPixels\fR. -.TP -\fB\-minsize \fIn\fR -Specifies that the size of the window cannot be made less than -\fIn\fR. This constraint only affects the size of the widget in the -paned dimension -- the x dimension for horizontal panedwindows, the y -dimension for vertical panedwindows. May be any value accepted by -\fBTk_GetPixels\fR. -.TP -\fB\-padx \fIn\fR -Specifies a non-negative value indicating how much extra space to -leave on each side of the window in the X-direction. The value may -have any of the forms accepted by \fBTk_GetPixels\fR. -.TP -\fB\-pady \fIn\fR -Specifies a non-negative value indicating how much extra space to -leave on each side of the window in the Y-direction. The value may -have any of the forms accepted by \fBTk_GetPixels\fR. -.TP -\fB\-sticky \fIstyle\fR -If a window's pane is larger than the requested dimensions of the -window, this option may be used to position (or stretch) the window -within its pane. \fIStyle\fR is a string that contains zero or more -of the characters \fBn\fP, \fBs\fP, \fBe\fP or \fBw\fP. The string -can optionally contains spaces or commas, but they are ignored. Each -letter refers to a side (north, south, east, or west) that the window -will "stick" to. If both \fBn\fP and \fBs\fP (or \fBe\fP and \fBw\fP) -are specified, the window will be stretched to fill the entire height -(or width) of its cavity. -.TP -\fB\-width \fIsize\fR -Specify a width for the window. The width will be the outer -dimension of the window including its border, if any. If \fIsize\fR -is an empty string, or if \fB\-width\fR is not specified, then the -width requested internally by the window will be used initially; the -width may later be adjusted by the movement of sashes in the -panedwindow. \fISize\fR may be any value accepted by \fBTk_GetPixels\fR. -.RE -.TP -\fIpathName \fBpanes\fR -Returns an ordered list of the widgets managed by \fIpathName\fR. - -.SH "RESIZING PANES" - -A pane is resized by grabbing the sash (or sash handle if present) and -dragging with the mouse. This is accomplished via mouse motion -bindings on the widget. When a sash is moved, the sizes of the panes -on each side of the sash, and thus the widgets in those panes, are -adjusted. -.PP -When a pane is resized from outside (eg, it is packed to expand and -fill, and the containing toplevel is resized), space is added to the final -(rightmost or bottommost) pane in the window. - -.SH KEYWORDS -panedwindow, widget, geometry management diff --git a/tcl/doc/photo.n b/tcl/doc/photo.n deleted file mode 100644 index e66d34e3ed..0000000000 --- a/tcl/doc/photo.n +++ /dev/null @@ -1,443 +0,0 @@ -'\" -'\" Copyright (c) 1994 The Australian National University -'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" Author: Paul Mackerras (paulus@cs.anu.edu.au), -'\" Department of Computer Science, -'\" Australian National University. -'\" -'\" RCS: @(#) $Id$ -'\" -.so man.macros -.TH photo n 4.0 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -photo \- Full-color images -.SH SYNOPSIS -\fBimage create photo \fR?\fIname\fR? ?\fIoptions\fR? -.BE - -.SH DESCRIPTION -.PP -A photo is an image whose pixels can display any color or be -transparent. A photo image is stored internally in full color (32 -bits per pixel), and is displayed using dithering if necessary. Image -data for a photo image can be obtained from a file or a string, or it -can be supplied from -C code through a procedural interface. At present, only GIF and PPM/PGM -formats are supported, but an interface exists to allow additional -image file formats to be added easily. A photo image is transparent -in regions where no image data has been supplied -.VS 8.4 -or where it has been set transparent by the \fBtransparency set\fR -subcommand. -.VE 8.4 - -.SH "CREATING PHOTOS" -.PP -Like all images, photos are created using the \fBimage create\fR -command. -Photos support the following \fIoptions\fR: -.TP -\fB\-data \fIstring\fR -Specifies the contents of the image as a string. The string can -contain base64 encoded data or binary data. The format of the -string must be one of those for which there is an image file format -handler that will accept string data. If both the \fB\-data\fR -and \fB\-file\fR options are specified, the \fB\-file\fR option takes -precedence. -.TP -\fB\-format \fIformat-name\fR -Specifies the name of the file format for the data specified with the -\fB\-data\fR or \fB\-file\fR option. -.TP -\fB\-file \fIname\fR -\fIname\fR gives the name of a file that is to be read to supply data -for the photo image. The file format must be one of those for which -there is an image file format handler that can read data. -.TP -\fB\-gamma \fIvalue\fR -Specifies that the colors allocated for displaying this image in a -window should be corrected for a non-linear display with the specified -gamma exponent value. (The intensity produced by most -CRT displays is a power function of the input value, to a good -approximation; gamma is the exponent and is typically around 2). -The value specified must be greater than zero. The default -value is one (no correction). In general, values greater than one -will make the image lighter, and values less than one will make it -darker. -.TP -\fB\-height \fInumber\fR -Specifies the height of the image, in pixels. This option is useful -primarily in situations where the user wishes to build up the contents -of the image piece by piece. A value of zero (the default) allows the -image to expand or shrink vertically to fit the data stored in it. -.TP -\fB\-palette \fIpalette-spec\fR -Specifies the resolution of the color cube to be allocated for -displaying this image, and thus the number of colors used from the -colormaps of the windows where it is displayed. The -\fIpalette-spec\fR string may be either a single decimal number, -specifying the number of shades of gray to use, or three decimal -numbers separated by slashes (/), specifying the number of shades of -red, green and blue to use, respectively. If the first form (a single -number) is used, the image will be displayed in monochrome (i.e., -grayscale). -.TP -\fB\-width \fInumber\fR -Specifies the width of the image, in pixels. This option is useful -primarily in situations where the user wishes to build up the contents -of the image piece by piece. A value of zero (the default) allows the -image to expand or shrink horizontally to fit the data stored in it. - -.SH "IMAGE COMMAND" -.PP -When a photo image is created, Tk also creates a new command -whose name is the same as the image. -This command may be used to invoke various operations -on the image. -It has the following general form: -.CS -\fIimageName option \fR?\fIarg arg ...\fR? -.CE -\fIOption\fR and the \fIarg\fRs -determine the exact behavior of the command. -.PP -Those options that write data to the image generally expand the size -of the image, if necessary, to accommodate the data written to the -image, unless the user has specified non-zero values for the -\fB\-width\fR and/or \fB\-height\fR configuration options, in which -case the width and/or height, respectively, of the image will not be -changed. -.PP -The following commands are possible for photo images: -.TP -\fIimageName \fBblank\fR -Blank the image; that is, set the entire image to have no data, so it -will be displayed as transparent, and the background of whatever -window it is displayed in will show through. -.TP -\fIimageName \fBcget\fR \fIoption\fR -Returns the current value of the configuration option given -by \fIoption\fR. -\fIOption\fR may have any of the values accepted by the -\fBimage create photo\fR command. -.TP -\fIimageName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -Query or modify the configuration options for the image. -If no \fIoption\fR is specified, returns a list describing all of -the available options for \fIimageName\fR (see \fBTk_ConfigureInfo\fR for -information on the format of this list). If \fIoption\fR is specified -with no \fIvalue\fR, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no \fIoption\fR is specified). If -one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given option(s) to have the given value(s); in -this case the command returns an empty string. -\fIOption\fR may have any of the values accepted by the -\fBimage create photo\fR command. -.TP -\fIimageName \fBcopy\fR \fIsourceImage\fR ?\fIoption value(s) ...\fR? -Copies a region from the image called \fIsourceImage\fR (which must -be a photo image) to the image called \fIimageName\fR, possibly with -pixel zooming and/or subsampling. If no options are specified, this -command copies the whole of \fIsourceImage\fR into \fIimageName\fR, -starting at coordinates (0,0) in \fIimageName\fR. The following -options may be specified: -.RS -.TP -\fB\-from \fIx1 y1 x2 y2\fR -Specifies a rectangular sub-region of the source image to be copied. -(\fIx1,y1\fR) and (\fIx2,y2\fR) specify diagonally opposite corners of -the rectangle. If \fIx2\fR and \fIy2\fR are not specified, the -default value is the bottom-right corner of the source image. The -pixels copied will include the left and top edges of the specified -rectangle but not the bottom or right edges. If the \fB\-from\fR -option is not given, the default is the whole source image. -.TP -\fB\-to \fIx1 y1 x2 y2\fR -Specifies a rectangular sub-region of the destination image to be -affected. (\fIx1,y1\fR) and (\fIx2,y2\fR) specify diagonally opposite -corners of the rectangle. If \fIx2\fR and \fIy2\fR are not specified, -the default value is (\fIx1,y1\fR) plus the size of the source -region (after subsampling and zooming, if specified). If \fIx2\fR and -\fIy2\fR are specified, the source region will be replicated if -necessary to fill the destination region in a tiled fashion. -.TP -\fB\-shrink\fR -Specifies that the size of the destination image should be reduced, if -necessary, so that the region being copied into is at the bottom-right -corner of the image. This option will not affect the width or height -of the image if the user has specified a non-zero value for the -\fB\-width\fR or \fB\-height\fR configuration option, respectively. -.TP -\fB\-zoom \fIx y\fR -Specifies that the source region should be magnified by a factor of -\fIx\fR in the X direction and \fIy\fR in the Y direction. If \fIy\fR -is not given, the default value is the same as \fIx\fR. With this -option, each pixel in the source image will be expanded into a block -of \fIx\fR x \fIy\fR pixels in the destination image, all the same -color. \fIx\fR and \fIy\fR must be greater than 0. -.TP -\fB\-subsample \fIx y\fR -Specifies that the source image should be reduced in size by using -only every \fIx\fRth pixel in the X direction and \fIy\fRth pixel in -the Y direction. Negative values will cause the image to be flipped -about the Y or X axes, respectively. If \fIy\fR is not given, the -default value is the same as \fIx\fR. -.TP -\fB\-compositingrule \fIrule\fR -.VS 8.4 -Specifies how transparent pixels in the source image are combined with -the destination image. When a compositing rule of \fIoverlay\fR is -set, the old contents of the destination image are visible, as if the -source image were printed on a piece of transparent film and placed -over the top of the destination. When a compositing rule of \fIset\fR -is set, the old contents of the destination image are discarded and -the source image is used as-is. The default compositing rule is -\fIoverlay\fR. -.VE 8.4 -.RE -.TP -\fIimageName \fBdata ?\fIoption value(s) ...\fR? -Returns image data in the form of a string. The following options -may be specified: -.RS -.TP -\fB\-background\fI color\fR -If the color is specified, the data will not contain any transparency -information. In all transparent pixels the color will be replaced by -the specified color. -.TP -\fB\-format\fI format-name\fR -Specifies the name of the image file format handler to be used. -Specifically, this subcommand searches -for the first handler whose name matches a initial substring of -\fIformat-name\fR and which has the capability to read this image data. -If this option is not given, this subcommand uses the first -handler that has the capability to read the image data. -.TP -\fB\-from \fIx1 y1 x2 y2\fR -Specifies a rectangular region of \fIimageName\fR to be returned. -If only \fIx1\fR and \fIy1\fR are specified, the region -extends from \fI(x1,y1)\fR to the bottom-right corner of -\fIimageName\fR. If all four coordinates are given, they specify -diagonally opposite corners of the rectangular region, including x1,y1 -and excluding x2,y2. The default, if this option is not given, is the -whole image. -.TP -\fB\-grayscale\fR -If this options is specified, the data will not contain color -information. All pixel data will be transformed into grayscale. -.RE -.TP -\fIimageName \fBget\fR \fIx y\fR -Returns the color of the pixel at coordinates (\fIx\fR,\fIy\fR) in the -image as a list of three integers between 0 and 255, representing the -red, green and blue components respectively. -.TP -\fIimageName \fBput\fR \fIdata\fR ?\fIoption value(s) ...\fR? -Sets pixels in \fI imageName\fR to the data specified in -\fIdata\fR. This command first searches the list of image file -format handlers for a handler that can interpret the data -in \fIdata\fR, and then reads the image in \fIfilename\fR into -\fIimageName\fR (the destination image). The following options -may be specified: -.RS -.TP -\fB\-format \fIformat-name\fR -Specifies the format of the image data in \fIdata\fR. -Specifically, only image file format handlers whose names begin with -\fIformat-name\fR will be used while searching for an image data -format handler to read the data. -.TP -\fB\-from \fIx1 y1 x2 y2\fR -Specifies a rectangular sub-region of the image file data to be -returned. If only \fIx1\fR and \fIy1\fR are specified, the region -extends from (\fIx1,y1\fR) to the bottom-right corner of the image -in the image file. If all four coordinates are specified, they -specify diagonally opposite corners or the region. The default, -if this option is not specified, is the whole of the image. -.TP -\fB\-shrink\fR -If this option, the size of \fIimageName\fR will be reduced, if -necessary, so that the region into which the image file data are read -is at the bottom-right corner of the \fIimageName\fR. This option -will not affect the width or height of the image if the user has -specified a non-zero value for the \fB\-width\fR or \fB\-height\fR -configuration option, respectively. -.TP -\fB\-to \fIx y\fR -Specifies the coordinates of the top-left corner of the region of -\fIimageName\fR into which data from \fIfilename\fR are to be read. -The default is (0,0). -.RE -.TP -\fIimageName \fBread\fR \fIfilename\fR ?\fIoption value(s) ...\fR? -Reads image data from the file named \fIfilename\fR into the image. -This command first searches the list of -image file format handlers for a handler that can interpret the data -in \fIfilename\fR, and then reads the image in \fIfilename\fR into -\fIimageName\fR (the destination image). The following options may be -specified: -.RS -.TP -\fB\-format \fIformat-name\fR -Specifies the format of the image data in \fIfilename\fR. -Specifically, only image file format handlers whose names begin with -\fIformat-name\fR will be used while searching for an image data -format handler to read the data. -.TP -\fB\-from \fIx1 y1 x2 y2\fR -Specifies a rectangular sub-region of the image file data to be copied -to the destination image. If only \fIx1\fR and \fIy1\fR are -specified, the region extends from (\fIx1,y1\fR) to the bottom-right -corner of the image in the image file. If all four coordinates are -specified, they specify diagonally opposite corners or the region. -The default, if this option is not specified, is the whole of the -image in the image file. -.TP -\fB\-shrink\fR -If this option, the size of \fIimageName\fR will be reduced, if -necessary, so that the region into which the image file data are read -is at the bottom-right corner of the \fIimageName\fR. This option -will not affect the width or height of the image if the user has -specified a non-zero value for the \fB\-width\fR or \fB\-height\fR -configuration option, respectively. -.TP -\fB\-to \fIx y\fR -Specifies the coordinates of the top-left corner of the region of -\fIimageName\fR into which data from \fIfilename\fR are to be read. -The default is (0,0). -.RE -.TP -\fIimageName \fBredither\fR -The dithering algorithm used in displaying photo images propagates -quantization errors from one pixel to its neighbors. -If the image data for \fIimageName\fR is supplied in pieces, the -dithered image may not be exactly correct. Normally the difference is -not noticeable, but if it is a problem, this command can be used to -recalculate the dithered image in each window where the image is -displayed. -.TP -\fIimageName \fBtransparency \fIsubcommand ?arg arg ...?\fR -.VS 8.4 -Allows examination and manipulation of the transparency information in -the photo image. Several subcommands are available: -.RS -.TP -\fIimageName \fBtransparency get \fIx y\fR -Returns a boolean indicating if the pixel at (\fIx\fR,\fIy\fR) is -transparent. -\fIimageName \fBtransparency set \fIx y boolean\fR -Makes the pixel at (\fIx\fR,\fIy\fR) transparent if \fIboolean\fR is -true, and makes that pixel opaque otherwise. -.RE -.VE 8.4 -.TP -\fIimageName \fBwrite \fIfilename\fR ?\fIoption value(s) ...\fR? -Writes image data from \fIimageName\fR to a file named \fIfilename\fR. -The following options may be specified: -.RS -.TP -\fB\-background\fI color\fR -If the color is specified, the data will not contain any transparency -information. In all transparent pixels the color will be replaced by -the specified color. -.TP -\fB\-format\fI format-name\fR -Specifies the name of the image file format handler to be used to -write the data to the file. Specifically, this subcommand searches -for the first handler whose name matches a initial substring of -\fIformat-name\fR and which has the capability to write an image -file. If this option is not given, this subcommand uses the first -handler that has the capability to write an image file. -.TP -\fB\-from \fIx1 y1 x2 y2\fR -Specifies a rectangular region of \fIimageName\fR to be written to the -image file. If only \fIx1\fR and \fIy1\fR are specified, the region -extends from \fI(x1,y1)\fR to the bottom-right corner of -\fIimageName\fR. If all four coordinates are given, they specify -diagonally opposite corners of the rectangular region. The default, -if this option is not given, is the whole image. -.TP -\fB\-grayscale\fR -If this options is specified, the data will not contain color -information. All pixel data will be transformed into grayscale. -.RE -.SH "IMAGE FORMATS" -.PP -The photo image code is structured to allow handlers for additional -image file formats to be added easily. The photo image code maintains -a list of these handlers. Handlers are added to the list by -registering them with a call to \fBTk_CreatePhotoImageFormat\fR. The -standard Tk distribution comes with handlers for PPM/PGM and GIF formats, -which are automatically registered on initialization. -.PP -When reading an image file or processing -string data specified with the \fB\-data\fR configuration option, the -photo image code invokes each handler in turn until one is -found that claims to be able to read the data in the file or string. -Usually this will find the correct handler, but if it doesn't, the -user may give a format name with the \fB\-format\fR option to specify -which handler to use. In fact the photo image code will try those -handlers whose names begin with the string specified for the -\fB\-format\fR option (the comparison is case-insensitive). For -example, if the user specifies \fB\-format gif\fR, then a handler -named GIF87 or GIF89 may be invoked, but a handler -named JPEG may not (assuming that such handlers had been -registered). -.PP -When writing image data to a file, the processing of the -\fB\-format\fR option is slightly different: the string value given -for the \fB\-format\fR option must begin with the complete name of the -requested handler, and may contain additional information following -that, which the handler can use, for example, to specify which variant -to use of the formats supported by the handler. -.VS 8.4 -Note that not all image handlers may support writing transparency data -to a file, even where the target image format does. -.VE 8.4 - -.SH "COLOR ALLOCATION" -.PP -When a photo image is displayed in a window, the photo image code -allocates colors to use to display the image and dithers the image, if -necessary, to display a reasonable approximation to the image using -the colors that are available. The colors are allocated as a color -cube, that is, the number of colors allocated is the product of the -number of shades of red, green and blue. -.PP -Normally, the number of -colors allocated is chosen based on the depth of the window. For -example, in an 8-bit PseudoColor window, the photo image code will -attempt to allocate seven shades of red, seven shades of green and -four shades of blue, for a total of 198 colors. In a 1-bit StaticGray -(monochrome) window, it will allocate two colors, black and white. In -a 24-bit DirectColor or TrueColor window, it will allocate 256 shades -each of red, green and blue. Fortunately, because of the way that -pixel values can be combined in DirectColor and TrueColor windows, -this only requires 256 colors to be allocated. If not all of the -colors can be allocated, the photo image code reduces the number of -shades of each primary color and tries again. -.PP -The user can exercise some control over the number of colors that a -photo image uses with the \fB\-palette\fR configuration option. If -this option is used, it specifies the maximum number of shades of -each primary color to try to allocate. It can also be used to force -the image to be displayed in shades of gray, even on a color display, -by giving a single number rather than three numbers separated by -slashes. - -.SH CREDITS -.PP -The photo image type was designed and implemented by Paul Mackerras, -based on his earlier photo widget and some suggestions from -John Ousterhout. - -.SH KEYWORDS -photo, image, color diff --git a/tcl/doc/place.n b/tcl/doc/place.n deleted file mode 100644 index 4c21d72edf..0000000000 --- a/tcl/doc/place.n +++ /dev/null @@ -1,250 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH place n "" Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -place \- Geometry manager for fixed or rubber-sheet placement -.SH SYNOPSIS -\fBplace \fIwindow option value \fR?\fIoption value ...\fR? -.sp -\fBplace configure \fIwindow \fR?\fIoption\fR? ?\fIvalue option value ...\fR? -.sp -\fBplace forget \fIwindow\fR -.sp -\fBplace info \fIwindow\fR -.sp -\fBplace slaves \fIwindow\fR -.BE - -.SH DESCRIPTION -.PP -The placer is a geometry manager for Tk. -It provides simple fixed placement of windows, where you specify -the exact size and location of one window, called the \fIslave\fR, -within another window, called the \fImaster\fR. -The placer also provides rubber-sheet placement, where you specify the -size and location of the slave in terms of the dimensions of -the master, so that the slave changes size and location -in response to changes in the size of the master. -Lastly, the placer allows you to mix these styles of placement so -that, for example, the slave has a fixed width and height but is -centered inside the master. -.PP -.TP -\fBplace \fIwindow option value \fR?\fIoption value ...\fR? -Arrange for the placer to manage the geometry of a slave whose -pathName is \fIwindow\fR. The remaining arguments consist of one or -more \fIoption\-value\fR pairs that specify the way in which -\fIwindow\fR's geometry is managed. \fIOption\fR may have any of the -values accepted by the \fBplace configure\fR command. -.TP -\fBplace configure \fIwindow \fR?\fIoption\fR? ?\fIvalue option value ...\fR? -Query or modify the geometry options of the slave given by -\fIwindow\fR. If no \fIoption\fR is specified, this command returns a -list describing the available options (see \fBTk_ConfigureInfo\fR for -information on the format of this list). If \fIoption\fR is specified -with no \fIvalue\fR, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no \fIoption\fR is specified). If -one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given option(s) to have the given value(s); in this case -the command returns an empty string. - -The following \fIoption\-value\fR pairs are supported: -.RS -.TP -\fB\-anchor \fIwhere\fR -\fIWhere\fR specifies which point of \fIwindow\fR is to be positioned -at the (x,y) location selected by the \fB\-x\fR, \fB\-y\fR, -\fB\-relx\fR, and \fB\-rely\fR options. -The anchor point is in terms of the outer area of \fIwindow\fR -including its border, if any. -Thus if \fIwhere\fR is \fBse\fR then the lower-right corner of -\fIwindow\fR's border will appear at the given (x,y) location -in the master. -The anchor position defaults to \fBnw\fR. -.TP -\fB\-bordermode \fImode\fR -\fIMode\fR determines the degree to which borders within the -master are used in determining the placement of the slave. -The default and most common value is \fBinside\fR. -In this case the placer considers the area of the master to -be the innermost area of the master, inside any border: -an option of \fB\-x 0\fR corresponds to an x-coordinate just -inside the border and an option of \fB\-relwidth 1.0\fR -means \fIwindow\fR will fill the area inside the master's -border. - -If \fImode\fR is \fBoutside\fR then the placer considers -the area of the master to include its border; -this mode is typically used when placing \fIwindow\fR -outside its master, as with the options \fB\-x 0 \-y 0 \-anchor ne\fR. -Lastly, \fImode\fR may be specified as \fBignore\fR, in which -case borders are ignored: the area of the master is considered -to be its official X area, which includes any internal border but -no external border. A bordermode of \fBignore\fR is probably -not very useful. -.TP -\fB\-height \fIsize\fR -\fISize\fR specifies the height for \fIwindow\fR in screen units -(i.e. any of the forms accepted by \fBTk_GetPixels\fR). -The height will be the outer dimension of \fIwindow\fR including its -border, if any. -If \fIsize\fR is an empty string, or if no \fB\-height\fR or -\fB\-relheight\fR option is specified, then the height requested -internally by the window will be used. -.TP -\fB\-in \fImaster\fR -\fIMaster\fR specifes the path name of the window relative -to which \fIwindow\fR is to be placed. -\fIMaster\fR must either be \fIwindow\fR's parent or a descendant -of \fIwindow\fR's parent. -In addition, \fImaster\fR and \fIwindow\fR must both be descendants -of the same top-level window. -These restrictions are necessary to guarantee -that \fIwindow\fR is visible whenever \fImaster\fR is visible. -If this option isn't specified then the master defaults to -\fIwindow\fR's parent. -.TP -\fB\-relheight \fIsize\fR -\fISize\fR specifies the height for \fIwindow\fR. -In this case the height is specified as a floating-point number -relative to the height of the master: 0.5 means \fIwindow\fR will -be half as high as the master, 1.0 means \fIwindow\fR will have -the same height as the master, and so on. -If both \fB\-height\fR and \fB\-relheight\fR are specified for a slave, -their values are summed. For example, \fB\-relheight 1.0 \-height \-2\fR -makes the slave 2 pixels shorter than the master. -.TP -\fB\-relwidth \fIsize\fR -\fISize\fR specifies the width for \fIwindow\fR. -In this case the width is specified as a floating-point number -relative to the width of the master: 0.5 means \fIwindow\fR will -be half as wide as the master, 1.0 means \fIwindow\fR will have -the same width as the master, and so on. -If both \fB\-width\fR and \fB\-relwidth\fR are specified for a slave, -their values are summed. For example, \fB\-relwidth 1.0 \-width 5\fR -makes the slave 5 pixels wider than the master. -.TP -\fB\-relx \fIlocation\fR -\fILocation\fR specifies the x-coordinate within the master window -of the anchor point for \fIwindow\fR. -In this case the location is specified in a relative fashion -as a floating-point number: 0.0 corresponds to the left edge -of the master and 1.0 corresponds to the right edge of the master. -\fILocation\fR need not be in the range 0.0\-1.0. -If both \fB\-x\fR and \fB\-relx\fR are specified for a slave -then their values are summed. For example, \fB\-relx 0.5 \-x \-2\fR -positions the left edge of the slave 2 pixels to the left of the -center of its master. -.TP -\fB\-rely \fIlocation\fR -\fILocation\fR specifies the y-coordinate within the master window -of the anchor point for \fIwindow\fR. -In this case the value is specified in a relative fashion -as a floating-point number: 0.0 corresponds to the top edge -of the master and 1.0 corresponds to the bottom edge of the master. -\fILocation\fR need not be in the range 0.0\-1.0. -If both \fB\-y\fR and \fB\-rely\fR are specified for a slave -then their values are summed. For example, \fB\-rely 0.5 \-x 3\fR -positions the top edge of the slave 3 pixels below the -center of its master. -.TP -\fB\-width \fIsize\fR -\fISize\fR specifies the width for \fIwindow\fR in screen units -(i.e. any of the forms accepted by \fBTk_GetPixels\fR). -The width will be the outer width of \fIwindow\fR including its -border, if any. -If \fIsize\fR is an empty string, or if no \fB\-width\fR -or \fB\-relwidth\fR option is specified, then the width requested -internally by the window will be used. -.TP -\fB\-x \fIlocation\fR -\fILocation\fR specifies the x-coordinate within the master window -of the anchor point for \fIwindow\fR. -The location is specified in screen units (i.e. any of the forms -accepted by \fBTk_GetPixels\fR) and need not lie within the bounds -of the master window. -.TP -\fB\-y \fIlocation\fR -\fILocation\fR specifies the y-coordinate within the master window -of the anchor point for \fIwindow\fR. -The location is specified in screen units (i.e. any of the forms -accepted by \fBTk_GetPixels\fR) and need not lie within the bounds -of the master window. -.PP -If the same value is specified separately with -two different options, such as \fB\-x\fR and \fB\-relx\fR, then -the most recent option is used and the older one is ignored. -.RE -.TP -\fBplace forget \fIwindow\fR -Causes the placer to stop managing the geometry of \fIwindow\fR. As a -side effect of this command \fIwindow\fR will be unmapped so that it -doesn't appear on the screen. If \fIwindow\fR isn't currently managed -by the placer then the command has no effect. This command returns an -empty string. -.TP -\fBplace info \fIwindow\fR -Returns a list giving the current configuration of \fIwindow\fR. -The list consists of \fIoption\-value\fR pairs in exactly the -same form as might be specified to the \fBplace configure\fR -command. -.TP -\fBplace slaves \fIwindow\fR -Returns a list of all the slave windows for which \fIwindow\fR is the master. -If there are no slaves for \fIwindow\fR then an empty string is returned. - -If the configuration of a window has been retrieved with -\fBplace info\fR, that configuration can be restored later by -first using \fBplace forget\fR to erase any existing information -for the window and then invoking \fBplace configure\fR with -the saved information. - -.SH "FINE POINTS" -.PP -It is not necessary for the master window to be the parent -of the slave window. -This feature is useful in at least two situations. -First, for complex window layouts it means you can create a -hierarchy of subwindows whose only purpose -is to assist in the layout of the parent. -The ``real children'' of the parent (i.e. the windows that -are significant for the application's user interface) can be -children of the parent yet be placed inside the windows -of the geometry-management hierarchy. -This means that the path names of the ``real children'' -don't reflect the geometry-management hierarchy and users -can specify options for the real children -without being aware of the structure of the geometry-management -hierarchy. -.PP -A second reason for having a master different than the slave's -parent is to tie two siblings together. -For example, the placer can be used to force a window always to -be positioned centered just below one of its -siblings by specifying the configuration -.CS -\fB\-in \fIsibling\fB \-relx 0.5 \-rely 1.0 \-anchor n \-bordermode outside\fR -.CE -Whenever the sibling is repositioned in the future, the slave -will be repositioned as well. -.PP -Unlike many other geometry managers (such as the packer) -the placer does not make any attempt to manipulate the geometry of -the master windows or the parents of slave windows (i.e. it doesn't -set their requested sizes). -To control the sizes of these windows, make them windows like -frames and canvases that provide configuration options for this purpose. - -.SH KEYWORDS -geometry manager, height, location, master, place, rubber sheet, slave, width diff --git a/tcl/doc/popup.n b/tcl/doc/popup.n deleted file mode 100644 index 8f574c85ea..0000000000 --- a/tcl/doc/popup.n +++ /dev/null @@ -1,33 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH tk_popup n 4.0 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -tk_popup \- Post a popup menu -.SH SYNOPSIS -\fBtk_popup \fImenu x y \fR?\fIentry\fR? -.BE - -.SH DESCRIPTION -.PP -This procedure posts a menu at a given position on the screen and -configures Tk so that the menu and its cascaded children can be -traversed with the mouse or the keyboard. -\fIMenu\fR is the name of a menu widget and \fIx\fR and \fIy\fR -are the root coordinates at which to display the menu. -If \fIentry\fR is omitted or an empty string, the -menu's upper left corner is positioned at the given point. -Otherwise \fIentry\fR gives the index of an entry in \fImenu\fR and -the menu will be positioned so that the entry is positioned over -the given point. - -.SH KEYWORDS -menu, popup diff --git a/tcl/doc/radiobutton.n b/tcl/doc/radiobutton.n deleted file mode 100644 index db33fe66a6..0000000000 --- a/tcl/doc/radiobutton.n +++ /dev/null @@ -1,256 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH radiobutton n 4.4 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -radiobutton \- Create and manipulate radiobutton widgets -.SH SYNOPSIS -\fBradiobutton\fR \fIpathName \fR?\fIoptions\fR? -.SO -\-activebackground \-font \-pady -\-activeforeground \-foreground \-relief -\-anchor \-highlightbackground \-takefocus -\-background \-highlightcolor \-text -\-bitmap \-highlightthickness \-textvariable -\-borderwidth \-image \-underline -\-cursor \-justify \-wraplength -\-disabledforeground \-padx -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-command command Command -Specifies a Tcl command to associate with the button. This command -is typically invoked when mouse button 1 is released over the button -window. The button's global variable (\fB\-variable\fR option) will -be updated before the command is invoked. -.OP \-height height Height -Specifies a desired height for the button. -If an image or bitmap is being displayed in the button then the value is in -screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR); -for text it is in lines of text. -If this option isn't specified, the button's desired height is computed -from the size of the image or bitmap or text being displayed in it. -.OP \-indicatoron indicatorOn IndicatorOn -Specifies whether or not the indicator should be drawn. Must be a -proper boolean value. If false, the \fBrelief\fR option is -ignored and the widget's relief is always sunken if the widget is -selected and raised otherwise. -.OP \-selectcolor selectColor Background -Specifies a background color to use when the button is selected. -If \fBindicatorOn\fR is true then the color applies to the indicator. -Under Windows, this color is used as the background for the indicator -regardless of the select state. -If \fBindicatorOn\fR is false, this color is used as the background -for the entire widget, in place of \fBbackground\fR or \fBactiveBackground\fR, -whenever the widget is selected. -If specified as an empty string then no special color is used for -displaying when the widget is selected. -.VS 8.4 -.OP \-offrelief offRelief OffRelief -Specifies the relief for the checkbutton when the indicator is not drawn and -the checkbutton is off. The default value is "raised". By setting this option -to "flat" and setting -indicatoron to false and -overrelief to raised, -the effect is achieved -of having a flat button that raises on mouse-over and which is -depressed when activated. This is the behavior typically exhibited by -the Align-Left, Align-Right, and Center radiobuttons on the toolbar of a -word-processor, for example. - -.VE 8.4 -.VS 8.4 -.OP \-overrelief overRelief OverRelief -Specifies an alternative relief for the radiobutton, to be used when the -mouse cursor is over the widget. This option can be used to make -toolbar buttons, by configuring \fB\-relief flat \-overrelief -raised\fR. If the value of this option is the empty string, then no -alternative relief is used when the mouse cursor is over the radiobutton. -The empty string is the default value. -.VE 8.4 -.OP \-selectimage selectImage SelectImage -Specifies an image to display (in place of the \fBimage\fR option) -when the radiobutton is selected. -This option is ignored unless the \fBimage\fR option has been -specified. -.OP \-state state State -Specifies one of three states for the radiobutton: \fBnormal\fR, \fBactive\fR, -or \fBdisabled\fR. In normal state the radiobutton is displayed using the -\fBforeground\fR and \fBbackground\fR options. The active state is -typically used when the pointer is over the radiobutton. In active state -the radiobutton is displayed using the \fBactiveForeground\fR and -\fBactiveBackground\fR options. Disabled state means that the radiobutton -should be insensitive: the default bindings will refuse to activate -the widget and will ignore mouse button presses. -In this state the \fBdisabledForeground\fR and -\fBbackground\fR options determine how the radiobutton is displayed. -.OP \-value value Value -Specifies value to store in the button's associated variable whenever -this button is selected. -.OP \-variable variable Variable -Specifies name of global variable to set whenever this button is -selected. Changes in this variable also cause the button to select -or deselect itself. -Defaults to the value \fBselectedButton\fR. -.OP \-width width Width -Specifies a desired width for the button. -If an image or bitmap is being displayed in the button, the value is in -screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR); -for text it is in characters. -If this option isn't specified, the button's desired width is computed -from the size of the image or bitmap or text being displayed in it. -.BE - -.SH DESCRIPTION -.PP -The \fBradiobutton\fR command creates a new window (given by the -\fIpathName\fR argument) and makes it into a radiobutton widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the radiobutton such as its colors, font, -text, and initial relief. The \fBradiobutton\fR command returns its -\fIpathName\fR argument. At the time this command is invoked, -there must not exist a window named \fIpathName\fR, but -\fIpathName\fR's parent must exist. -.PP -.VS -A radiobutton is a widget that displays a textual string, bitmap or image -and a diamond or circle called an \fIindicator\fR. -.VE -If text is displayed, it must all be in a single font, but it -can occupy multiple lines on the screen (if it contains newlines -or if wrapping occurs because of the \fBwrapLength\fR option) and -one of the characters may optionally be underlined using the -\fBunderline\fR option. A radiobutton has -all of the behavior of a simple button: it can display itself in either -of three different ways, according to the \fBstate\fR option; -it can be made to appear -raised, sunken, or flat; it can be made to flash; and it invokes -a Tcl command whenever mouse button 1 is clicked over the -check button. -.PP -In addition, radiobuttons can be \fIselected\fR. -If a radiobutton is selected, the indicator is normally -.VS -drawn with a selected appearance, and -a Tcl variable associated with the radiobutton is set to a particular -value (normally 1). -Under Unix, the indicator is drawn with a sunken relief and a special -color. Under Windows, the indicator is drawn with a round mark inside. -If the radiobutton is not selected, then the indicator is drawn with a -deselected appearance, and the associated variable is -set to a different value (typically 0). -Under Unix, the indicator is drawn with a raised relief and no special -color. Under Windows, the indicator is drawn without a round mark inside. -.VE -Typically, several radiobuttons share a single variable and the -value of the variable indicates which radiobutton is to be selected. -When a radiobutton is selected it sets the value of the variable to -indicate that fact; each radiobutton also monitors the value of -the variable and automatically selects and deselects itself when the -variable's value changes. -By default the variable \fBselectedButton\fR -is used; its contents give the name of the button that is -selected, or the empty string if no button associated with that -variable is selected. -The name of the variable for a radiobutton, -plus the variable to be stored into it, may be modified with options -on the command line or in the option database. -Configuration options may also be used to modify the way the -indicator is displayed (or whether it is displayed at all). -By default a radiobutton is configured to select itself on button clicks. - -.SH "WIDGET COMMAND" -.PP -The \fBradiobutton\fR command creates a new Tcl command whose -name is \fIpathName\fR. This -command may be used to invoke various -operations on the widget. It has the following general form: -.CS -\fIpathName option \fR?\fIarg arg ...\fR? -.CE -\fIOption\fR and the \fIarg\fRs -determine the exact behavior of the command. The following -commands are possible for radiobutton widgets: -.TP -\fIpathName \fBcget\fR \fIoption\fR -Returns the current value of the configuration option given -by \fIoption\fR. -\fIOption\fR may have any of the values accepted by the \fBradiobutton\fR -command. -.TP -\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -Query or modify the configuration options of the widget. -If no \fIoption\fR is specified, returns a list describing all of -the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for -information on the format of this list). If \fIoption\fR is specified -with no \fIvalue\fR, the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no \fIoption\fR is specified). If -one or more \fIoption\-value\fR pairs are specified, the command -modifies the given widget option(s) to have the given value(s); in -this case the command returns an empty string. -\fIOption\fR may have any of the values accepted by the \fBradiobutton\fR -command. -.TP -\fIpathName \fBdeselect\fR -Deselects the radiobutton and sets the associated variable to an -empty string. -If this radiobutton was not currently selected, the command has -no effect. -.TP -\fIpathName \fBflash\fR -Flashes the radiobutton. This is accomplished by redisplaying the radiobutton -several times, alternating between active and normal colors. At -the end of the flash the radiobutton is left in the same normal/active -state as when the command was invoked. -This command is ignored if the radiobutton's state is \fBdisabled\fR. -.TP -\fIpathName \fBinvoke\fR -Does just what would have happened if the user invoked the radiobutton -with the mouse: selects the button and invokes -its associated Tcl command, if there is one. -The return value is the return value from the Tcl command, or an -empty string if there is no command associated with the radiobutton. -This command is ignored if the radiobutton's state is \fBdisabled\fR. -.TP -\fIpathName \fBselect\fR -Selects the radiobutton and sets the associated variable to the -value corresponding to this widget. - -.SH BINDINGS -.PP -Tk automatically creates class bindings for radiobuttons that give them -the following default behavior: -.VS -.IP [1] -On Unix systems, a radiobutton activates whenever the mouse passes -over it and deactivates whenever the mouse leaves the radiobutton. On -Mac and Windows systems, when mouse button 1 is pressed over a -radiobutton, the button activates whenever the mouse pointer is inside -the button, and deactivates whenever the mouse pointer leaves the -button. -.VE -.IP [2] -When mouse button 1 is pressed over a radiobutton it is invoked (it -becomes selected and the command associated with the button is -invoked, if there is one). -.IP [3] -When a radiobutton has the input focus, the space key causes the radiobutton -to be invoked. -.PP -If the radiobutton's state is \fBdisabled\fR then none of the above -actions occur: the radiobutton is completely non-responsive. -.PP -The behavior of radiobuttons can be changed by defining new bindings for -individual widgets or by redefining the class bindings. - -.SH KEYWORDS -radiobutton, widget diff --git a/tcl/doc/raise.n b/tcl/doc/raise.n deleted file mode 100644 index 550e0914eb..0000000000 --- a/tcl/doc/raise.n +++ /dev/null @@ -1,38 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH raise n 3.3 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -raise \- Change a window's position in the stacking order -.SH SYNOPSIS -\fBraise \fIwindow \fR?\fIaboveThis\fR? -.BE - -.SH DESCRIPTION -.PP -If the \fIaboveThis\fR argument is omitted then the command raises -\fIwindow\fR so that it is above all of its siblings in the stacking -order (it will not be obscured by any siblings and will obscure -any siblings that overlap it). -If \fIaboveThis\fR is specified then it must be the path name of -a window that is either a sibling of \fIwindow\fR or the descendant -of a sibling of \fIwindow\fR. -In this case the \fBraise\fR command will insert -\fIwindow\fR into the stacking order just above \fIaboveThis\fR -(or the ancestor of \fIaboveThis\fR that is a sibling of \fIwindow\fR); -this could end up either raising or lowering \fIwindow\fR. - -.SH "SEE ALSO" -lower - -.SH KEYWORDS -obscure, raise, stacking order diff --git a/tcl/doc/scale.n b/tcl/doc/scale.n deleted file mode 100644 index 9c21d8fa91..0000000000 --- a/tcl/doc/scale.n +++ /dev/null @@ -1,247 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH scale n 4.1 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -scale \- Create and manipulate scale widgets -.SH SYNOPSIS -\fBscale\fR \fIpathName \fR?\fIoptions\fR? -.SO -\-activebackground \-foreground \-relief -\-background \-highlightbackground \-repeatdelay -\-borderwidth \-highlightcolor \-repeatinterval -\-cursor \-highlightthickness \-takefocus -\-font \-orient \-troughcolor -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-bigincrement bigIncrement BigIncrement -Some interactions with the scale cause its value to change by -``large'' increments; this option specifies the size of the -large increments. If specified as 0, the large increments default -to 1/10 the range of the scale. -.OP \-command command Command -Specifies the prefix of a Tcl command to invoke whenever the scale's -value is changed via a widget command. -The actual command consists -of this option followed by a space and a real number indicating the -new value of the scale. -.OP \-digits digits Digits -An integer specifying how many significant digits should be retained -when converting the value of the scale to a string. -If the number is less than or equal to zero, then the scale picks -the smallest value that guarantees that every possible slider -position prints as a different string. -.OP \-from from From -A real value corresponding to the left or top end of the scale. -.OP \-label label Label -A string to display as a label for the scale. For -vertical scales the label is displayed just to the right of the -top end of the scale. For horizontal scales the label is displayed -just above the left end of the scale. If the option is specified -as an empty string, no label is displayed. -.OP \-length length Length -Specifies the desired long dimension of the scale in screen units -(i.e. any of the forms acceptable to \fBTk_GetPixels\fR). -For vertical scales this is the scale's height; for horizontal scales -it is the scale's width. -.OP \-resolution resolution Resolution -A real value specifying the resolution for the scale. -If this value is greater than zero then the scale's value will always be -rounded to an even multiple of this value, as will tick marks and -the endpoints of the scale. If the value is less than zero then no -rounding occurs. Defaults to 1 (i.e., the value will be integral). -.OP \-showvalue showValue ShowValue -Specifies a boolean value indicating whether or not the current -value of the scale is to be displayed. -.OP \-sliderlength sliderLength SliderLength -Specfies the size of the slider, measured in screen units along the slider's -long dimension. The value may be specified in any of the forms acceptable -to \fBTk_GetPixels\fR. -.OP \-sliderrelief sliderRelief SliderRelief -Specifies the relief to use when drawing the slider, such as \fBraised\fR -or \fBsunken\fR. -.OP \-state state State -Specifies one of three states for the scale: \fBnormal\fR, -\fBactive\fR, or \fBdisabled\fR. -If the scale is disabled then the value may not be changed and the scale -won't activate. -If the scale is active, the slider is displayed using the color -specified by the \fBactiveBackground\fR option. -.OP \-tickinterval tickInterval TickInterval -Must be a real value. -Determines the spacing between numerical -tick marks displayed below or to the left of the slider. -If 0, no tick marks will be displayed. -.OP \-to to To -Specifies a real value corresponding -to the right or bottom end of the scale. -This value may be either less than or greater than the \fBfrom\fR option. -.OP \-variable variable Variable -Specifies the name of a global variable to link to the scale. Whenever the -value of the variable changes, the scale will update to reflect this -value. -Whenever the scale is manipulated interactively, the variable -will be modified to reflect the scale's new value. -.OP \-width width Width -Specifies the desired narrow dimension of the trough in screen units -(i.e. any of the forms acceptable to \fBTk_GetPixels\fR). -For vertical scales this is the trough's width; for horizontal scales -this is the trough's height. -.BE - -.SH DESCRIPTION -.PP -The \fBscale\fR command creates a new window (given by the -\fIpathName\fR argument) and makes it into a scale widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the scale such as its colors, orientation, -and relief. The \fBscale\fR command returns its -\fIpathName\fR argument. At the time this command is invoked, -there must not exist a window named \fIpathName\fR, but -\fIpathName\fR's parent must exist. -.PP -A scale is a widget that displays a rectangular \fItrough\fR and a -small \fIslider\fR. The trough corresponds to a range -of real values (determined by the \fBfrom\fR, \fBto\fR, and -\fBresolution\fR options), -and the position of the slider selects a particular real value. -The slider's position (and hence the scale's value) may be adjusted -with the mouse or keyboard as described in the BINDINGS -section below. Whenever the scale's value is changed, a Tcl -command is invoked (using the \fBcommand\fR option) to notify -other interested widgets of the change. -In addition, the value -of the scale can be linked to a Tcl variable (using the \fBvariable\fR -option), so that changes in either are reflected in the other. -.PP -Three annotations may be displayed in a scale widget: a label -appearing at the top right of the widget (top left for horizontal -scales), a number displayed just to the left of the slider -(just above the slider for horizontal scales), and a collection -of numerical tick marks just to the left of the current value -(just below the trough for horizontal scales). Each of these three -annotations may be enabled or disabled using the -configuration options. - -.SH "WIDGET COMMAND" -.PP -The \fBscale\fR command creates a new Tcl command whose -name is \fIpathName\fR. This -command may be used to invoke various -operations on the widget. It has the following general form: -.CS -\fIpathName option \fR?\fIarg arg ...\fR? -.CE -\fIOption\fR and the \fIarg\fRs -determine the exact behavior of the command. The following -commands are possible for scale widgets: -.TP -\fIpathName \fBcget\fR \fIoption\fR -Returns the current value of the configuration option given -by \fIoption\fR. -\fIOption\fR may have any of the values accepted by the \fBscale\fR -command. -.TP -\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -Query or modify the configuration options of the widget. -If no \fIoption\fR is specified, returns a list describing all of -the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for -information on the format of this list). If \fIoption\fR is specified -with no \fIvalue\fR, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no \fIoption\fR is specified). If -one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given widget option(s) to have the given value(s); in -this case the command returns an empty string. -\fIOption\fR may have any of the values accepted by the \fBscale\fR -command. -.TP -\fIpathName \fBcoords \fR?\fIvalue\fR? -Returns a list whose elements are the x and y coordinates of -the point along the centerline of the trough that corresponds -to \fIvalue\fR. -If \fIvalue\fR is omitted then the scale's current value is used. -.TP -\fIpathName \fBget\fR ?\fIx y\fR? -If \fIx\fR and \fIy\fR are omitted, returns the current value -of the scale. If \fIx\fR and \fIy\fR are specified, they give -pixel coordinates within the widget; the command returns -the scale value corresponding to the given pixel. -Only one of \fIx\fR or \fIy\fR is used: for horizontal scales -\fIy\fR is ignored, and for vertical scales \fIx\fR is ignored. -.TP -\fIpathName \fBidentify\fR \fIx y\fR -Returns a string indicating what part of the scale lies under -the coordinates given by \fIx\fR and \fIy\fR. -A return value of \fBslider\fR means that the point is over -the slider; \fBtrough1\fR means that the point is over the -portion of the slider above or to the left of the slider; -and \fBtrough2\fR means that the point is over the portion -of the slider below or to the right of the slider. -If the point isn't over one of these elements, an empty string -is returned. -.TP -\fIpathName \fBset\fR \fIvalue\fR -This command is invoked to change the current value of the scale, -and hence the position at which the slider is displayed. \fIValue\fR -gives the new value for the scale. -The command has no effect if the scale is disabled. - -.SH BINDINGS -.PP -Tk automatically creates class bindings for scales that give them -the following default behavior. -Where the behavior is different for vertical and horizontal scales, -the horizontal behavior is described in parentheses. -.IP [1] -If button 1 is pressed in the trough, the scale's value will -be incremented or decremented by the value of the \fBresolution\fR -option so that the slider moves in the direction of the cursor. -If the button is held down, the action auto-repeats. -.IP [2] -If button 1 is pressed over the slider, the slider can be dragged -with the mouse. -.IP [3] -If button 1 is pressed in the trough with the Control key down, -the slider moves all the way to the end of its range, in the -direction towards the mouse cursor. -.IP [4] -If button 2 is pressed, the scale's value is set to the mouse -position. If the mouse is dragged with button 2 down, the scale's -value changes with the drag. -.IP [5] -The Up and Left keys move the slider up (left) by the value -of the \fBresolution\fR option. -.IP [6] -The Down and Right keys move the slider down (right) by the value -of the \fBresolution\fR option. -.IP [7] -Control-Up and Control-Left move the slider up (left) by the -value of the \fBbigIncrement\fR option. -.IP [8] -Control-Down and Control-Right move the slider down (right) by the -value of the \fBbigIncrement\fR option. -.IP [9] -Home moves the slider to the top (left) end of its range. -.IP [10] -End moves the slider to the bottom (right) end of its range. -.PP -If the scale is disabled using the \fBstate\fR option then -none of the above bindings have any effect. -.PP -The behavior of scales can be changed by defining new bindings for -individual widgets or by redefining the class bindings. - -.SH KEYWORDS -scale, slider, trough, widget diff --git a/tcl/doc/scrollbar.n b/tcl/doc/scrollbar.n deleted file mode 100644 index 744889dec5..0000000000 --- a/tcl/doc/scrollbar.n +++ /dev/null @@ -1,341 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH scrollbar n 4.1 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -scrollbar \- Create and manipulate scrollbar widgets -.SH SYNOPSIS -\fBscrollbar\fR \fIpathName \fR?\fIoptions\fR? -.SO -\-activebackground \-highlightcolor \-repeatdelay -\-background \-highlightthickness \-repeatinterval -\-borderwidth \-jump \-takefocus -\-cursor \-orient \-troughcolor -\-highlightbackground \-relief -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-activerelief activeRelief ActiveRelief -Specifies the relief to use when displaying the element that is -active, if any. -Elements other than the active element are always displayed with -a raised relief. -.OP \-command command Command -Specifies the prefix of a Tcl command to invoke to change the view -in the widget associated with the scrollbar. When a user requests -a view change by manipulating the scrollbar, a Tcl command is -invoked. The actual command consists of this option followed by -additional information as described later. This option almost always has -a value such as \fB.t xview\fR or \fB.t yview\fR, consisting of the -name of a widget and either \fBxview\fR (if the scrollbar is for -horizontal scrolling) or \fByview\fR (for vertical scrolling). -All scrollable widgets have \fBxview\fR and \fByview\fR commands -that take exactly the additional arguments appended by the scrollbar -as described in SCROLLING COMMANDS below. -.OP \-elementborderwidth elementBorderWidth BorderWidth -Specifies the width of borders drawn around the internal elements -of the scrollbar (the two arrows and the slider). The value may -have any of the forms acceptable to \fBTk_GetPixels\fR. -If this value is less than zero, the value of the \fBborderWidth\fR -option is used in its place. -.OP \-width width Width -Specifies the desired narrow dimension of the scrollbar window, -not including 3-D border, if any. For vertical -scrollbars this will be the width and for horizontal scrollbars -this will be the height. -The value may have any of the forms acceptable to \fBTk_GetPixels\fR. -.BE - -.SH DESCRIPTION -.PP -The \fBscrollbar\fR command creates a new window (given by the -\fIpathName\fR argument) and makes it into a scrollbar widget. -Additional options, described above, may be specified on the command -line or in the option database to configure aspects of the scrollbar -such as its colors, orientation, and relief. -The \fBscrollbar\fR command returns its \fIpathName\fR argument. -At the time this command is invoked, there must not exist a window -named \fIpathName\fR, but \fIpathName\fR's parent must exist. -.PP -A scrollbar is a widget that displays two arrows, one at each end of -the scrollbar, and a \fIslider\fR in the middle portion of the -scrollbar. -It provides information about what is visible in an \fIassociated window\fR -that displays an document of some sort (such as a file being edited or -a drawing). -The position and size of the slider indicate which portion of the -document is visible in the associated window. For example, if the -slider in a vertical scrollbar covers the top third of the area -between the two arrows, it means that the associated window displays -the top third of its document. -.PP -Scrollbars can be used to adjust the view in the associated window -by clicking or dragging with the mouse. See the BINDINGS section -below for details. - -.SH "ELEMENTS" -.PP -A scrollbar displays five elements, which are referred to in the -widget commands for the scrollbar: -.TP 10 -\fBarrow1\fR -The top or left arrow in the scrollbar. -.TP 10 -\fBtrough1\fR -The region between the slider and \fBarrow1\fR. -.TP 10 -\fBslider\fR -The rectangle that indicates what is visible in the associated widget. -.TP 10 -\fBtrough2\fR -The region between the slider and \fBarrow2\fR. -.TP 10 -\fBarrow2\fR -The bottom or right arrow in the scrollbar. - -.SH "WIDGET COMMAND" -.PP -The \fBscrollbar\fR command creates a new Tcl command whose -name is \fIpathName\fR. This -command may be used to invoke various -operations on the widget. It has the following general form: -.CS -\fIpathName option \fR?\fIarg arg ...\fR? -.CE -\fIOption\fR and the \fIarg\fRs -determine the exact behavior of the command. The following -commands are possible for scrollbar widgets: -.TP -\fIpathName \fBactivate \fR?\fIelement\fR? -Marks the element indicated by \fIelement\fR as active, which -causes it to be displayed as specified by the \fBactiveBackground\fR -and \fBactiveRelief\fR options. -The only element values understood by this command are \fBarrow1\fR, -\fBslider\fR, or \fBarrow2\fR. -If any other value is specified then no element of the scrollbar -will be active. -If \fIelement\fR is not specified, the command returns -the name of the element that is currently active, or an empty string -if no element is active. -.TP -\fIpathName \fBcget\fR \fIoption\fR -Returns the current value of the configuration option given -by \fIoption\fR. -\fIOption\fR may have any of the values accepted by the \fBscrollbar\fR -command. -.TP -\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -Query or modify the configuration options of the widget. -If no \fIoption\fR is specified, returns a list describing all of -the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for -information on the format of this list). If \fIoption\fR is specified -with no \fIvalue\fR, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no \fIoption\fR is specified). If -one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given widget option(s) to have the given value(s); in -this case the command returns an empty string. -\fIOption\fR may have any of the values accepted by the \fBscrollbar\fR -command. -.TP -\fIpathName \fBdelta \fIdeltaX deltaY\fR -Returns a real number indicating the fractional change in -the scrollbar setting that corresponds to a given change -in slider position. For example, if the scrollbar is horizontal, -the result indicates how much the scrollbar setting must change -to move the slider \fIdeltaX\fR pixels to the right (\fIdeltaY\fR is -ignored in this case). -If the scrollbar is vertical, the result indicates how much the -scrollbar setting must change to move the slider \fIdeltaY\fR pixels -down. The arguments and the result may be zero or negative. -.TP -\fIpathName \fBfraction \fIx y\fR -Returns a real number between 0 and 1 indicating where the point -given by \fIx\fR and \fIy\fR lies in the trough area of the scrollbar. -The value 0 corresponds to the top or left of the trough, the -value 1 corresponds to the bottom or right, 0.5 corresponds to -the middle, and so on. -\fIX\fR and \fIy\fR must be pixel coordinates relative to the scrollbar -widget. -If \fIx\fR and \fIy\fR refer to a point outside the trough, the closest -point in the trough is used. -.TP -\fIpathName \fBget\fR -Returns the scrollbar settings in the form of a list whose -elements are the arguments to the most recent \fBset\fR widget command. -.TP -\fIpathName \fBidentify\fR \fIx y\fR -Returns the name of the element under the point given by \fIx\fR and -\fIy\fR (such as \fBarrow1\fR), or an empty string if the point does -not lie in any element of the scrollbar. -\fIX\fR and \fIy\fR must be pixel coordinates relative to the scrollbar -widget. -.TP -\fIpathName \fBset\fR \fIfirst last\fR -This command is invoked by the scrollbar's associated widget to -tell the scrollbar about the current view in the widget. -The command takes two arguments, each of which is a real fraction -between 0 and 1. -The fractions describe the range of the document that is visible in -the associated widget. -For example, if \fIfirst\fR is 0.2 and \fIlast\fR is 0.4, it means -that the first part of the document visible in the window is 20% -of the way through the document, and the last visible part is 40% -of the way through. - -.SH "SCROLLING COMMANDS" -.PP -When the user interacts with the scrollbar, for example by dragging -the slider, the scrollbar notifies the associated widget that it -must change its view. -The scrollbar makes the notification by evaluating a Tcl command -generated from the scrollbar's \fB\-command\fR option. -The command may take any of the following forms. -In each case, \fIprefix\fR is the contents of the -\fB\-command\fR option, which usually has a form like \fB.t yview\fR -.TP -\fIprefix \fBmoveto \fIfraction\fR -\fIFraction\fR is a real number between 0 and 1. -The widget should adjust its view so that the point given -by \fIfraction\fR appears at the beginning of the widget. -If \fIfraction\fR is 0 it refers to the beginning of the -document. 1.0 refers to the end of the document, 0.333 -refers to a point one-third of the way through the document, -and so on. -.TP -\fIprefix \fBscroll \fInumber \fBunits\fR -The widget should adjust its view by \fInumber\fR units. -The units are defined in whatever way makes sense for the widget, -such as characters or lines in a text widget. -\fINumber\fR is either 1, which means one unit should scroll off -the top or left of the window, or \-1, which means that one unit -should scroll off the bottom or right of the window. -.TP -\fIprefix \fBscroll \fInumber \fBpages\fR -The widget should adjust its view by \fInumber\fR pages. -It is up to the widget to define the meaning of a page; typically -it is slightly less than what fits in the window, so that there -is a slight overlap between the old and new views. -\fINumber\fR is either 1, which means the next page should -become visible, or \-1, which means that the previous page should -become visible. - -.SH "OLD COMMAND SYNTAX" -.PP -In versions of Tk before 4.0, the \fBset\fR and \fBget\fR widget -commands used a different form. -This form is still supported for backward compatibility, but it -is deprecated. -In the old command syntax, the \fBset\fR widget command has the -following form: -.TP -\fIpathName \fBset\fR \fItotalUnits windowUnits firstUnit lastUnit\fR -In this form the arguments are all integers. -\fITotalUnits\fR gives the total size of the object being displayed in the -associated widget. The meaning of one unit depends on the associated -widget; for example, in a text editor widget units might -correspond to lines of -text. \fIWindowUnits\fR indicates the total number of units that -can fit in the associated window at one time. \fIFirstUnit\fR -and \fIlastUnit\fR give the indices of the first and last units -currently visible in the associated window (zero corresponds to the -first unit of the object). -.LP -Under the old syntax the \fBget\fR widget command returns a list -of four integers, consisting of the \fItotalUnits\fR, \fIwindowUnits\fR, -\fIfirstUnit\fR, and \fIlastUnit\fR values from the last \fBset\fR -widget command. -.PP -The commands generated by scrollbars also have a different form -when the old syntax is being used: -.TP -\fIprefix\fR \fIunit\fR -\fIUnit\fR is an integer that indicates what should appear at -the top or left of the associated widget's window. -It has the same meaning as the \fIfirstUnit\fR and \fIlastUnit\fR -arguments to the \fBset\fR widget command. -.LP -The most recent \fBset\fR widget command determines whether or not -to use the old syntax. -If it is given two real arguments then the new syntax will be -used in the future, and if it is given four integer arguments then -the old syntax will be used. - -.SH BINDINGS -Tk automatically creates class bindings for scrollbars that give them -the following default behavior. -If the behavior is different for vertical and horizontal scrollbars, -the horizontal behavior is described in parentheses. - -.IP [1] -Pressing button 1 over \fBarrow1\fR causes the view in the -associated widget to shift up (left) by one unit so that the -document appears to move down (right) one unit. -If the button is held down, the action auto-repeats. -.IP [2] -Pressing button 1 over \fBtrough1\fR causes the view in the -associated widget to shift up (left) by one screenful so that the -document appears to move down (right) one screenful. -If the button is held down, the action auto-repeats. -.IP [3] -Pressing button 1 over the slider and dragging causes the view -to drag with the slider. -If the \fBjump\fR option is true, then the view doesn't drag along -with the slider; it changes only when the mouse button is released. -.IP [4] -Pressing button 1 over \fBtrough2\fR causes the view in the -associated widget to shift down (right) by one screenful so that the -document appears to move up (left) one screenful. -If the button is held down, the action auto-repeats. -.IP [5] -Pressing button 1 over \fBarrow2\fR causes the view in the -associated widget to shift down (right) by one unit so that the -document appears to move up (left) one unit. -If the button is held down, the action auto-repeats. -.IP [6] -If button 2 is pressed over the trough or the slider, it sets -the view to correspond to the mouse position; dragging the -mouse with button 2 down causes the view to drag with the mouse. -If button 2 is pressed over one of the arrows, it causes the -same behavior as pressing button 1. -.IP [7] -If button 1 is pressed with the Control key down, then if the -mouse is over \fBarrow1\fR or \fBtrough1\fR the view changes -to the very top (left) of the document; if the mouse is over -\fBarrow2\fR or \fBtrough2\fR the view changes -to the very bottom (right) of the document; if the mouse is -anywhere else then the button press has no effect. -.IP [8] -In vertical scrollbars the Up and Down keys have the same behavior -as mouse clicks over \fBarrow1\fR and \fBarrow2\fR, respectively. -In horizontal scrollbars these keys have no effect. -.IP [9] -In vertical scrollbars Control-Up and Control-Down have the same -behavior as mouse clicks over \fBtrough1\fR and \fBtrough2\fR, respectively. -In horizontal scrollbars these keys have no effect. -.IP [10] -In horizontal scrollbars the Up and Down keys have the same behavior -as mouse clicks over \fBarrow1\fR and \fBarrow2\fR, respectively. -In vertical scrollbars these keys have no effect. -.IP [11] -In horizontal scrollbars Control-Up and Control-Down have the same -behavior as mouse clicks over \fBtrough1\fR and \fBtrough2\fR, respectively. -In vertical scrollbars these keys have no effect. -.IP [12] -The Prior and Next keys have the same behavior -as mouse clicks over \fBtrough1\fR and \fBtrough2\fR, respectively. -.IP [13] -The Home key adjusts the view to the top (left edge) of the document. -.IP [14] -The End key adjusts the view to the bottom (right edge) of the document. - -.SH KEYWORDS -scrollbar, widget diff --git a/tcl/doc/selection.n b/tcl/doc/selection.n deleted file mode 100644 index 3c41f88fd7..0000000000 --- a/tcl/doc/selection.n +++ /dev/null @@ -1,136 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH selection n 8.1 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -selection \- Manipulate the X selection -.SH SYNOPSIS -\fBselection \fIoption\fR ?\fIarg arg ...\fR? -.BE - -.SH DESCRIPTION -.PP -This command provides a Tcl interface to the X selection mechanism and -implements the full selection functionality described in the -X Inter-Client Communication Conventions Manual (ICCCM). -.PP -Note that for management of the CLIPBOARD selection (see below), the -\fBclipboard\fR command may also be used. -.PP -The first argument to \fBselection\fR determines the format of the -rest of the arguments and the behavior of the command. The following -forms are currently supported: -.PP -.TP -\fBselection clear\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-selection\fR \fIselection\fR? -If \fIselection\fR exists anywhere on \fIwindow\fR's display, clear it -so that no window owns the selection anymore. \fISelection\fR -specifies the X selection that should be cleared, and should be an -atom name such as PRIMARY or CLIPBOARD; see the Inter-Client -Communication Conventions Manual for complete details. -\fISelection\fR defaults to PRIMARY and \fIwindow\fR defaults to ``.''. -Returns an empty string. -.TP -\fBselection get\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-selection\fR \fIselection\fR? ?\fB\-type\fR \fItype\fR? -Retrieves the value of \fIselection\fR from \fIwindow\fR's display and -returns it as a result. \fISelection\fR defaults to PRIMARY and -\fIwindow\fR defaults to ``.''. -\fIType\fR specifies the form in which the selection is to be returned -(the desired ``target'' for conversion, in ICCCM terminology), and -should be an atom name such as STRING or FILE_NAME; see the -Inter-Client Communication Conventions Manual for complete details. -\fIType\fR defaults to STRING. The selection owner may choose to -return the selection in any of several different representation -formats, such as STRING, ATOM, INTEGER, etc. (this format is different -than the selection type; see the ICCCM for all the confusing details). -If the selection is returned in a non-string format, such as INTEGER -or ATOM, the \fBselection\fR command converts it to string format as a -collection of fields separated by spaces: atoms are converted to their -textual names, and anything else is converted to hexadecimal integers. -.TP -\fBselection handle\fR ?\fB\-selection\fR \fIselection\fR? ?\fB\-type\fR \fItype\fR? ?\fB\-format\fR \fIformat\fR? \fIwindow command\fR -Creates a handler for selection requests, such that \fIcommand\fR will -be executed whenever \fIselection\fR is owned by \fIwindow\fR and -someone attempts to retrieve it in the form given by \fItype\fR -(e.g. \fItype\fR is specified in the \fBselection get\fR command). -\fISelection\fR defaults to PRIMARY, \fItype\fR defaults to STRING, and -\fIformat\fR defaults to STRING. If \fIcommand\fR is an empty string -then any existing handler for \fIwindow\fR, \fItype\fR, and -\fIselection\fR is removed. -.RS -.PP -When \fIselection\fR is requested, \fIwindow\fR is the selection owner, -and \fItype\fR is the requested type, \fIcommand\fR will be executed -as a Tcl command with two additional numbers appended to it -(with space separators). -The two additional numbers -.VS -are \fIoffset\fR and \fImaxChars\fR: \fIoffset\fR specifies a starting -character position in the selection and \fImaxChars\fR gives the maximum -number of characters to retrieve. The command should return a value consisting -of at most \fImaxChars\fR of the selection, starting at position -\fIoffset\fR. For very large selections (larger than \fImaxChars\fR) -the selection will be retrieved using several invocations of \fIcommand\fR -with increasing \fIoffset\fR values. If \fIcommand\fR returns a string -whose length is less than \fImaxChars\fR, the return value is assumed to -include all of the remainder of the selection; if the length of -\fIcommand\fR's result is equal to \fImaxChars\fR then -\fIcommand\fR will be invoked again, until it eventually -returns a result shorter than \fImaxChars\fR. The value of \fImaxChars\fR -will always be relatively large (thousands of characters). -.VE -.PP -If \fIcommand\fR returns an error then the selection retrieval is rejected -just as if the selection didn't exist at all. -.PP -The \fIformat\fR argument specifies the representation that should be -used to transmit the selection to the requester (the second column of -Table 2 of the ICCCM), and defaults to STRING. If \fIformat\fR is -STRING, the selection is transmitted as 8-bit ASCII characters (i.e. -just in the form returned by \fIcommand\fR). If \fIformat\fR is -ATOM, then the return value from \fIcommand\fR is divided into fields -separated by white space; each field is converted to its atom value, -and the 32-bit atom value is transmitted instead of the atom name. -For any other \fIformat\fR, the return value from \fIcommand\fR is -divided into fields separated by white space and each field is -converted to a 32-bit integer; an array of integers is transmitted -to the selection requester. -.PP -The \fIformat\fR argument is needed only for compatibility with -selection requesters that don't use Tk. If Tk is being -used to retrieve the selection then the value is converted back to -a string at the requesting end, so \fIformat\fR is -irrelevant. -.RE -.TP -\fBselection own\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-selection\fR \fIselection\fR? -.TP -\fBselection own\fR ?\fB\-command\fR \fIcommand\fR? ?\fB\-selection\fR \fIselection\fR? \fIwindow\fR -The first form of \fBselection own\fR returns the path name of the -window in this application that owns \fIselection\fR on the display -containing \fIwindow\fR, or an empty string if no window in this -application owns the selection. \fISelection\fR defaults to PRIMARY and -\fIwindow\fR defaults to ``.''. -.PP -The second form of \fBselection own\fR causes \fIwindow\fR to become -the new owner of \fIselection\fR on \fIwindow\fR's display, returning -an empty string as result. The existing owner, if any, is notified -that it has lost the selection. -If \fIcommand\fR is specified, it is a Tcl script to execute when -some other window claims ownership of the selection away from -\fIwindow\fR. \fISelection\fR defaults to PRIMARY. - -.SH "SEE ALSO" -clipboard - -.SH KEYWORDS -clear, format, handler, ICCCM, own, selection, target, type diff --git a/tcl/doc/send.n b/tcl/doc/send.n deleted file mode 100644 index 96056777d2..0000000000 --- a/tcl/doc/send.n +++ /dev/null @@ -1,97 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH send n 4.0 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -send \- Execute a command in a different application -.SH SYNOPSIS -\fBsend ?\fIoptions\fR? \fIapp cmd \fR?\fIarg arg ...\fR? -.BE - -.SH DESCRIPTION -.PP -This command arranges for \fIcmd\fR (and \fIarg\fRs) to be executed in the -application named by \fIapp\fR. It returns the result or -error from that command execution. -\fIApp\fR may be the name of any application whose main window is -on the display containing the sender's main window; it need not -be within the same process. -If no \fIarg\fR arguments are present, then the command to be executed is -contained entirely within the \fIcmd\fR argument. If one or -more \fIarg\fRs are present, they are concatenated to form the -command to be executed, just as for the \fBeval\fR command. -.PP -If the initial arguments of the command begin with ``\-'' -they are treated as options. The following options are -currently defined: -.TP -\fB\-async\fR -Requests asynchronous invocation. In this case the \fBsend\fR -command will complete immediately without waiting for \fIcmd\fR -to complete in the target application; no result will be available -and errors in the sent command will be ignored. -If the target application is in the same process as the sending -application then the \fB\-async\fR option is ignored. -.TP -\fB\-displayof\fR \fIpathName\fR -Specifies that the target application's main window is on the display -of the window given by \fIpathName\fR, instead of the display containing -the application's main window. -.TP -\fB\-\|\-\fR -Serves no purpose except to terminate the list of options. This -option is needed only if \fIapp\fR could contain a leading ``\-'' -character. - -.SH "APPLICATION NAMES" -.PP -The name of an application is set initially from the name of the -program or script that created the application. -You can query and change the name of an application with the -\fBtk appname\fR command. - -.SH "DISABLING SENDS" -.PP -If the \fBsend\fR command is removed from an application (e.g. -with the command \fBrename send {}\fR) then the application -will not respond to incoming send requests anymore, nor will it -be able to issue outgoing requests. -Communication can be reenabled by invoking the \fBtk appname\fR -command. - -.SH SECURITY -.PP -The \fBsend\fR command is potentially a serious security loophole. On Unix, -any application that can connect to your X server can send -scripts to your applications. -These incoming scripts can use Tcl to read and -write your files and invoke subprocesses under your name. -Host-based access control such as that provided by \fBxhost\fR -is particularly insecure, since it allows anyone with an account -on particular hosts to connect to your server, and if disabled it -allows anyone anywhere to connect to your server. -In order to provide at least a small amount of -security, Tk checks the access control being used by the server -and rejects incoming sends unless (a) \fBxhost\fR-style access control -is enabled (i.e. only certain hosts can establish connections) and (b) the -list of enabled hosts is empty. -This means that applications cannot connect to your server unless -they use some other form of authorization -such as that provide by \fBxauth\fR. -.VS -Under Windows, \fBsend\fR is currently disabled. Most of the -functionality is provided by the \fBdde\fR command instead. -.VE -.SH KEYWORDS -.VS -application, dde, name, remote execution, security, send -.VE diff --git a/tcl/doc/spinbox.n b/tcl/doc/spinbox.n deleted file mode 100644 index 7fe9299557..0000000000 --- a/tcl/doc/spinbox.n +++ /dev/null @@ -1,582 +0,0 @@ -'\" -'\" Copyright (c) 2000 Jeffrey Hobbs. -'\" Copyright (c) 2000 Ajuba Solutions. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id$ -'\" -.so man.macros -.TH spinbox n 8.4 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -spinbox \- Create and manipulate spinbox widgets -.SH SYNOPSIS -\fBspinbox\fR \fIpathName \fR?\fIoptions\fR? -.SO -\-activebackground \-highlightthickness \-repeatinterval -\-background \-insertbackground \-selectbackground -\-borderwidth \-insertborderwidth \-selectborderwidth -\-cursor \-insertontime \-selectforeground -\-exportselection \-insertwidth \-takefocus -\-font \-insertofftime \-textvariable -\-foreground \-justify \-xscrollcommand -\-highlightbackground \-relief -\-highlightcolor \-repeatdelay -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-buttonbackground buttonBackground Background -The background color to be used for the spin buttons. -.OP \-buttoncursor buttonCursor Cursor -The cursor to be used when over the spin buttons. If this is empty -(the default), a default cursor will be used. -.OP \-buttondownrelief buttonDownRelief Relief -The relief to be used for the upper spin button. -.OP \-buttonuprelief buttonUpRelief Relief -The relief to be used for the lower spin button. -.OP \-command command Command -Specifies a Tcl command to invoke whenever a spinbutton is invoked. -The command recognizes several percent substitutions: \fB%W\fR for -the widget path, \fB%s\fR for the current value of the widget, and -\fB%d\fR for the direction of the button pressed (\fBup\fR or \fBdown\fR). -.OP \-disabledbackground disabledBackground DisabledBackground -Specifies the background color to use when the spinbox is disabled. If -this option is the empty string, the normal background color is used. -.OP \-disabledforeground disabledForeground DisabledForeground -Specifies the foreground color to use when the spinbox is disabled. If -this option is the empty string, the normal foreground color is used. -.OP \-format format Format -Specifies an alternate format to use when setting the string value -when using the \fB\-from\fR and \fB\-to\fR range. -This must be a format specifier of the form \fB%.f\fR, -as it will format a floating-point number. -.OP \-from from From -A floating-point value corresponding to the lowest value for a spinbox, to -be used in conjunction with \fB\-to\fR and \fB\-increment\fR. When all -are specified correctly, the spinbox will use these values to control its -contents. This value must be less than the \fB\-to\fR option. -If \fB\-values\fR is specified, it supercedes this option. -.OP "\-invalidcommand or \-invcmd" invalidCommand InvalidCommand -Specifies a script to eval when \fBvalidateCommand\fR returns 0. Setting -it to an empty string disables this feature (the default). The best use of -this option is to set it to \fIbell\fR. See \fBValidation\fR below for -more information. -.OP \-increment increment Increment -A floating-point value specifying the increment. When used with -\fB\-from\fR and \fB\-to\fR, the value in the widget will be adjusted by -\fB\-increment\fR when a spin button is pressed (up adds the value, -down subtracts the value). -.OP \-readonlybackground readonlyBackground ReadonlyBackground -Specifies the background color to use when the spinbox is readonly. If -this option is the empty string, the normal background color is used. -.OP \-state state State -Specifies one of three states for the spinbox: \fBnormal\fR, -\fBdisabled\fR, or \fBreadonly\fR. If the spinbox is readonly, then the -value may not be changed using widget commands and no insertion cursor -will be displayed, even if the input focus is in the widget; the -contents of the widget may still be selected. If the spinbox is -disabled, the value may not be changed, no insertion cursor will be -displayed, the contents will not be selectable, and the spinbox may -be displayed in a different color, depending on the values of the -\fB-disabledforeground\fR and \fB-disabledbackground\fR options. -.OP \-to to To -A floating-point value corresponding to the highest value for the spinbox, -to be used in conjunction with \fB\-from\fR and \fB\-increment\fR. When -all are specified correctly, the spinbox will use these values to control -its contents. This value must be greater than the \fB\-from\fR option. -If \fB\-values\fR is specified, it supercedes this option. -.OP \-validate validate Validate -Specifies the mode in which validation should operate: \fBnone\fR, -\fBfocus\fR, \fBfocusin\fR, \fBfocusout\fR, \fBkey\fR, or \fBall\fR. -It defaults to \fBnone\fR. When you want validation, you must explicitly -state which mode you wish to use. See \fBValidation\fR below for more. -.OP "\-validatecommand or \-vcmd" validateCommand ValidateCommand -Specifies a script to evaluate when you want to validate the input in the -widget. Setting it to an empty string disables this feature (the default). -Validation occurs according to the value of \fB\-validate\fR. -This command must return a valid Tcl boolean value. If it returns 0 (or -the valid Tcl boolean equivalent) then the value of the widget will not -change and the \fBinvalidCommand\fR will be evaluated if it is set. If it -returns 1, then value will be changed. -See \fBValidation\fR below for more information. -.OP \-values values Values -Must be a proper list value. If specified, the spinbox will use these -values as to control its contents, starting with the first value. This -option has precedence over the \fB\-from\fR and \fB\-to\fR range. -.OP \-width width Width -Specifies an integer value indicating the desired width of the spinbox window, -in average-size characters of the widget's font. -If the value is less than or equal to zero, the widget picks a -size just large enough to hold its current text. -.OP \-wrap wrap wrap -Must be a proper boolean value. If on, the spinbox will wrap around the -values of data in the widget. -.BE - -.SH DESCRIPTION -.PP -The \fBspinbox\fR command creates a new window (given by the -\fIpathName\fR argument) and makes it into a spinbox widget. -Additional options, described above, may be specified on the -command line or in the option database -to configure aspects of the spinbox such as its colors, font, -and relief. The \fBspinbox\fR command returns its -\fIpathName\fR argument. At the time this command is invoked, -there must not exist a window named \fIpathName\fR, but -\fIpathName\fR's parent must exist. -.PP -A \fBspinbox\fR is an extended \fBentry\fR widget that allows he user -to move, or spin, through a fixed set of ascending or descending values -such as times or dates in addition to editing the value as in an -\fBentry\fR. When first created, a spinbox's string is empty. -A portion of the spinbox may be selected as described below. -If a spinbox is exporting its selection (see the \fBexportSelection\fR -option), then it will observe the standard protocols for handling the -selection; spinbox selections are available as type \fBSTRING\fR. -Spinboxes also observe the standard Tk rules for dealing with the -input focus. When a spinbox has the input focus it displays an -\fIinsertion cursor\fR to indicate where new characters will be -inserted. -.PP -Spinboxes are capable of displaying strings that are too long to -fit entirely within the widget's window. In this case, only a -portion of the string will be displayed; commands described below -may be used to change the view in the window. Spinboxes use -the standard \fBxScrollCommand\fR mechanism for interacting with -scrollbars (see the description of the \fBxScrollCommand\fR option -for details). They also support scanning, as described below. - -.SH VALIDATION -.PP -Validation works by setting the \fBvalidateCommand\fR -option to a script which will be evaluated according to the \fBvalidate\fR -option as follows: -.PP -.IP \fBnone\fR 10 -Default. This means no validation will occur. -.IP \fBfocus\fR 10 -\fBvalidateCommand\fR will be called when the spinbox receives or -loses focus. -.IP \fBfocusin\fR 10 -\fBvalidateCommand\fR will be called when the spinbox receives focus. -.IP \fBfocusout\fR 10 -\fBvalidateCommand\fR will be called when the spinbox loses focus. -.IP \fBkey\fR 10 -\fBvalidateCommand\fR will be called when the spinbox is edited. -.IP \fBall\fR 10 -\fBvalidateCommand\fR will be called for all above conditions. -.PP -It is posible to perform percent substitutions on the \fBvalidateCommand\fR -and \fBinvalidCommand\fR, just as you would in a \fBbind\fR script. The -following substitutions are recognized: -.PP -.IP \fB%d\fR 5 -Type of action: 1 for \fBinsert\fR, 0 for \fBdelete\fR, -or -1 for focus, forced or textvariable validation. -.IP \fB%i\fR 5 -Index of char string to be inserted/deleted, if any, otherwise -1. -.IP \fB%P\fR 5 -The value of the spinbox should edition occur. If you are configuring the -spinbox widget to have a new textvariable, this will be the value of that -textvariable. -.IP \fB%s\fR 5 -The current value of spinbox before edition. -.IP \fB%S\fR 5 -The text string being inserted/deleted, if any. -Otherwise it is an empty string. -.IP \fB%v\fR 5 -The type of validation currently set. -.IP \fB%V\fR 5 -The type of validation that triggered the callback -(key, focusin, focusout, forced). -.IP \fB%W\fR 5 -The name of the spinbox widget. -.PP -In general, the \fBtextVariable\fR and \fBvalidateCommand\fR can be -dangerous to mix. Any problems have been overcome so that using the -\fBvalidateCommand\fR will not interfere with the traditional behavior of -the spinbox widget. Using the \fBtextVariable\fR for read-only purposes will -never cause problems. The danger comes when you try set the -\fBtextVariable\fR to something that the \fBvalidateCommand\fR would not -accept, which causes \fBvalidate\fR to become \fInone\fR (the -\fBinvalidCommand\fR will not be triggered). The same happens -when an error occurs evaluating the \fBvalidateCommand\fR. -.PP -Primarily, an error will occur when the \fBvalidateCommand\fR or -\fBinvalidCommand\fR encounters an error in its script while evaluating or -\fBvalidateCommand\fR does not return a valid Tcl boolean value. The -\fBvalidate\fR option will also set itself to \fBnone\fR when you edit the -spinbox widget from within either the \fBvalidateCommand\fR or the -\fBinvalidCommand\fR. Such editions will override the one that was being -validated. If you wish to edit the value of the widget -during validation and still have the \fBvalidate\fR option set, you should -include the command -.CS - \fI%W config -validate %v\fR -.CE -in the \fBvalidateCommand\fR or \fBinvalidCommand\fR (whichever one you -were editing the spinbox widget from). It is also recommended to not set an -associated \fBtextVariable\fR during validation, as that can cause the -spinbox widget to become out of sync with the \fBtextVariable\fR. - -.SH "WIDGET COMMAND" -.PP -The \fBspinbox\fR command creates a new Tcl command whose -name is \fIpathName\fR. This command may be used to invoke various -operations on the widget. It has the following general form: -.CS -\fIpathName option \fR?\fIarg arg ...\fR? -.CE -\fIOption\fR and the \fIarg\fRs -determine the exact behavior of the command. -.PP -Many of the widget commands for spinboxes take one or more indices as -arguments. An index specifies a particular character in the spinbox's -string, in any of the following ways: -.TP 12 -\fInumber\fR -Specifies the character as a numerical index, where 0 corresponds -to the first character in the string. -.TP 12 -\fBanchor\fR -Indicates the anchor point for the selection, which is set with the -\fBselect from\fR and \fBselect adjust\fR widget commands. -.TP 12 -\fBend\fR -Indicates the character just after the last one in the spinbox's string. -This is equivalent to specifying a numerical index equal to the length -of the spinbox's string. -.TP 12 -\fBinsert\fR -Indicates the character adjacent to and immediately following the -insertion cursor. -.TP 12 -\fBsel.first\fR -Indicates the first character in the selection. It is an error to -use this form if the selection isn't in the spinbox window. -.TP 12 -\fBsel.last\fR -Indicates the character just after the last one in the selection. -It is an error to use this form if the selection isn't in the -spinbox window. -.TP 12 -\fB@\fInumber\fR -In this form, \fInumber\fR is treated as an x-coordinate in the -spinbox's window; the character spanning that x-coordinate is used. -For example, ``\fB@0\fR'' indicates the left-most character in the -window. -.LP -Abbreviations may be used for any of the forms above, e.g. ``\fBe\fR'' -or ``\fBsel.f\fR''. In general, out-of-range indices are automatically -rounded to the nearest legal value. -.PP -The following commands are possible for spinbox widgets: -.TP -\fIpathName \fBbbox \fIindex\fR -Returns a list of four numbers describing the bounding box of the -character given by \fIindex\fR. -The first two elements of the list give the x and y coordinates of -the upper-left corner of the screen area covered by the character -(in pixels relative to the widget) and the last two elements give -the width and height of the character, in pixels. -The bounding box may refer to a region outside the visible area -of the window. -.TP -\fIpathName \fBcget\fR \fIoption\fR -Returns the current value of the configuration option given -by \fIoption\fR. -\fIOption\fR may have any of the values accepted by the \fBspinbox\fR -command. -.TP -\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -Query or modify the configuration options of the widget. -If no \fIoption\fR is specified, returns a list describing all of -the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for -information on the format of this list). If \fIoption\fR is specified -with no \fIvalue\fR, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no \fIoption\fR is specified). If -one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given widget option(s) to have the given value(s); in -this case the command returns an empty string. -\fIOption\fR may have any of the values accepted by the \fBspinbox\fR -command. -.TP -\fIpathName \fBdelete \fIfirst \fR?\fIlast\fR? -Delete one or more elements of the spinbox. -\fIFirst\fR is the index of the first character to delete, and -\fIlast\fR is the index of the character just after the last -one to delete. -If \fIlast\fR isn't specified it defaults to \fIfirst\fR+1, -i.e. a single character is deleted. -This command returns an empty string. -.TP -\fIpathName \fBget\fR -Returns the spinbox's string. -.TP -\fIpathName \fBicursor \fIindex\fR -Arrange for the insertion cursor to be displayed just before the character -given by \fIindex\fR. Returns an empty string. -.TP -\fIpathName \fBidentify\fI x y\fR -Returns the name of the window element corresponding to coordinates -\fIx\fR and \fIy\fR in the spinbox. Return value is one of: -\fBnone\fR, \fBbuttondown\fR, \fBbuttonup\fR, \fBentry\fR. -.TP -\fIpathName \fBindex\fI index\fR -Returns the numerical index corresponding to \fIindex\fR. -.TP -\fIpathName \fBinsert \fIindex string\fR -Insert the characters of \fIstring\fR just before the character -indicated by \fIindex\fR. Returns an empty string. -.TP -\fIpathName \fBinvoke\fI element\fR -Causes the specified element, either \fBbuttondown\fR or \fBbuttonup\fR, -to be invoked, triggering the action associated with it. -.TP -\fIpathName \fBscan\fR \fIoption args\fR -This command is used to implement scanning on spinboxes. It has -two forms, depending on \fIoption\fR: -.RS -.TP -\fIpathName \fBscan mark \fIx\fR -Records \fIx\fR and the current view in the spinbox window; used in -conjunction with later \fBscan dragto\fR commands. Typically this -command is associated with a mouse button press in the widget. It -returns an empty string. -.TP -\fIpathName \fBscan dragto \fIx\fR -This command computes the difference between its \fIx\fR argument -and the \fIx\fR argument to the last \fBscan mark\fR command for -the widget. It then adjusts the view left or right by 10 times the -difference in x-coordinates. This command is typically associated -with mouse motion events in the widget, to produce the effect of -dragging the spinbox at high speed through the window. The return -value is an empty string. -.RE -.TP -\fIpathName \fBselection \fIoption arg\fR -This command is used to adjust the selection within a spinbox. It -has several forms, depending on \fIoption\fR: -.RS -.TP -\fIpathName \fBselection adjust \fIindex\fR -Locate the end of the selection nearest to the character given by -\fIindex\fR, and adjust that end of the selection to be at \fIindex\fR -(i.e including but not going beyond \fIindex\fR). The other -end of the selection is made the anchor point for future -\fBselect to\fR commands. If the selection -isn't currently in the spinbox, then a new selection is created to -include the characters between \fIindex\fR and the most recent -selection anchor point, inclusive. -Returns an empty string. -.TP -\fIpathName \fBselection clear\fR -Clear the selection if it is currently in this widget. If the -selection isn't in this widget then the command has no effect. -Returns an empty string. -.TP -\fIpathName \fBselection element\fR ?\fIelement\fR? -Sets or gets the currently selected element. If a spinbutton element -is specified, it will be displayed depressed. -.TP -\fIpathName \fBselection from \fIindex\fR -Set the selection anchor point to just before the character -given by \fIindex\fR. Doesn't change the selection. -Returns an empty string. -.TP -\fIpathName \fBselection present\fR -Returns 1 if there is are characters selected in the spinbox, -0 if nothing is selected. -.TP -\fIpathName \fBselection range \fIstart\fR \fIend\fR -Sets the selection to include the characters starting with -the one indexed by \fIstart\fR and ending with the one just -before \fIend\fR. -If \fIend\fR refers to the same character as \fIstart\fR or an -earlier one, then the spinbox's selection is cleared. -.TP -\fIpathName \fBselection to \fIindex\fR -If \fIindex\fR is before the anchor point, set the selection -to the characters from \fIindex\fR up to but not including -the anchor point. -If \fIindex\fR is the same as the anchor point, do nothing. -If \fIindex\fR is after the anchor point, set the selection -to the characters from the anchor point up to but not including -\fIindex\fR. -The anchor point is determined by the most recent \fBselect from\fR -or \fBselect adjust\fR command in this widget. -If the selection isn't in this widget then a new selection is -created using the most recent anchor point specified for the widget. -Returns an empty string. -.RE -.TP -\fIpathName \fBset\fR ?\fIstring\fR? -If \fIstring\fR is specified, the spinbox will try and set it to this -value, otherwise it just returns the spinbox's string. -If validation is on, it will occur when setting the string. -.TP -\fIpathName \fBvalidate\fR -This command is used to force an evaluation of the \fBvalidateCommand\fR -independent of the conditions specified by the \fBvalidate\fR option. -This is done by temporarily setting the \fBvalidate\fR option to \fBall\fR. -It returns 0 or 1. -.TP -\fIpathName \fBxview \fIargs\fR -This command is used to query and change the horizontal position of the -text in the widget's window. It can take any of the following -forms: -.RS -.TP -\fIpathName \fBxview\fR -Returns a list containing two elements. -Each element is a real fraction between 0 and 1; together they describe -the horizontal span that is visible in the window. -For example, if the first element is .2 and the second element is .6, -20% of the spinbox's text is off-screen to the left, the middle 40% is visible -in the window, and 40% of the text is off-screen to the right. -These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR -option. -.TP -\fIpathName \fBxview\fR \fIindex\fR -Adjusts the view in the window so that the character given by \fIindex\fR -is displayed at the left edge of the window. -.TP -\fIpathName \fBxview moveto\fI fraction\fR -Adjusts the view in the window so that the character \fIfraction\fR of the -way through the text appears at the left edge of the window. -\fIFraction\fR must be a fraction between 0 and 1. -.TP -\fIpathName \fBxview scroll \fInumber what\fR -This command shifts the view in the window left or right according to -\fInumber\fR and \fIwhat\fR. -\fINumber\fR must be an integer. -\fIWhat\fR must be either \fBunits\fR or \fBpages\fR or an abbreviation -of one of these. -If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by -\fInumber\fR average-width characters on the display; if it is -\fBpages\fR then the view adjusts by \fInumber\fR screenfuls. -If \fInumber\fR is negative then characters farther to the left -become visible; if it is positive then characters farther to the right -become visible. -.RE - -.SH "DEFAULT BINDINGS" -.PP -Tk automatically creates class bindings for spinboxes that give them -the following default behavior. -In the descriptions below, ``word'' refers to a contiguous group -of letters, digits, or ``_'' characters, or any single character -other than these. -.IP [1] -Clicking mouse button 1 positions the insertion cursor -just before the character underneath the mouse cursor, sets the -input focus to this widget, and clears any selection in the widget. -Dragging with mouse button 1 strokes out a selection between -the insertion cursor and the character under the mouse. -.IP [2] -Double-clicking with mouse button 1 selects the word under the mouse -and positions the insertion cursor at the beginning of the word. -Dragging after a double click will stroke out a selection consisting -of whole words. -.IP [3] -Triple-clicking with mouse button 1 selects all of the text in the -spinbox and positions the insertion cursor before the first character. -.IP [4] -The ends of the selection can be adjusted by dragging with mouse -button 1 while the Shift key is down; this will adjust the end -of the selection that was nearest to the mouse cursor when button -1 was pressed. -If the button is double-clicked before dragging then the selection -will be adjusted in units of whole words. -.IP [5] -Clicking mouse button 1 with the Control key down will position the -insertion cursor in the spinbox without affecting the selection. -.IP [6] -If any normal printing characters are typed in a spinbox, they are -inserted at the point of the insertion cursor. -.IP [7] -The view in the spinbox can be adjusted by dragging with mouse button 2. -If mouse button 2 is clicked without moving the mouse, the selection -is copied into the spinbox at the position of the mouse cursor. -.IP [8] -If the mouse is dragged out of the spinbox on the left or right sides -while button 1 is pressed, the spinbox will automatically scroll to -make more text visible (if there is more text off-screen on the side -where the mouse left the window). -.IP [9] -The Left and Right keys move the insertion cursor one character to the -left or right; they also clear any selection in the spinbox and set -the selection anchor. -If Left or Right is typed with the Shift key down, then the insertion -cursor moves and the selection is extended to include the new character. -Control-Left and Control-Right move the insertion cursor by words, and -Control-Shift-Left and Control-Shift-Right move the insertion cursor -by words and also extend the selection. -Control-b and Control-f behave the same as Left and Right, respectively. -Meta-b and Meta-f behave the same as Control-Left and Control-Right, -respectively. -.IP [10] -The Home key, or Control-a, will move the insertion cursor to the -beginning of the spinbox and clear any selection in the spinbox. -Shift-Home moves the insertion cursor to the beginning of the spinbox -and also extends the selection to that point. -.IP [11] -The End key, or Control-e, will move the insertion cursor to the -end of the spinbox and clear any selection in the spinbox. -Shift-End moves the cursor to the end and extends the selection -to that point. -.IP [12] -The Select key and Control-Space set the selection anchor to the position -of the insertion cursor. They don't affect the current selection. -Shift-Select and Control-Shift-Space adjust the selection to the -current position of the insertion cursor, selecting from the anchor -to the insertion cursor if there was not any selection previously. -.IP [13] -Control-/ selects all the text in the spinbox. -.IP [14] -Control-\e clears any selection in the spinbox. -.IP [15] -The F16 key (labelled Copy on many Sun workstations) or Meta-w -copies the selection in the widget to the clipboard, if there is a selection. -.IP [16] -The F20 key (labelled Cut on many Sun workstations) or Control-w -copies the selection in the widget to the clipboard and deletes -the selection. -If there is no selection in the widget then these keys have no effect. -.IP [17] -The F18 key (labelled Paste on many Sun workstations) or Control-y -inserts the contents of the clipboard at the position of the -insertion cursor. -.IP [18] -The Delete key deletes the selection, if there is one in the spinbox. -If there is no selection, it deletes the character to the right of -the insertion cursor. -.IP [19] -The BackSpace key and Control-h delete the selection, if there is one -in the spinbox. -If there is no selection, it deletes the character to the left of -the insertion cursor. -.IP [20] -Control-d deletes the character to the right of the insertion cursor. -.IP [21] -Meta-d deletes the word to the right of the insertion cursor. -.IP [22] -Control-k deletes all the characters to the right of the insertion -cursor. -.IP [23] -Control-t reverses the order of the two characters to the right of -the insertion cursor. -.PP -If the spinbox is disabled using the \fB\-state\fR option, then the spinbox's -view can still be adjusted and text in the spinbox can still be selected, -but no insertion cursor will be displayed and no text modifications will -take place. -.PP -The behavior of spinboxes can be changed by defining new bindings for -individual widgets or by redefining the class bindings. - -.SH KEYWORDS -spinbox, entry, widget diff --git a/tcl/doc/text.n b/tcl/doc/text.n deleted file mode 100644 index 5cf8d9603c..0000000000 --- a/tcl/doc/text.n +++ /dev/null @@ -1,1776 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH text n 8.4 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -text, tk_textCopy, tk_textCut, tk_textPaste \- Create and manipulate text widgets -.SH SYNOPSIS -.nf -\fBtext\fR \fIpathName \fR?\fIoptions\fR? -.VS 8.4 -\fBtk_textCopy\fR \fIpathName\fR -\fBtk_textCut\fR \fIpathName\fR -\fBtk_textPaste\fR \fIpathName\fR -.VE 8.4 -.SO -\-background \-highlightthickness \-relief -\-borderwidth \-insertbackground \-selectbackground -\-cursor \-insertborderwidth \-selectborderwidth -\-exportselection \-insertofftime \-selectforeground -\-font \-insertontime \-setgrid -\-foreground \-insertwidth \-takefocus -\-highlightbackground \-padx \-xscrollcommand -\-highlightcolor \-pady \-yscrollcommand -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-autoseparators autoSeparators AutoSeparators -.VS 8.4 -Specifies a boolean that says whether separators are automatically -inserted in the undo stack. Only meaningful when the \fB\-undo\fR -option is true. -.VE 8.4 -.OP \-height height Height -Specifies the desired height for the window, in units of characters -in the font given by the \fB\-font\fR option. -Must be at least one. -.OP \-maxundo maxUndo MaxUndo -.VS 8.4 -Specifies the maximum number of compound undo actions on the undo -stack. A zero or a negative value imply an unlimited undo stack. -.VE 8.4 -.OP \-spacing1 spacing1 Spacing1 -Requests additional space above each text line in the widget, -using any of the standard forms for screen distances. -If a line wraps, this option only applies to the first line -on the display. -This option may be overriden with \fB\-spacing1\fR options in -tags. -.OP \-spacing2 spacing2 Spacing2 -For lines that wrap (so that they cover more than one line on the -display) this option specifies additional space to provide between -the display lines that represent a single line of text. -The value may have any of the standard forms for screen distances. -This option may be overriden with \fB\-spacing2\fR options in -tags. -.OP \-spacing3 spacing3 Spacing3 -Requests additional space below each text line in the widget, -using any of the standard forms for screen distances. -If a line wraps, this option only applies to the last line -on the display. -This option may be overriden with \fB\-spacing3\fR options in -tags. -.OP \-state state State -Specifies one of two states for the text: \fBnormal\fR or \fBdisabled\fR. -If the text is disabled then characters may not be inserted or deleted -and no insertion cursor will be displayed, even if the input focus is -in the widget. -.OP \-tabs tabs Tabs -Specifies a set of tab stops for the window. The option's value consists -of a list of screen distances giving the positions of the tab stops. Each -position may optionally be followed in the next list element -by one of the keywords \fBleft\fR, \fBright\fR, \fBcenter\fR, -or \fBnumeric\fR, which specifies how to justify -text relative to the tab stop. \fBLeft\fR is the default; it causes -the text following the tab character to be positioned with its left edge -at the tab position. \fBRight\fR means that the right edge of the text -following the tab character is positioned at the tab position, and -\fBcenter\fR means that the text is centered at the tab position. -\fBNumeric\fR means that the decimal point in the text is positioned -at the tab position; if there is no decimal point then the least -significant digit of the number is positioned just to the left of the -tab position; if there is no number in the text then the text is -right-justified at the tab position. -For example, \fB\-tabs {2c left 4c 6c center}\fR creates three -tab stops at two-centimeter intervals; the first two use left -justification and the third uses center justification. -If the list of tab stops does not have enough elements to cover all -of the tabs in a text line, then Tk extrapolates new tab stops using -the spacing and alignment from the last tab stop in the list. -The value of the \fBtabs\fR option may be overridden by \fB\-tabs\fR -options in tags. -If no \fB\-tabs\fR option is specified, or if it is specified as -an empty list, then Tk uses default tabs spaced every eight -(average size) characters. -.OP \-undo undo Undo -.VS 8.4 -Specifies a boolean that says whether the undo mechanism is active or -not. -.VE 8.4 -.OP \-width width Width -Specifies the desired width for the window in units of characters -in the font given by the \fB\-font\fR option. -If the font doesn't have a uniform width then the width of the -character ``0'' is used in translating from character units to -screen units. -.OP \-wrap wrap Wrap -Specifies how to handle lines in the text that are too long to be -displayed in a single line of the text's window. -The value must be \fBnone\fR or \fBchar\fR or \fBword\fR. -A wrap mode of \fBnone\fR means that each line of text appears as -exactly one line on the screen; extra characters that don't fit -on the screen are not displayed. -In the other modes each line of text will be broken up into several -screen lines if necessary to keep all the characters visible. -In \fBchar\fR mode a screen line break may occur after any character; -in \fBword\fR mode a line break will only be made at word boundaries. -.BE - -.SH DESCRIPTION -.PP -The \fBtext\fR command creates a new window (given by the -\fIpathName\fR argument) and makes it into a text widget. -Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the text such as its default background color -and relief. The \fBtext\fR command returns the -path name of the new window. -.PP -A text widget displays one or more lines of text and allows that -text to be edited. -Text widgets support four different kinds of annotations on the -text, called tags, marks, embedded windows or embedded images. -Tags allow different portions of the text -to be displayed with different fonts and colors. -In addition, Tcl commands can be associated with tags so -that scripts are invoked when particular actions such as keystrokes -and mouse button presses occur in particular ranges of the text. -See TAGS below for more details. -.PP -The second form of annotation consists of marks, which are floating -markers in the text. -Marks are used to keep track of various interesting positions in the -text as it is edited. -See MARKS below for more details. -.PP -The third form of annotation allows arbitrary windows to be -embedded in a text widget. -See EMBEDDED WINDOWS below for more details. -.PP -The fourth form of annotation allows Tk images to be embedded in a text -widget. -See EMBEDDED IMAGES below for more details. -.PP -.VS 8.4 -The text widget also has a built-in undo/redo mechanism. -See UNDO MECHANISM below for more details. -.VE 8.4 - -.SH INDICES -.PP -Many of the widget commands for texts take one or more indices -as arguments. -An index is a string used to indicate a particular place within -a text, such as a place to insert characters or one endpoint of a -range of characters to delete. -Indices have the syntax -.CS -\fIbase modifier modifier modifier ...\fR -.CE -Where \fIbase\fR gives a starting point and the \fImodifier\fRs -adjust the index from the starting point (e.g. move forward or -backward one character). Every index must contain a \fIbase\fR, -but the \fImodifier\fRs are optional. -.PP -The \fIbase\fR for an index must have one of the following forms: -.TP 12 -\fIline\fB.\fIchar\fR -Indicates \fIchar\fR'th character on line \fIline\fR. -Lines are numbered from 1 for consistency with other UNIX programs -that use this numbering scheme. -Within a line, characters are numbered from 0. -If \fIchar\fR is \fBend\fR then it refers to the newline character -that ends the line. -.TP 12 -\fB@\fIx\fB,\fIy\fR -Indicates the character that covers the pixel whose x and y coordinates -within the text's window are \fIx\fR and \fIy\fR. -.TP 12 -\fBend\fR -Indicates the end of the text (the character just after the last -newline). -.TP 12 -\fImark\fR -Indicates the character just after the mark whose name is \fImark\fR. -.TP 12 -\fItag\fB.first\fR -Indicates the first character in the text that has been tagged with -\fItag\fR. -This form generates an error if no characters are currently tagged -with \fItag\fR. -.TP 12 -\fItag\fB.last\fR -Indicates the character just after the last one in the text that has -been tagged with \fItag\fR. -This form generates an error if no characters are currently tagged -with \fItag\fR. -.TP 12 -\fIpathName\fR -Indicates the position of the embedded window whose name is -\fIpathName\fR. -This form generates an error if there is no embedded window -by the given name. -.TP 12 -\fIimageName\fR -Indicates the position of the embedded image whose name is -\fIimageName\fR. -This form generates an error if there is no embedded image -by the given name. -.PP -If the \fIbase\fP could match more than one of the above forms, such -as a \fImark\fP and \fIimageName\fP both having the same value, then -the form earlier in the above list takes precedence. -If modifiers follow the base index, each one of them must have one -of the forms listed below. Keywords such as \fBchars\fR and \fBwordend\fR -may be abbreviated as long as the abbreviation is unambiguous. -.TP -\fB+ \fIcount\fB chars\fR -Adjust the index forward by \fIcount\fR characters, moving to later -lines in the text if necessary. If there are fewer than \fIcount\fR -characters in the text after the current index, then set the index -to the last character in the text. -Spaces on either side of \fIcount\fR are optional. -.TP -\fB\- \fIcount\fB chars\fR -Adjust the index backward by \fIcount\fR characters, moving to earlier -lines in the text if necessary. If there are fewer than \fIcount\fR -characters in the text before the current index, then set the index -to the first character in the text. -Spaces on either side of \fIcount\fR are optional. -.TP -\fB+ \fIcount\fB lines\fR -Adjust the index forward by \fIcount\fR lines, retaining the same -character position within the line. If there are fewer than \fIcount\fR -lines after the line containing the current index, then set the index -to refer to the same character position on the last line of the text. -Then, if the line is not long enough to contain a character at the indicated -character position, adjust the character position to refer to the last -character of the line (the newline). -Spaces on either side of \fIcount\fR are optional. -.TP -\fB\- \fIcount\fB lines\fR -Adjust the index backward by \fIcount\fR lines, retaining the same -character position within the line. If there are fewer than \fIcount\fR -lines before the line containing the current index, then set the index -to refer to the same character position on the first line of the text. -Then, if the line is not long enough to contain a character at the indicated -character position, adjust the character position to refer to the last -character of the line (the newline). -Spaces on either side of \fIcount\fR are optional. -.TP -\fBlinestart\fR -Adjust the index to refer to the first character on the line. -.TP -\fBlineend\fR -Adjust the index to refer to the last character on the line (the newline). -.TP -\fBwordstart\fR -Adjust the index to refer to the first character of the word containing -the current index. A word consists of any number of adjacent characters -that are letters, digits, or underscores, or a single character that -is not one of these. -.TP -\fBwordend\fR -Adjust the index to refer to the character just after the last one of the -word containing the current index. If the current index refers to the last -character of the text then it is not modified. -.PP -If more than one modifier is present then they are applied in -left-to-right order. For example, the index ``\fBend \- 1 chars\fR'' -refers to the next-to-last character in the text and -``\fBinsert wordstart \- 1 c\fR'' refers to the character just before -the first one in the word containing the insertion cursor. - -.SH TAGS -.PP -The first form of annotation in text widgets is a tag. -A tag is a textual string that is associated with some of the characters -in a text. -Tags may contain arbitrary characters, but it is probably best to -avoid using the the characters `` '' (space), \fB+\fR, or \fB\-\fR: -these characters have special meaning in indices, so tags containing -them can't be used as indices. -There may be any number of tags associated with characters in a -text. -Each tag may refer to a single character, a range of characters, or -several ranges of characters. -An individual character may have any number of tags associated with it. -.PP -A priority order is defined among tags, and this order is used in -implementing some of the tag-related functions described below. -When a tag is defined (by associating it with characters or setting -its display options or binding commands to it), it is given -a priority higher than any existing tag. -The priority order of tags may be redefined using the -``\fIpathName \fBtag raise\fR'' and ``\fIpathName \fBtag lower\fR'' -widget commands. -.PP -Tags serve three purposes in text widgets. -First, they control the way information is displayed on the screen. -By default, characters are displayed as determined by the -\fBbackground\fR, \fBfont\fR, and \fBforeground\fR options for the -text widget. -However, display options may be associated with individual tags -using the ``\fIpathName \fBtag configure\fR'' widget command. -If a character has been tagged, then the display options associated -with the tag override the default display style. -The following options are currently supported for tags: -.TP -\fB\-background \fIcolor\fR -\fIColor\fR specifies the background color to use for characters -associated with the tag. -It may have any of the forms accepted by \fBTk_GetColor\fR. -.TP -\fB\-bgstipple \fIbitmap\fR -\fIBitmap\fR specifies a bitmap that is used as a stipple pattern -for the background. -It may have any of the forms accepted by \fBTk_GetBitmap\fR. -If \fIbitmap\fR hasn't been specified, or if it is specified -as an empty string, then a solid fill will be used for the -background. -.TP -\fB\-borderwidth \fIpixels\fR -\fIPixels\fR specifies the width of a 3-D border to draw around -the background. -It may have any of the forms accepted by \fBTk_GetPixels\fR. -This option is used in conjunction with the \fB\-relief\fR -option to give a 3-D appearance to the background for characters; -it is ignored unless the \fB\-background\fR option -has been set for the tag. -.TP -\fB\-elide \fIboolean\fR -\fIElide\fR specifies whether the data should be elided. -Elided data is not displayed and takes no space on screen, but further -on behaves just as normal data. -.TP -\fB\-fgstipple \fIbitmap\fR -\fIBitmap\fR specifies a bitmap that is used as a stipple pattern -when drawing text and other foreground information such as -underlines. -It may have any of the forms accepted by \fBTk_GetBitmap\fR. -If \fIbitmap\fR hasn't been specified, or if it is specified -as an empty string, then a solid fill will be used. -.TP -\fB\-font \fIfontName\fR -\fIFontName\fR is the name of a font to use for drawing characters. -It may have any of the forms accepted by \fBTk_GetFont\fR. -.TP -\fB\-foreground \fIcolor\fR -\fIColor\fR specifies the color to use when drawing text and other -foreground information such as underlines. -It may have any of the forms accepted by \fBTk_GetColor\fR. -.TP -\fB\-justify \fIjustify\fR -If the first character of a display line has a tag for which this -option has been specified, then \fIjustify\fR determines how to -justify the line. -It must be one of \fBleft\fR, \fBright\fR, or \fBcenter\fR. -If a line wraps, then the justification for each line on the -display is determined by the first character of that display line. -.TP -\fB\-lmargin1 \fIpixels\fR -If the first character of a text line has a tag for which this -option has been specified, then \fIpixels\fR specifies how -much the line should be indented from the left edge of the -window. -\fIPixels\fR may have any of the standard forms for screen -distances. -If a line of text wraps, this option only applies to the -first line on the display; the \fB\-lmargin2\fR option controls -the indentation for subsequent lines. -.TP -\fB\-lmargin2 \fIpixels\fR -If the first character of a display line has a tag for which this -option has been specified, and if the display line is not the -first for its text line (i.e., the text line has wrapped), then -\fIpixels\fR specifies how much the line should be indented from -the left edge of the window. -\fIPixels\fR may have any of the standard forms for screen -distances. -This option is only used when wrapping is enabled, and it only -applies to the second and later display lines for a text line. -.TP -\fB\-offset \fIpixels\fR -\fIPixels\fR specifies an amount by which the text's baseline -should be offset vertically from the baseline of the overall -line, in pixels. -For example, a positive offset can be used for superscripts -and a negative offset can be used for subscripts. -\fIPixels\fR may have any of the standard forms for screen -distances. -.TP -\fB\-overstrike \fIboolean\fR -Specifies whether or not to draw a horizontal rule through -the middle of characters. -\fIBoolean\fR may have any of the forms accepted by \fBTk_GetBoolean\fR. -.TP -\fB\-relief \fIrelief\fR -\fIRelief\fR specifies the 3-D relief to use for drawing backgrounds, -in any of the forms accepted by \fBTk_GetRelief\fR. -This option is used in conjunction with the \fB\-borderwidth\fR -option to give a 3-D appearance to the background for characters; -it is ignored unless the \fB\-background\fR option -has been set for the tag. -.TP -\fB\-rmargin \fIpixels\fR -If the first character of a display line has a tag for which this -option has been specified, then \fIpixels\fR specifies how wide -a margin to leave between the end of the line and the right -edge of the window. -\fIPixels\fR may have any of the standard forms for screen -distances. -This option is only used when wrapping is enabled. -If a text line wraps, the right margin for each line on the -display is determined by the first character of that display -line. -.TP -\fB\-spacing1 \fIpixels\fR -\fIPixels\fR specifies how much additional space should be -left above each text line, using any of the standard forms for -screen distances. -If a line wraps, this option only applies to the first -line on the display. -.TP -\fB\-spacing2 \fIpixels\fR -For lines that wrap, this option specifies how much additional -space to leave between the display lines for a single text line. -\fIPixels\fR may have any of the standard forms for screen -distances. -.TP -\fB\-spacing3 \fIpixels\fR -\fIPixels\fR specifies how much additional space should be -left below each text line, using any of the standard forms for -screen distances. -If a line wraps, this option only applies to the last -line on the display. -.TP -\fB\-tabs \fItabList\fR -\fITabList\fR specifies a set of tab stops in the same form -as for the \fB\-tabs\fR option for the text widget. This -option only applies to a display line if it applies to the -first character on that display line. -If this option is specified as an empty string, it cancels -the option, leaving it unspecified for the tag (the default). -If the option is specified as a non-empty string that is -an empty list, such as \fB\-tags\0{\0}\fR, then it requests -default 8-character tabs as described for the \fBtags\fR -widget option. -.TP -\fB\-underline \fIboolean\fR -\fIBoolean\fR specifies whether or not to draw an underline underneath -characters. -It may have any of the forms accepted by \fBTk_GetBoolean\fR. -.TP -\fB\-wrap \fImode\fR -\fIMode\fR specifies how to handle lines that are wider than the -text's window. -It has the same legal values as the \fB\-wrap\fR option -for the text widget: \fBnone\fR, \fBchar\fR, or \fBword\fR. -If this tag option is specified, it overrides the \fB\-wrap\fR option -for the text widget. -.PP -If a character has several tags associated with it, and if their -display options conflict, then the options of the highest priority -tag are used. -If a particular display option hasn't been specified for a -particular tag, or if it is specified as an empty string, then -that option will never be used; the next-highest-priority -tag's option will used instead. -If no tag specifies a particular display option, then the default -style for the widget will be used. -.PP -The second purpose for tags is event bindings. -You can associate bindings with a tag in much the same way you can -associate bindings with a widget class: whenever particular X -events occur on characters with the given tag, a given -Tcl command will be executed. -Tag bindings can be used to give behaviors to ranges of characters; -among other things, this allows hypertext-like -features to be implemented. -For details, see the description of the \fBtag bind\fR widget -command below. -.PP -The third use for tags is in managing the selection. -See THE SELECTION below. - -.SH MARKS -.PP -The second form of annotation in text widgets is a mark. -Marks are used for remembering particular places in a text. -They are something like tags, in that they have names and -they refer to places in the file, but a mark isn't associated -with particular characters. -Instead, a mark is associated with the gap between two characters. -Only a single position may be associated with a mark at any given -time. -If the characters around a mark are deleted the mark will still -remain; it will just have new neighbor characters. -In contrast, if the characters containing a tag are deleted then -the tag will no longer have an association with characters in -the file. -Marks may be manipulated with the ``\fIpathName \fBmark\fR'' widget -command, and their current locations may be determined by using the -mark name as an index in widget commands. -.PP -Each mark also has a \fIgravity\fR, which is either \fBleft\fR or -\fBright\fR. -The gravity for a mark specifies what happens to the mark when -text is inserted at the point of the mark. -If a mark has left gravity, then the mark is treated as if it -were attached to the character on its left, so the mark will -remain to the left of any text inserted at the mark position. -If the mark has right gravity, new text inserted at the mark -position will appear to the left of the mark (so that the mark -remains rightmost). The gravity for a mark defaults to \fBright\fR. -.PP -The name space for marks is different from that for tags: the -same name may be used for both a mark and a tag, but they will refer -to different things. -.PP -Two marks have special significance. -First, the mark \fBinsert\fR is associated with the insertion cursor, -as described under THE INSERTION CURSOR below. -Second, the mark \fBcurrent\fR is associated with the character -closest to the mouse and is adjusted automatically to track the -mouse position and any changes to the text in the widget (one -exception: \fBcurrent\fR is not updated in response to mouse -motions if a mouse button is down; the update will be deferred -until all mouse buttons have been released). -Neither of these special marks may be deleted. - -.SH "EMBEDDED WINDOWS" -.PP -The third form of annotation in text widgets is an embedded window. -Each embedded window annotation causes a window to be displayed -at a particular point in the text. -There may be any number of embedded windows in a text widget, -and any widget may be used as an embedded window (subject to the -usual rules for geometry management, which require the text window -to be the parent of the embedded window or a descendant of its -parent). -The embedded window's position on the screen will be updated as the -text is modified or scrolled, and it will be mapped and unmapped as -it moves into and out of the visible area of the text widget. -Each embedded window occupies one character's worth of index space -in the text widget, and it may be referred to either by the name -of its embedded window or by its position in the widget's -index space. -If the range of text containing the embedded window is deleted then -the window is destroyed. -.PP -When an embedded window is added to a text widget with the -\fBwindow create\fR widget command, several configuration -options may be associated with it. -These options may be modified later with the \fBwindow configure\fR -widget command. -The following options are currently supported: -.TP -\fB\-align \fIwhere\fR -If the window is not as tall as the line in which it is displayed, -this option determines where the window is displayed in the line. -\fIWhere\fR must have one of the values \fBtop\fR (align the top of the window -with the top of the line), \fBcenter\fR (center the window -within the range of the line), \fBbottom\fR (align the bottom of the -window with the bottom of the line's area), -or \fBbaseline\fR (align the bottom of the window with the baseline -of the line). -.TP -\fB\-create \fIscript\fR -Specifies a Tcl script that may be evaluated to create the window -for the annotation. -If no \fB\-window\fR option has been specified for the annotation -this script will be evaluated when the annotation is about to -be displayed on the screen. -\fIScript\fR must create a window for the annotation and return -the name of that window as its result. -If the annotation's window should ever be deleted, \fIscript\fR -will be evaluated again the next time the annotation is displayed. -.TP -\fB\-padx \fIpixels\fR -\fIPixels\fR specifies the amount of extra space to leave on -each side of the embedded window. -It may have any of the usual forms defined for a screen distance. -.TP -\fB\-pady \fIpixels\fR -\fIPixels\fR specifies the amount of extra space to leave on -the top and on the bottom of the embedded window. -It may have any of the usual forms defined for a screen distance. -.TP -\fB\-stretch \fIboolean\fR -If the requested height of the embedded window is less than the -height of the line in which it is displayed, this option can be -used to specify whether the window should be stretched vertically -to fill its line. -If the \fB\-pady\fR option has been specified as well, then the -requested padding will be retained even if the window is -stretched. -.TP -\fB\-window \fIpathName\fR -Specifies the name of a window to display in the annotation. - -.SH "EMBEDDED IMAGES" -.PP -The final form of annotation in text widgets is an embedded image. -Each embedded image annotation causes an image to be displayed -at a particular point in the text. -There may be any number of embedded images in a text widget, -and a particular image may be embedded in multiple places in the same -text widget. -The embedded image's position on the screen will be updated as the -text is modified or scrolled. -Each embedded image occupies one character's worth of index space -in the text widget, and it may be referred to either by -its position in the widget's index space, or the name it is assigned -when the image is inserted into the text widget widh \fBimage create\fP. -If the range of text containing the embedded image is deleted then -that copy of the image is removed from the screen. -.PP -When an embedded image is added to a text widget with the \fBimage -create\fR widget command, a name unique to this instance of the image -is returned. This name may then be used to refer to this image -instance. The name is taken to be the value of the \fB-name\fP option -(described below). If the \fB-name\fP option is not provided, the -\fB-image\fP name is used instead. If the \fIimageName\fP is already -in use in the text widget, then \fB#\fInn\fR is added to the end of the -\fIimageName\fP, where \fInn\fP is an arbitrary integer. This insures -the \fIimageName\fP is unique. -Once this name is assigned to this instance of the image, it does not -change, even though the \fB-image\fP or \fB-name\fP values can be changed -with \fBimage configure\fP. -.PP -When an embedded image is added to a text widget with the -\fBimage create\fR widget command, several configuration -options may be associated with it. -These options may be modified later with the \fBimage configure\fR -widget command. -The following options are currently supported: -.TP -\fB\-align \fIwhere\fR -If the image is not as tall as the line in which it is displayed, -this option determines where the image is displayed in the line. -\fIWhere\fR must have one of the values \fBtop\fR (align the top of the image -with the top of the line), \fBcenter\fR (center the image -within the range of the line), \fBbottom\fR (align the bottom of the -image with the bottom of the line's area), -or \fBbaseline\fR (align the bottom of the image with the baseline -of the line). -.TP -\fB\-image \fIimage\fR -Specifies the name of the Tk image to display in the annotation. -If \fIimage\fP is not a valid Tk image, then an error is returned. -.TP -\fB\-name \fIImageName\fR -Specifies the name by which this image instance may be referenced in -the text widget. If \fIImageName\fP is not supplied, then the -name of the Tk image is used instead. -If the \fIimageName\fP is already in use, \fI#nn\fP is appended to -the end of the name as described above. -.TP -\fB\-padx \fIpixels\fR -\fIPixels\fR specifies the amount of extra space to leave on -each side of the embedded image. -It may have any of the usual forms defined for a screen distance. -.TP -\fB\-pady \fIpixels\fR -\fIPixels\fR specifies the amount of extra space to leave on -the top and on the bottom of the embedded image. -It may have any of the usual forms defined for a screen distance. - -.SH "THE SELECTION" -.PP -Selection support is implemented via tags. -If the \fBexportSelection\fR option for the text widget is true -then the \fBsel\fR tag will be associated with the selection: -.IP [1] -Whenever characters are tagged with \fBsel\fR the text widget -will claim ownership of the selection. -.IP [2] -Attempts to retrieve the -selection will be serviced by the text widget, returning all the -characters with the \fBsel\fR tag. -.IP [3] -If the selection is claimed away by another application or by another -window within this application, then the \fBsel\fR tag will be removed -from all characters in the text. -.IP [4] -Whenever the \fBsel\fR tag range changes a virtual event -\fB<>\fR is generated. -.PP -The \fBsel\fR tag is automatically defined when a text widget is -created, and it may not be deleted with the ``\fIpathName \fBtag delete\fR'' -widget command. Furthermore, the \fBselectBackground\fR, -\fBselectBorderWidth\fR, and \fBselectForeground\fR options for -the text widget are tied to the \fB\-background\fR, -\fB\-borderwidth\fR, and \fB\-foreground\fR options for the \fBsel\fR -tag: changes in either will automatically be reflected in the -other. - -.SH "THE INSERTION CURSOR" -.PP -The mark named \fBinsert\fR has special significance in text widgets. -It is defined automatically when a text widget is created and it -may not be unset with the ``\fIpathName \fBmark unset\fR'' widget -command. -The \fBinsert\fR mark represents the position of the insertion -cursor, and the insertion cursor will automatically be drawn at -this point whenever the text widget has the input focus. - -.SH "THE MODIFIED FLAG" -The text widget can keep track of changes to the content of the widget -by means of the modified flag. Inserting or deleting text will set -this flag. The flag can be queried, set and cleared programatically -as well. Whenever the flag changes state a \fB<>\fR virtual -event is generated. See the \fBedit modified\fR widget command for -more details. - -.SH "THE UNDO MECHANISM" -.PP -.VS 8.4 -The text widget has an unlimited undo and redo mechanism (when the -\fB-undo\fR widget option is true) which records every insert and -delete action on a stack. -.PP -Boundaries (called "separators") are inserted between edit actions. -The purpose of these separators is to group inserts and deletes into -one compound edit action. When undoing a change everything between -two separators will be undone. The undone changes are then moved to -the redo stack, so that an undone edit can be redone again. The redo -stack is cleared whenever new edit actions are recorded on the undo -stack. The undo and redo stacks can be cleared to keep their depth -under control. -.PP -Separators are inserted automatically when the \fB-autoseparators\fR -widget option is true. You can insert separators programatically as -well. If a separator is already present at the top of the undo stack -no other will be inserted. That means that two separators on the undo -stack are always separated by at least one insert or delete action. -.PP -The undo mechanism is also linked to the modified flag. This means -that undoing or redoing changes can take a modified text widget back -to the unmodified state or vice versa. The modified flag will be set -automatically to the appropriate state. This automatic coupling -does not work when the modified flag has been set by the user, until -the flag has been reset again. -.PP -See below for the \fBedit\fR widget command that controls the undo -mechanism. -.VE 8.4 - -.SH "WIDGET COMMAND" -.PP -The \fBtext\fR command creates a new Tcl command whose -name is the same as the path name of the text's window. This -command may be used to invoke various -operations on the widget. It has the following general form: -.CS -\fIpathName option \fR?\fIarg arg ...\fR? -.CE -\fIPathName\fR is the name of the command, which is the same as -the text widget's path name. \fIOption\fR and the \fIarg\fRs -determine the exact behavior of the command. The following -commands are possible for text widgets: -.TP -\fIpathName \fBbbox \fIindex\fR -Returns a list of four elements describing the screen area -of the character given by \fIindex\fR. -The first two elements of the list give the x and y coordinates -of the upper-left corner of the area occupied by the -character, and the last two elements give the width and height -of the area. -If the character is only partially visible on the screen, then -the return value reflects just the visible part. -If the character is not visible on the screen then the return -value is an empty list. -.TP -\fIpathName \fBcget\fR \fIoption\fR -Returns the current value of the configuration option given -by \fIoption\fR. -\fIOption\fR may have any of the values accepted by the \fBtext\fR -command. -.TP -\fIpathName \fBcompare\fR \fIindex1 op index2\fR -Compares the indices given by \fIindex1\fR and \fIindex2\fR according -to the relational operator given by \fIop\fR, and returns 1 if -the relationship is satisfied and 0 if it isn't. -\fIOp\fR must be one of the operators <, <=, ==, >=, >, or !=. -If \fIop\fR is == then 1 is returned if the two indices refer to -the same character, if \fIop\fR is < then 1 is returned if \fIindex1\fR -refers to an earlier character in the text than \fIindex2\fR, and -so on. -.TP -\fIpathName \fBconfigure\fR ?\fIoption\fR? \fI?value option value ...\fR? -Query or modify the configuration options of the widget. -If no \fIoption\fR is specified, returns a list describing all of -the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for -information on the format of this list). If \fIoption\fR is specified -with no \fIvalue\fR, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no \fIoption\fR is specified). If -one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given widget option(s) to have the given value(s); in -this case the command returns an empty string. -\fIOption\fR may have any of the values accepted by the \fBtext\fR -command. -.TP -\fIpathName \fBdebug \fR?\fIboolean\fR? -If \fIboolean\fR is specified, then it must have one of the true or -false values accepted by Tcl_GetBoolean. -If the value is a true one then internal consistency checks will be -turned on in the B-tree code associated with text widgets. -If \fIboolean\fR has a false value then the debugging checks will -be turned off. -In either case the command returns an empty string. -If \fIboolean\fR is not specified then the command returns \fBon\fR -or \fBoff\fR to indicate whether or not debugging is turned on. -There is a single debugging switch shared by all text widgets: turning -debugging on or off in any widget turns it on or off for all widgets. -For widgets with large amounts of text, the consistency checks may -cause a noticeable slow-down. -.PP -.VS 8.4 -When debugging is turned on, the drawing routines of the text widget -set the global variables \fBtk_textRedraw\fR and \fBtk_textRelayout\fR -to the lists of indices that are redrawn. The values of these variables -are tested by Tk's test suite. -.VE 8.4 -.TP -\fIpathName \fBdelete \fIindex1 \fR?\fIindex2 ...\fR? -Delete a range of characters from the text. -If both \fIindex1\fR and \fIindex2\fR are specified, then delete -all the characters starting with the one given by \fIindex1\fR -and stopping just before \fIindex2\fR (i.e. the character at -\fIindex2\fR is not deleted). -If \fIindex2\fR doesn't specify a position later in the text -than \fIindex1\fR then no characters are deleted. -If \fIindex2\fR isn't specified then the single character at -\fIindex1\fR is deleted. -It is not allowable to delete characters in a way that would leave -the text without a newline as the last character. -The command returns an empty string. -.VS 8.4 -If more indices are given, multiple ranges of text will be deleted. -All indices are first checked for validity before any deletions are made. -They are sorted and the text is removed from the last range to the -first range to deleted text does not cause a undesired index shifting -side-effects. If multiple ranges with the same start index are given, -then the longest range is used. If overlapping ranges are given, then -they will be merged into spans that do not cause deletion of text -outside the given ranges due to text shifted during deletion. -.VE 8.4 -.TP -\fIpathName \fBdlineinfo \fIindex\fR -Returns a list with five elements describing the area occupied -by the display line containing \fIindex\fR. -The first two elements of the list give the x and y coordinates -of the upper-left corner of the area occupied by the -line, the third and fourth elements give the width and height -of the area, and the fifth element gives the position of the baseline -for the line, measured down from the top of the area. -All of this information is measured in pixels. -If the current wrap mode is \fBnone\fR and the line extends beyond -the boundaries of the window, -the area returned reflects the entire area of the line, including the -portions that are out of the window. -If the line is shorter than the full width of the window then the -area returned reflects just the portion of the line that is occupied -by characters and embedded windows. -If the display line containing \fIindex\fR is not visible on -the screen then the return value is an empty list. -.TP -\fIpathName \fBdump \fR?\fIswitches\fR? \fIindex1 \fR?\fIindex2\fR? -Return the contents of the text widget from \fIindex1\fR up to, -but not including \fIindex2\fR, -including the text and -information about marks, tags, and embedded windows. -If \fIindex2\fR is not specified, then it defaults to -one character past \fIindex1\fR. The information is returned -in the following format: -.LP -.RS -\fIkey1 value1 index1 key2 value2 index2\fR ... -.LP -The possible \fIkey\fP values are \fBtext\fP, \fBmark\fP, -\fBtagon\fP, \fBtagoff\fP, and \fBwindow\fP. The corresponding -\fIvalue\fP is the text, mark name, tag name, or window name. -The \fIindex\fP information is the index of the -start of the text, the mark, the tag transition, or the window. -One or more of the following switches (or abbreviations thereof) -may be specified to control the dump: -.TP -\fB\-all\fR -Return information about all elements: text, marks, tags, images and windows. -This is the default. -.TP -\fB\-command \fIcommand\fR -Instead of returning the information as the result of the dump operation, -invoke the \fIcommand\fR on each element of the text widget within the range. -The command has three arguments appended to it before it is evaluated: -the \fIkey\fP, \fIvalue\fP, and \fIindex\fP. -.TP -\fB\-image\fR -Include information about images in the dump results. -.TP -\fB\-mark\fR -Include information about marks in the dump results. -.TP -\fB\-tag\fR -Include information about tag transitions in the dump results. Tag -information is returned as \fBtagon\fP and \fBtagoff\fP elements that -indicate the begin and end of each range of each tag, respectively. -.TP -\fB\-text\fR -Include information about text in the dump results. The value is the -text up to the next element or the end of range indicated by \fIindex2\fR. -A text element does not span newlines. A multi-line block of text that -contains no marks or tag transitions will still be dumped as a set -of text seqments that each end with a newline. The newline is part -of the value. -.TP -\fB\-window\fR -Include information about embedded windows in the dump results. -The value of a window is its Tk pathname, unless the window -has not been created yet. (It must have a create script.) -In this case an empty string is returned, and you must query the -window by its index position to get more information. -.RE -.TP -\fIpathName \fBedit \fIoption \fR?\fIarg arg ...\fR? -.VS 8.4 -This command controls the undo mechanism and the modified flag. The -exact behavior of the command depends on the \fIoption\fR argument -that follows the \fBedit\fR argument. The following forms of the -command are currently supported: -.RS -.TP -\fIpathName \fBedit modified ?\fIboolean\fR? -If \fIboolean\fR is not specified, returns the modified flag of the -widget. The insert, delete, edit undo and edit redo commands or the -user can set or clear the modified flag. If \fIboolean\fR is -specified, sets the modified flag of the widget to \fIboolean\fR. -.TP -\fIpathName \fBedit redo\fR -When the \fB-undo\fR option is true, reapplies the last undone edits -provided no other edits were done since then. Generates an error when -the redo stack is empty. Does nothing when the \fB-undo\fR option is -false. -.TP -\fIpathName \fBedit reset\fR -Clears the undo and redo stacks. -.TP -\fIpathName \fBedit separator\fR -Inserts a separator (boundary) on the undo stack. Does nothing when -the \fB-undo\fR option is false. -.TP -\fIpathName \fBedit undo\fR -Undoes the last edit action when the \fB-undo\fR option is true. An -edit action is defined as all the insert and delete commands that are -recorded on the undo stack in between two separators. Generates an -error when the undo stack is empty. Does nothing when the \fB-undo\fR -option is false. -.RE -.VE 8.4 -.TP -\fIpathName \fBget \fIindex1 \fR?\fIindex2 ...\fR? -Return a range of characters from the text. -The return value will be all the characters in the text starting -with the one whose index is \fIindex1\fR and ending just before -the one whose index is \fIindex2\fR (the character at \fIindex2\fR -will not be returned). -If \fIindex2\fR is omitted then the single character at \fIindex1\fR -is returned. -If there are no characters in the specified range (e.g. \fIindex1\fR -is past the end of the file or \fIindex2\fR is less than or equal -to \fIindex1\fR) then an empty string is returned. -If the specified range contains embedded windows, no information -about them is included in the returned string. -.VS 8.4 -If multiple index pairs are given, multiple ranges of text will be returned -in a list. Invalid ranges will not be represented with empty strings in -the list. The ranges are returned in the order passed to \fBget\fR. -.VE 8.4 -.TP -\fIpathName \fBimage \fIoption \fR?\fIarg arg ...\fR? -This command is used to manipulate embedded images. -The behavior of the command depends on the \fIoption\fR argument -that follows the \fBtag\fR argument. -The following forms of the command are currently supported: -.RS -.TP -\fIpathName \fBimage cget\fR \fIindex option\fR -Returns the value of a configuration option for an embedded image. -\fIIndex\fR identifies the embedded image, and \fIoption\fR -specifies a particular configuration option, which must be one of -the ones listed in the section EMBEDDED IMAGES. -.TP -\fIpathName \fBimage configure \fIindex\fR ?\fIoption value ...\fR? -Query or modify the configuration options for an embedded image. -If no \fIoption\fR is specified, returns a list describing all of -the available options for the embedded image at \fIindex\fR -(see \fBTk_ConfigureInfo\fR for information on the format of this list). -If \fIoption\fR is specified with no \fIvalue\fR, then the command -returns a list describing the one named option (this list will be -identical to the corresponding sublist of the value returned if no -\fIoption\fR is specified). -If one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given option(s) to have the given value(s); in -this case the command returns an empty string. -See EMBEDDED IMAGES for information on the options that -are supported. -.TP -\fIpathName \fBimage create \fIindex\fR ?\fIoption value ...\fR? -This command creates a new image annotation, which will appear -in the text at the position given by \fIindex\fR. -Any number of \fIoption\-value\fR pairs may be specified to -configure the annotation. -Returns a unique identifier that may be used as an index to refer to -this image. -See EMBEDDED IMAGES for information on the options that -are supported, and a description of the identifier returned. -.TP -\fIpathName \fBimage names\fR -Returns a list whose elements are the names of all image instances currently -embedded in \fIwindow\fR. -.RE -.TP -\fIpathName \fBindex \fIindex\fR -Returns the position corresponding to \fIindex\fR in the form -\fIline.char\fR where \fIline\fR is the line number and \fIchar\fR -is the character number. -\fIIndex\fR may have any of the forms described under INDICES above. -.TP -\fIpathName \fBinsert \fIindex chars \fR?\fItagList chars tagList ...\fR? -Inserts all of the \fIchars\fR arguments just before the character at -\fIindex\fR. -If \fIindex\fR refers to the end of the text (the character after -the last newline) then the new text is inserted just before the -last newline instead. -If there is a single \fIchars\fR argument and no \fItagList\fR, then -the new text will receive any tags that are present on both the -character before and the character after the insertion point; if a tag -is present on only one of these characters then it will not be -applied to the new text. -If \fItagList\fR is specified then it consists of a list of -tag names; the new characters will receive all of the tags in -this list and no others, regardless of the tags present around -the insertion point. -If multiple \fIchars\fR\-\fItagList\fR argument pairs are present, -they produce the same effect as if a separate \fBinsert\fR widget -command had been issued for each pair, in order. -The last \fItagList\fR argument may be omitted. -.TP -\fIpathName \fBmark \fIoption \fR?\fIarg arg ...\fR? -This command is used to manipulate marks. The exact behavior of -the command depends on the \fIoption\fR argument that follows -the \fBmark\fR argument. The following forms of the command -are currently supported: -.RS -.TP -\fIpathName \fBmark gravity \fImarkName\fR ?\fIdirection\fR? -If \fIdirection\fR is not specified, returns \fBleft\fR or \fBright\fR -to indicate which of its adjacent characters \fImarkName\fR is attached -to. -If \fIdirection\fR is specified, it must be \fBleft\fR or \fBright\fR; -the gravity of \fImarkName\fR is set to the given value. -.TP -\fIpathName \fBmark names\fR -Returns a list whose elements are the names of all the marks that -are currently set. -.TP -\fIpathName \fBmark next \fIindex\fR -Returns the name of the next mark at or after \fIindex\fR. -If \fIindex\fR is specified in numerical form, then the search for -the next mark begins at that index. -If \fIindex\fR is the name of a mark, then the search for -the next mark begins immediately after that mark. -This can still return a mark at the same position if -there are multiple marks at the same index. -These semantics mean that the \fBmark next\fP operation can be used to -step through all the marks in a text widget in the same order -as the mark information returned by the \fBdump\fP operation. -If a mark has been set to the special \fBend\fP index, -then it appears to be \fIafter\fP \fBend\fP with respect to the \fBmark next\fP operation. -An empty string is returned if there are no marks after \fIindex\fR. -.TP -\fIpathName \fBmark previous \fIindex\fR -Returns the name of the mark at or before \fIindex\fR. -If \fIindex\fR is specified in numerical form, then the search for -the previous mark begins with the character just before that index. -If \fIindex\fR is the name of a mark, then the search for -the next mark begins immediately before that mark. -This can still return a mark at the same position if -there are multiple marks at the same index. -These semantics mean that the \fBmark previous\fP operation can be used to -step through all the marks in a text widget in the reverse order -as the mark information returned by the \fBdump\fP operation. -An empty string is returned if there are no marks before \fIindex\fR. -.TP -\fIpathName \fBmark set \fImarkName index\fR -Sets the mark named \fImarkName\fR to a position just before the -character at \fIindex\fR. -If \fImarkName\fR already exists, it is moved from its old position; -if it doesn't exist, a new mark is created. -This command returns an empty string. -.TP -\fIpathName \fBmark unset \fImarkName \fR?\fImarkName markName ...\fR? -Remove the mark corresponding to each of the \fImarkName\fR arguments. -The removed marks will not be usable in indices and will not be -returned by future calls to ``\fIpathName \fBmark names\fR''. -This command returns an empty string. -.RE -.TP -\fIpathName \fBscan\fR \fIoption args\fR -This command is used to implement scanning on texts. It has -two forms, depending on \fIoption\fR: -.RS -.TP -\fIpathName \fBscan mark \fIx y\fR -Records \fIx\fR and \fIy\fR and the current view in the text window, -for use in conjunction with later \fBscan dragto\fR commands. -Typically this command is associated with a mouse button press in -the widget. It returns an empty string. -.TP -\fIpathName \fBscan dragto \fIx y\fR -This command computes the difference between its \fIx\fR and \fIy\fR -arguments and the \fIx\fR and \fIy\fR arguments to the last -\fBscan mark\fR command for the widget. -It then adjusts the view by 10 times the difference in coordinates. -This command is typically associated -with mouse motion events in the widget, to produce the effect of -dragging the text at high speed through the window. The return -value is an empty string. -.RE -.TP -\fIpathName \fBsearch \fR?\fIswitches\fR? \fIpattern index \fR?\fIstopIndex\fR? -Searches the text in \fIpathName\fR starting at \fIindex\fR for a range -of characters that matches \fIpattern\fR. -If a match is found, the index of the first character in the match is -returned as result; otherwise an empty string is returned. -One or more of the following switches (or abbreviations thereof) -may be specified to control the search: -.RS -.TP -\fB\-forwards\fR -The search will proceed forward through the text, finding the first -matching range starting at or after the position given by \fIindex\fR. -This is the default. -.TP -\fB\-backwards\fR -The search will proceed backward through the text, finding the -matching range closest to \fIindex\fR whose first character -is before \fIindex\fR. -.TP -\fB\-exact\fR -Use exact matching: the characters in the matching range must be -identical to those in \fIpattern\fR. -This is the default. -.TP -\fB\-regexp\fR -Treat \fIpattern\fR as a regular expression and match it against -the text using the rules for regular expressions (see the \fBregexp\fR -command for details). -.TP -\fB\-nocase\fR -Ignore case differences between the pattern and the text. -.TP -\fB\-count\fI varName\fR -The argument following \fB\-count\fR gives the name of a variable; -if a match is found, the number of index positions between beginning and -end of the matching range will be stored in the variable. If there are no -embedded images or windows in the matching range, this is equivalent to the -number of characters matched. In either case, the range \fImatchIdx\fR to -\fImatchIdx + $count chars\fR will return the entire matched text. -.TP -\fB\-elide\fR -Find elidden (hidden) text as well. By default only displayed text is -searched. -.TP -\fB\-\|\-\fR -This switch has no effect except to terminate the list of switches: -the next argument will be treated as \fIpattern\fR even if it starts -with \fB\-\fR. -.LP -The matching range must be entirely within a single line of text. -For regular expression matching the newlines are removed from the ends -of the lines before matching: use the \fB$\fR feature in regular -expressions to match the end of a line. -For exact matching the newlines are retained. -If \fIstopIndex\fR is specified, the search stops at that index: -for forward searches, no match at or after \fIstopIndex\fR will -be considered; for backward searches, no match earlier in the -text than \fIstopIndex\fR will be considered. -If \fIstopIndex\fR is omitted, the entire text will be searched: -when the beginning or end of the text is reached, the search -continues at the other end until the starting location is reached -again; if \fIstopIndex\fR is specified, no wrap-around will occur. -.RE -.TP -\fIpathName \fBsee \fIindex\fR -Adjusts the view in the window so that the character given by \fIindex\fR -is completely visible. -If \fIindex\fR is already visible then the command does nothing. -If \fIindex\fR is a short distance out of view, the command -adjusts the view just enough to make \fIindex\fR visible at the -edge of the window. -If \fIindex\fR is far out of view, then the command centers -\fIindex\fR in the window. -.TP -\fIpathName \fBtag \fIoption \fR?\fIarg arg ...\fR? -This command is used to manipulate tags. The exact behavior of the -command depends on the \fIoption\fR argument that follows the -\fBtag\fR argument. The following forms of the command are currently -supported: -.RS -.TP -\fIpathName \fBtag add \fItagName index1 \fR?\fIindex2 index1 index2 ...\fR? -Associate the tag \fItagName\fR with all of the characters starting -with \fIindex1\fR and ending just before -\fIindex2\fR (the character at \fIindex2\fR isn't tagged). -A single command may contain any number of \fIindex1\fR\-\fIindex2\fR -pairs. -If the last \fIindex2\fR is omitted then the single character at -\fIindex1\fR is tagged. -If there are no characters in the specified range (e.g. \fIindex1\fR -is past the end of the file or \fIindex2\fR is less than or equal -to \fIindex1\fR) then the command has no effect. -.TP -\fIpathName \fBtag bind \fItagName\fR ?\fIsequence\fR? ?\fIscript\fR? -This command associates \fIscript\fR with the tag given by -\fItagName\fR. -Whenever the event sequence given by \fIsequence\fR occurs for a -character that has been tagged with \fItagName\fR, -the script will be invoked. -This widget command is similar to the \fBbind\fR command except that -it operates on characters in a text rather than entire widgets. -See the \fBbind\fR manual entry for complete details -on the syntax of \fIsequence\fR and the substitutions performed -on \fIscript\fR before invoking it. -If all arguments are specified then a new binding is created, replacing -any existing binding for the same \fIsequence\fR and \fItagName\fR -(if the first character of \fIscript\fR is ``+'' then \fIscript\fR -augments an existing binding rather than replacing it). -In this case the return value is an empty string. -If \fIscript\fR is omitted then the command returns the \fIscript\fR -associated with \fItagName\fR and \fIsequence\fR (an error occurs -if there is no such binding). -If both \fIscript\fR and \fIsequence\fR are omitted then the command -returns a list of all the sequences for which bindings have been -defined for \fItagName\fR. -.RS -.PP -.VS -The only events for which bindings may be specified are those related -to the mouse and keyboard (such as \fBEnter\fR, \fBLeave\fR, -\fBButtonPress\fR, \fBMotion\fR, and \fBKeyPress\fR) or virtual events. -Event bindings for a text widget use the \fBcurrent\fR mark described -under MARKS above. An \fBEnter\fR event triggers for a tag when the tag -first becomes present on the current character, and a \fBLeave\fR event -triggers for a tag when it ceases to be present on the current character. -\fBEnter\fR and \fBLeave\fR events can happen either because the -\fBcurrent\fR mark moved or because the character at that position -changed. Note that these events are different than \fBEnter\fR and -\fBLeave\fR events for windows. Mouse and keyboard events are directed -to the current character. If a virtual event is used in a binding, that -binding can trigger only if the virtual event is defined by an underlying -mouse-related or keyboard-related event. -.VE -.PP -It is possible for the current character to have multiple tags, -and for each of them to have a binding for a particular event -sequence. -When this occurs, one binding is invoked for each tag, in order -from lowest-priority to highest priority. -If there are multiple matching bindings for a single tag, then -the most specific binding is chosen (see the manual entry for -the \fBbind\fR command for details). -\fBcontinue\fR and \fBbreak\fR commands within binding scripts -are processed in the same way as for bindings created with -the \fBbind\fR command. -.PP -If bindings are created for the widget as a whole using the -\fBbind\fR command, then those bindings will supplement the -tag bindings. -The tag bindings will be invoked first, followed by bindings -for the window as a whole. -.RE -.TP -\fIpathName \fBtag cget\fR \fItagName option\fR -This command returns the current value of the option named \fIoption\fR -associated with the tag given by \fItagName\fR. -\fIOption\fR may have any of the values accepted by the \fBtag configure\fR -widget command. -.TP -\fIpathName \fBtag configure \fItagName\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? -This command is similar to the \fBconfigure\fR widget command except -that it modifies options associated with the tag given by \fItagName\fR -instead of modifying options for the overall text widget. -If no \fIoption\fR is specified, the command returns a list describing -all of the available options for \fItagName\fR (see \fBTk_ConfigureInfo\fR -for information on the format of this list). -If \fIoption\fR is specified with no \fIvalue\fR, then the command returns -a list describing the one named option (this list will be identical to -the corresponding sublist of the value returned if no \fIoption\fR -is specified). -If one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given option(s) to have the given value(s) in \fItagName\fR; -in this case the command returns an empty string. -See TAGS above for details on the options available for tags. -.TP -\fIpathName \fBtag delete \fItagName \fR?\fItagName ...\fR? -Deletes all tag information for each of the \fItagName\fR -arguments. -The command removes the tags from all characters in the file -and also deletes any other information associated with the tags, -such as bindings and display information. -The command returns an empty string. -.TP -\fIpathName\fB tag lower \fItagName \fR?\fIbelowThis\fR? -Changes the priority of tag \fItagName\fR so that it is just lower -in priority than the tag whose name is \fIbelowThis\fR. -If \fIbelowThis\fR is omitted, then \fItagName\fR's priority -is changed to make it lowest priority of all tags. -.TP -\fIpathName \fBtag names \fR?\fIindex\fR? -Returns a list whose elements are the names of all the tags that -are active at the character position given by \fIindex\fR. -If \fIindex\fR is omitted, then the return value will describe -all of the tags that exist for the text (this includes all tags -that have been named in a ``\fIpathName \fBtag\fR'' widget -command but haven't been deleted by a ``\fIpathName \fBtag delete\fR'' -widget command, even if no characters are currently marked with -the tag). -The list will be sorted in order from lowest priority to highest -priority. -.TP -\fIpathName \fBtag nextrange \fItagName index1 \fR?\fIindex2\fR? -This command searches the text for a range of characters tagged -with \fItagName\fR where the first character of the range is -no earlier than the character at \fIindex1\fR and no later than -the character just before \fIindex2\fR (a range starting at -\fIindex2\fR will not be considered). -If several matching ranges exist, the first one is chosen. -The command's return value is a list containing -two elements, which are the index of the first character of the -range and the index of the character just after the last one in -the range. -If no matching range is found then the return value is an -empty string. -If \fIindex2\fR is not given then it defaults to the end of the text. -.TP -\fIpathName \fBtag prevrange \fItagName index1 \fR?\fIindex2\fR? -This command searches the text for a range of characters tagged -with \fItagName\fR where the first character of the range is -before the character at \fIindex1\fR and no earlier than -the character at \fIindex2\fR (a range starting at -\fIindex2\fR will be considered). -If several matching ranges exist, the one closest to \fIindex1\fR is chosen. -The command's return value is a list containing -two elements, which are the index of the first character of the -range and the index of the character just after the last one in -the range. -If no matching range is found then the return value is an -empty string. -If \fIindex2\fR is not given then it defaults to the beginning of the text. -.TP -\fIpathName\fB tag raise \fItagName \fR?\fIaboveThis\fR? -Changes the priority of tag \fItagName\fR so that it is just higher -in priority than the tag whose name is \fIaboveThis\fR. -If \fIaboveThis\fR is omitted, then \fItagName\fR's priority -is changed to make it highest priority of all tags. -.TP -\fIpathName \fBtag ranges \fItagName\fR -Returns a list describing all of the ranges of text that have been -tagged with \fItagName\fR. -The first two elements of the list describe the first tagged range -in the text, the next two elements describe the second range, and -so on. -The first element of each pair contains the index of the first -character of the range, and the second element of the pair contains -the index of the character just after the last one in the -range. -If there are no characters tagged with \fItag\fR then an -empty string is returned. -.TP -\fIpathName \fBtag remove \fItagName index1 \fR?\fIindex2 index1 index2 ...\fR? -Remove the tag \fItagName\fR from all of the characters starting -at \fIindex1\fR and ending just before -\fIindex2\fR (the character at \fIindex2\fR isn't affected). -A single command may contain any number of \fIindex1\fR\-\fIindex2\fR -pairs. -If the last \fIindex2\fR is omitted then the single character at -\fIindex1\fR is tagged. -If there are no characters in the specified range (e.g. \fIindex1\fR -is past the end of the file or \fIindex2\fR is less than or equal -to \fIindex1\fR) then the command has no effect. -This command returns an empty string. -.RE -.TP -\fIpathName \fBwindow \fIoption \fR?\fIarg arg ...\fR? -This command is used to manipulate embedded windows. -The behavior of the command depends on the \fIoption\fR argument -that follows the \fBtag\fR argument. -The following forms of the command are currently supported: -.RS -.TP -\fIpathName \fBwindow cget\fR \fIindex option\fR -Returns the value of a configuration option for an embedded window. -\fIIndex\fR identifies the embedded window, and \fIoption\fR -specifies a particular configuration option, which must be one of -the ones listed in the section EMBEDDED WINDOWS. -.TP -\fIpathName \fBwindow configure \fIindex\fR ?\fIoption value ...\fR? -Query or modify the configuration options for an embedded window. -If no \fIoption\fR is specified, returns a list describing all of -the available options for the embedded window at \fIindex\fR -(see \fBTk_ConfigureInfo\fR for information on the format of this list). -If \fIoption\fR is specified with no \fIvalue\fR, then the command -returns a list describing the one named option (this list will be -identical to the corresponding sublist of the value returned if no -\fIoption\fR is specified). -If one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given option(s) to have the given value(s); in -this case the command returns an empty string. -See EMBEDDED WINDOWS for information on the options that -are supported. -.TP -\fIpathName \fBwindow create \fIindex\fR ?\fIoption value ...\fR? -This command creates a new window annotation, which will appear -in the text at the position given by \fIindex\fR. -Any number of \fIoption\-value\fR pairs may be specified to -configure the annotation. -See EMBEDDED WINDOWS for information on the options that -are supported. -Returns an empty string. -.TP -\fIpathName \fBwindow names\fR -Returns a list whose elements are the names of all windows currently -embedded in \fIwindow\fR. -.RE -.TP -\fIpathName \fBxview \fIoption args\fR -This command is used to query and change the horizontal position of the -text in the widget's window. It can take any of the following -forms: -.RS -.TP -\fIpathName \fBxview\fR -Returns a list containing two elements. -Each element is a real fraction between 0 and 1; together they describe -the portion of the document's horizontal span that is visible in -the window. -For example, if the first element is .2 and the second element is .6, -20% of the text is off-screen to the left, the middle 40% is visible -in the window, and 40% of the text is off-screen to the right. -The fractions refer only to the lines that are actually visible in the -window: if the lines in the window are all very short, so that they -are entirely visible, the returned fractions will be 0 and 1, -even if there are other lines in the text that are -much wider than the window. -These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR -option. -.TP -\fIpathName \fBxview moveto\fI fraction\fR -Adjusts the view in the window so that \fIfraction\fR of the horizontal -span of the text is off-screen to the left. -\fIFraction\fR is a fraction between 0 and 1. -.TP -\fIpathName \fBxview scroll \fInumber what\fR -This command shifts the view in the window left or right according to -\fInumber\fR and \fIwhat\fR. -\fINumber\fR must be an integer. -\fIWhat\fR must be either \fBunits\fR or \fBpages\fR or an abbreviation -of one of these. -If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by -\fInumber\fR average-width characters on the display; if it is -\fBpages\fR then the view adjusts by \fInumber\fR screenfuls. -If \fInumber\fR is negative then characters farther to the left -become visible; if it is positive then characters farther to the right -become visible. -.RE -.TP -\fIpathName \fByview \fI?args\fR? -This command is used to query and change the vertical position of the -text in the widget's window. -It can take any of the following forms: -.RS -.TP -\fIpathName \fByview\fR -Returns a list containing two elements, both of which are real fractions -between 0 and 1. -The first element gives the position of the first character in the -top line in the window, relative to the text as a whole (0.5 means -it is halfway through the text, for example). -The second element gives the position of the character just after -the last one in the bottom line of the window, -relative to the text as a whole. -These are the same values passed to scrollbars via the \fB\-yscrollcommand\fR -option. -.TP -\fIpathName \fByview moveto\fI fraction\fR -Adjusts the view in the window so that the character given by \fIfraction\fR -appears on the top line of the window. -\fIFraction\fR is a fraction between 0 and 1; 0 indicates the first -character in the text, 0.33 indicates the character one-third the -way through the text, and so on. -.TP -\fIpathName \fByview scroll \fInumber what\fR -This command adjust the view in the window up or down according to -\fInumber\fR and \fIwhat\fR. -\fINumber\fR must be an integer. -\fIWhat\fR must be either \fBunits\fR or \fBpages\fR. -If \fIwhat\fR is \fBunits\fR, the view adjusts up or down by -\fInumber\fR lines on the display; if it is \fBpages\fR then -the view adjusts by \fInumber\fR screenfuls. -If \fInumber\fR is negative then earlier positions in the text -become visible; if it is positive then later positions in the text -become visible. -.TP -\fIpathName \fByview \fR?\fB\-pickplace\fR? \fIindex\fR -Changes the view in the widget's window to make \fIindex\fR visible. -If the \fB\-pickplace\fR option isn't specified then \fIindex\fR will -appear at the top of the window. -If \fB\-pickplace\fR is specified then the widget chooses where -\fIindex\fR appears in the window: -.RS -.IP [1] -If \fIindex\fR is already visible somewhere in the window then the -command does nothing. -.IP [2] -If \fIindex\fR is only a few lines off-screen above the window then -it will be positioned at the top of the window. -.IP [3] -If \fIindex\fR is only a few lines off-screen below the window then -it will be positioned at the bottom of the window. -.IP [4] -Otherwise, \fIindex\fR will be centered in the window. -.LP -The \fB\-pickplace\fR option has been obsoleted by the \fBsee\fR widget -command (\fBsee\fR handles both x- and y-motion to make a location -visible, whereas \fB\-pickplace\fR only handles motion in y). -.RE -.TP -\fIpathName \fByview \fInumber\fR -This command makes the first character on the line after -the one given by \fInumber\fR visible at the top of the window. -\fINumber\fR must be an integer. -This command used to be used for scrolling, but now it is obsolete. -.RE - -.SH BINDINGS -.PP -Tk automatically creates class bindings for texts that give them -the following default behavior. -In the descriptions below, ``word'' is dependent on the value of -the \fBtcl_wordchars\fR variable. See tclvars(n). -.IP [1] -Clicking mouse button 1 positions the insertion cursor -just before the character underneath the mouse cursor, sets the -input focus to this widget, and clears any selection in the widget. -Dragging with mouse button 1 strokes out a selection between -the insertion cursor and the character under the mouse. -.IP [2] -Double-clicking with mouse button 1 selects the word under the mouse -and positions the insertion cursor at the beginning of the word. -Dragging after a double click will stroke out a selection consisting -of whole words. -.IP [3] -Triple-clicking with mouse button 1 selects the line under the mouse -and positions the insertion cursor at the beginning of the line. -Dragging after a triple click will stroke out a selection consisting -of whole lines. -.IP [4] -The ends of the selection can be adjusted by dragging with mouse -button 1 while the Shift key is down; this will adjust the end -of the selection that was nearest to the mouse cursor when button -1 was pressed. -If the button is double-clicked before dragging then the selection -will be adjusted in units of whole words; if it is triple-clicked -then the selection will be adjusted in units of whole lines. -.IP [5] -Clicking mouse button 1 with the Control key down will reposition the -insertion cursor without affecting the selection. -.IP [6] -If any normal printing characters are typed, they are -inserted at the point of the insertion cursor. -.IP [7] -The view in the widget can be adjusted by dragging with mouse button 2. -If mouse button 2 is clicked without moving the mouse, the selection -is copied into the text at the position of the mouse cursor. -The Insert key also inserts the selection, but at the position of -the insertion cursor. -.IP [8] -If the mouse is dragged out of the widget -while button 1 is pressed, the entry will automatically scroll to -make more text visible (if there is more text off-screen on the side -where the mouse left the window). -.IP [9] -The Left and Right keys move the insertion cursor one character to the -left or right; they also clear any selection in the text. -If Left or Right is typed with the Shift key down, then the insertion -cursor moves and the selection is extended to include the new character. -Control-Left and Control-Right move the insertion cursor by words, and -Control-Shift-Left and Control-Shift-Right move the insertion cursor -by words and also extend the selection. -Control-b and Control-f behave the same as Left and Right, respectively. -Meta-b and Meta-f behave the same as Control-Left and Control-Right, -respectively. -.IP [10] -The Up and Down keys move the insertion cursor one line up or -down and clear any selection in the text. -If Up or Right is typed with the Shift key down, then the insertion -cursor moves and the selection is extended to include the new character. -Control-Up and Control-Down move the insertion cursor by paragraphs (groups -of lines separated by blank lines), and -Control-Shift-Up and Control-Shift-Down move the insertion cursor -by paragraphs and also extend the selection. -Control-p and Control-n behave the same as Up and Down, respectively. -.IP [11] -The Next and Prior keys move the insertion cursor forward or backwards -by one screenful and clear any selection in the text. -If the Shift key is held down while Next or Prior is typed, then -the selection is extended to include the new character. -Control-v moves the view down one screenful without moving the -insertion cursor or adjusting the selection. -.IP [12] -Control-Next and Control-Prior scroll the view right or left by one page -without moving the insertion cursor or affecting the selection. -.IP [13] -Home and Control-a move the insertion cursor to the -beginning of its line and clear any selection in the widget. -Shift-Home moves the insertion cursor to the beginning of the line -and also extends the selection to that point. -.IP [14] -End and Control-e move the insertion cursor to the -end of the line and clear any selection in the widget. -Shift-End moves the cursor to the end of the line and extends the selection -to that point. -.IP [15] -Control-Home and Meta-< move the insertion cursor to the beginning of -the text and clear any selection in the widget. -Control-Shift-Home moves the insertion cursor to the beginning of the text -and also extends the selection to that point. -.IP [16] -Control-End and Meta-> move the insertion cursor to the end of the -text and clear any selection in the widget. -Control-Shift-End moves the cursor to the end of the text and extends -the selection to that point. -.IP [17] -The Select key and Control-Space set the selection anchor to the position -of the insertion cursor. They don't affect the current selection. -Shift-Select and Control-Shift-Space adjust the selection to the -current position of the insertion cursor, selecting from the anchor -to the insertion cursor if there was not any selection previously. -.IP [18] -Control-/ selects the entire contents of the widget. -.IP [19] -Control-\e clears any selection in the widget. -.IP [20] -The F16 key (labelled Copy on many Sun workstations) or Meta-w -copies the selection in the widget to the clipboard, if there is a selection. -.VS 8.4 -This action is carried out by the command \fBtk_textCopy\fR. -.VE 8.4 -.IP [21] -The F20 key (labelled Cut on many Sun workstations) or Control-w -copies the selection in the widget to the clipboard and deletes -the selection. -.VS 8.4 -This action is carried out by the command \fBtk_textCut\fR. -.VE 8.4 -If there is no selection in the widget then these keys have no effect. -.IP [22] -The F18 key (labelled Paste on many Sun workstations) or Control-y -inserts the contents of the clipboard at the position of the -insertion cursor. -.VS 8.4 -This action is carried out by the command \fBtk_textPaste\fR. -.VE 8.4 -.IP [23] -The Delete key deletes the selection, if there is one in the widget. -If there is no selection, it deletes the character to the right of -the insertion cursor. -.IP [24] -Backspace and Control-h delete the selection, if there is one -in the widget. -If there is no selection, they delete the character to the left of -the insertion cursor. -.IP [25] -Control-d deletes the character to the right of the insertion cursor. -.IP [26] -Meta-d deletes the word to the right of the insertion cursor. -.IP [27] -Control-k deletes from the insertion cursor to the end of its line; -if the insertion cursor is already at the end of a line, then -Control-k deletes the newline character. -.IP [28] -Control-o opens a new line by inserting a newline character in -front of the insertion cursor without moving the insertion cursor. -.IP [29] -Meta-backspace and Meta-Delete delete the word to the left of the -insertion cursor. -.IP [30] -Control-x deletes whatever is selected in the text widget. -.IP [31] -Control-t reverses the order of the two characters to the right of -the insertion cursor. -.IP [32] -.VS 8.4 -Control-z (and Control-underscore on UNIX when \fBtk_strictMotif\fR is -true) undoes the last edit action if the \fB-undo\fR option is true. -Does nothing otherwise. -.IP [33] -Control-Z (or Control-y on Windows) reapplies the last undone edit -action if the \fB-undo\fR option is true. Does nothing otherwise. -.VE 8.4 -.PP -If the widget is disabled using the \fB\-state\fR option, then its -view can still be adjusted and text can still be selected, -but no insertion cursor will be displayed and no text modifications will -take place. -.PP -The behavior of texts can be changed by defining new bindings for -individual widgets or by redefining the class bindings. - -.SH "PERFORMANCE ISSUES" -.PP -Text widgets should run efficiently under a variety -of conditions. The text widget uses about 2-3 bytes of -main memory for each byte of text, so texts containing a megabyte -or more should be practical on most workstations. -Text is represented internally with a modified B-tree structure -that makes operations relatively efficient even with large texts. -Tags are included in the B-tree structure in a way that allows -tags to span large ranges or have many disjoint smaller ranges -without loss of efficiency. -Marks are also implemented in a way that allows large numbers of -marks. -In most cases it is fine to have large numbers of unique tags, -or a tag that has many distinct ranges. -.PP -One performance problem can arise if you have hundreds or thousands -of different tags that all have the following characteristics: -the first and last ranges of each tag are near the beginning and -end of the text, respectively, -or a single tag range covers most of the text widget. -The cost of adding and deleting tags like this is proportional -to the number of other tags with the same properties. -In contrast, there is no problem with having thousands of distinct -tags if their overall ranges are localized and spread uniformly throughout -the text. -.PP -Very long text lines can be expensive, -especially if they have many marks and tags within them. -.PP -The display line with the insert cursor is redrawn each time the -cursor blinks, which causes a steady stream of graphics traffic. -Set the \fBinsertOffTime\fP attribute to 0 avoid this. -.SH KEYWORDS -text, widget, tkvars diff --git a/tcl/doc/tk.n b/tcl/doc/tk.n deleted file mode 100644 index b60aa9e9e0..0000000000 --- a/tcl/doc/tk.n +++ /dev/null @@ -1,104 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH tk n 8.4 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -tk \- Manipulate Tk internal state -.SH SYNOPSIS -\fBtk\fR \fIoption \fR?\fIarg arg ...\fR? -.BE - -.SH DESCRIPTION -.PP -The \fBtk\fR command provides access to miscellaneous -elements of Tk's internal state. -Most of the information manipulated by this command pertains to the -application as a whole, or to a screen or display, rather than to a -particular window. -The command can take any of a number of different forms -depending on the \fIoption\fR argument. The legal forms are: -.TP -\fBtk appname \fR?\fInewName\fR? -If \fInewName\fR isn't specified, this command returns the name -of the application (the name that may be used in \fBsend\fR -commands to communicate with the application). -If \fInewName\fR is specified, then the name of the application -is changed to \fInewName\fR. -If the given name is already in use, then a suffix of the form -``\fB #2\fR'' or ``\fB #3\fR'' is appended in order to make the name unique. -The command's result is the name actually chosen. -\fInewName\fR should not start with a capital letter. -This will interfere with option processing, since names starting with -capitals are assumed to be classes; as a result, Tk may not -be able to find some options for the application. -If sends have been disabled by deleting the \fBsend\fR command, -this command will reenable them and recreate the \fBsend\fR -command. -.VS 8.4 -.TP -\fBtk caret window \fR?\fB\-x \fIx\fR? ?\fB\-y \fIy\fR? ?\fB\-height \fIheight\fR? -. -Sets and queries the caret location for the display of the specified -Tk window \fIwindow\fR. The caret is the per-display cursor location -used for indicating global focus (e.g. to comply with Microsoft -Accessibility guidelines), as well as for location of the over-the-spot -XIM (X Input Methods) or Windows IME windows. If no options are specified, -the last values used for setting the caret are return in option-value pair -format. \fI\-x\fR and \fI\-y\fR represent window-relative coordinates, and -\fI\-height\fR is the height of the current cursor location, or the height -of the specified \fIwindow\fR if none is given. -.VE -.TP -\fBtk scaling \fR?\fB\-displayof \fIwindow\fR? ?\fInumber\fR? -. -Sets and queries the current scaling factor used by Tk to convert between -physical units (for example, points, inches, or millimeters) and pixels. The -\fInumber\fR argument is a floating point number that specifies the number of -pixels per point on \fIwindow\fR's display. If the \fIwindow\fR argument is -omitted, it defaults to the main window. If the \fInumber\fR argument is -omitted, the current value of the scaling factor is returned. -.RS -.PP -A ``point'' is a unit of measurement equal to 1/72 inch. A scaling factor -of 1.0 corresponds to 1 pixel per point, which is equivalent to a standard -72 dpi monitor. A scaling factor of 1.25 would mean 1.25 pixels per point, -which is the setting for a 90 dpi monitor; setting the scaling factor to -1.25 on a 72 dpi monitor would cause everything in the application to be -displayed 1.25 times as large as normal. The initial value for the scaling -factor is set when the application starts, based on properties of the -installed monitor, but it can be changed at any time. Measurements made -after the scaling factor is changed will use the new scaling factor, but it -is undefined whether existing widgets will resize themselves dynamically to -accomodate the new scaling factor. -.RE -.VS 8.3 -.TP -\fBtk useinputmethods \fR?\fB\-displayof \fIwindow\fR? ?\fIboolean\fR? -. -Sets and queries the state of whether Tk should use XIM (X Input Methods) -for filtering events. The resulting state is returned. XIM is used in -some locales (ie: Japanese, Korean), to handle special input devices. This -feature is only significant on X. If XIM support is not available, this -will always return 0. If the \fIwindow\fR argument is omitted, it defaults -to the main window. If the \fIboolean\fR argument is omitted, the current -state is returned. This is turned on by default for the main display. -.VE -.VS 8.4 -.TP -\fBtk windowingsystem\fR -. -Returns the current Tk windowing system, one of -\fBx11\fR (X11-based), \fBwin32\fR (MS Windows), -\fBclassic\fR (Mac OS Classic), or \fBaqua\fR (Mac OS X Aqua). -.VE -.SH KEYWORDS -application name, send diff --git a/tcl/doc/tkerror.n b/tcl/doc/tkerror.n deleted file mode 100644 index 9ccee96b1b..0000000000 --- a/tcl/doc/tkerror.n +++ /dev/null @@ -1,38 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH tkerror n 4.1 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -tkerror \- Command invoked to process background errors -.SH SYNOPSIS -\fBtkerror \fImessage\fR -.BE - -.SH DESCRIPTION -.PP -Note: as of Tk 4.1 the \fBtkerror\fR command has been renamed to -\fBbgerror\fR because the event loop (which is what usually invokes -it) is now part of Tcl. For backward compatibility -the \fBbgerror\fR provided by the current Tk version still -tries to call \fBtkerror\fR if there is one (or an auto loadable one), -so old script defining that error handler should still work, but you -should anyhow modify your scripts to use \fBbgerror\fR instead -of \fBtkerror\fR because that support for the old name might vanish -in the near future. If that call fails, \fBbgerror\fR -posts a dialog showing the error and offering to see the stack trace -to the user. If you want your own error management you should -directly override \fBbgerror\fR instead of \fBtkerror\fR. -Documentation for \fBbgerror\fR is available as part of Tcl's -documentation. - -.SH KEYWORDS -background error, reporting diff --git a/tcl/doc/tkvars.n b/tcl/doc/tkvars.n deleted file mode 100644 index fe8b2e7d61..0000000000 --- a/tcl/doc/tkvars.n +++ /dev/null @@ -1,80 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH tkvars n 4.1 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -tkvars \- Variables used or set by Tk -.BE - -.SH DESCRIPTION -.PP -The following Tcl variables are either set or used by Tk at various times -in its execution: -.TP 15 -\fBtk_library\fR -This variable holds the file name for a directory containing a library -of Tcl scripts related to Tk. These scripts include an initialization -file that is normally processed whenever a Tk application starts up, -plus other files containing procedures that implement default behaviors -for widgets. -The initial value of \fBtcl_library\fR is set when Tk is added to -an interpreter; this is done by searching several different directories -until one is found that contains an appropriate Tk startup script. -If the \fBTK_LIBRARY\fR environment variable exists, then -the directory it names is checked first. -If \fBTK_LIBRARY\fR isn't set or doesn't refer to an appropriate -directory, then Tk checks several other directories based on a -compiled-in default location, the location of the Tcl library directory, -the location of the binary containing the application, and the current -working directory. -The variable can be modified by an application to switch to a different -library. -.TP -\fBtk_patchLevel\fR -Contains a decimal integer giving the current patch level for Tk. -The patch level is incremented for each new release or patch, and -it uniquely identifies an official version of Tk. -.TP -\fBtk::Priv\fR -This variable is an array containing several pieces of information -that are private to Tk. The elements of \fBtk::Priv\fR are used by -Tk library procedures and default bindings. -They should not be accessed by any code outside Tk. -.TP -\fBtk_strictMotif\fR -This variable is set to zero by default. -If an application sets it to one, then Tk attempts to adhere as -closely as possible to Motif look-and-feel standards. -For example, active elements such as buttons and scrollbar -sliders will not change color when the pointer passes over them. -.TP -\fBtk_textRedraw\fR -.TP -\fBtk_textRelayout\fR -These variables are set by text widgets when they have debugging -turned on. The values written to these variables can be used to -test or debug text widget operations. These variables are mostly -used by Tk's test suite. -.TP 15 -\fBtk_version\fR -Tk sets this variable in the interpreter for each application. -The variable holds the current version number of the Tk -library in the form \fImajor\fR.\fIminor\fR. \fIMajor\fR and -\fIminor\fR are integers. The major version number increases in -any Tk release that includes changes that are not backward compatible -(i.e. whenever existing Tk applications and scripts may have to change to -work with the new release). The minor version number increases with -each new release of Tk, except that it resets to zero whenever the -major version number changes. - -.SH KEYWORDS -variables, version, text diff --git a/tcl/doc/tkwait.n b/tcl/doc/tkwait.n deleted file mode 100644 index 0c39f38497..0000000000 --- a/tcl/doc/tkwait.n +++ /dev/null @@ -1,51 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH tkwait n "" Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -tkwait \- Wait for variable to change or window to be destroyed -.SH SYNOPSIS -\fBtkwait variable \fIname\fR -.sp -\fBtkwait visibility \fIname\fR -.sp -\fBtkwait window \fIname\fR -.BE - -.SH DESCRIPTION -.PP -The \fBtkwait\fR command waits for one of several things to happen, -then it returns without taking any other actions. -The return value is always an empty string. -If the first argument is \fBvariable\fR (or any abbreviation of -it) then the second argument is the name of a global variable and the -command waits for that variable to be modified. -If the first argument is \fBvisibility\fR (or any abbreviation -of it) then the second argument is the name of a window and the -\fBtkwait\fR command waits for a change in its -visibility state (as indicated by the arrival of a VisibilityNotify -event). This form is typically used to wait for a newly-created -window to appear on the screen before taking some action. -If the first argument is \fBwindow\fR (or any abbreviation -of it) then the second argument is the name of a window and the -\fBtkwait\fR command waits for that window to be destroyed. -This form is typically used to wait for a user to finish interacting -with a dialog box before using the result of that interaction. -.PP -While the \fBtkwait\fR command is waiting it processes events in -the normal fashion, so the application will continue to respond -to user interactions. -If an event handler invokes \fBtkwait\fR again, the nested call -to \fBtkwait\fR must complete before the outer call can complete. - -.SH KEYWORDS -variable, visibility, wait, window diff --git a/tcl/doc/toplevel.n b/tcl/doc/toplevel.n deleted file mode 100644 index 070da07713..0000000000 --- a/tcl/doc/toplevel.n +++ /dev/null @@ -1,161 +0,0 @@ -'\" -'\" 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$ -'\" -.so man.macros -.TH toplevel n 8.4 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -toplevel \- Create and manipulate toplevel widgets -.SH SYNOPSIS -\fBtoplevel\fR \fIpathName \fR?\fIoptions\fR? -.SO -\-borderwidth \-highlightcolor \-pady -\-cursor \-highlightthickness \-relief -\-highlightbackground \-padx \-takefocus -.SE -.SH "WIDGET-SPECIFIC OPTIONS" -.OP \-background background Background -This option is the same as the standard \fBbackground\fR option -except that its value may also be specified as an empty string. -In this case, the widget will display no background or border, and -no colors will be consumed from its colormap for its background -and border. -.OP \-class class Class -Specifies a class for the window. -This class will be used when querying the option database for -the window's other options, and it will also be used later for -other purposes such as bindings. -The \fBclass\fR option may not be changed with the \fBconfigure\fR -widget command. -.OP \-colormap colormap Colormap -Specifies a colormap to use for the window. -The value may be either \fBnew\fR, in which case a new colormap is -created for the window and its children, or the name of another -window (which must be on the same screen and have the same visual -as \fIpathName\fR), in which case the new window will use the colormap -from the specified window. -If the \fBcolormap\fR option is not specified, the new window -uses the default colormap of its screen. -This option may not be changed with the \fBconfigure\fR -widget command. -.OP \-container container Container -The value must be a boolean. If true, it means that this window will -be used as a container in which some other application will be embedded -(for example, a Tk toplevel can be embedded using the \fB\-use\fR option). -The window will support the appropriate window manager protocols for -things like geometry requests. The window should not have any -children of its own in this application. -This option may not be changed with the \fBconfigure\fR -widget command. -.OP \-height height Height -Specifies the desired height for the window in any of the forms -acceptable to \fBTk_GetPixels\fR. -If this option is less than or equal to zero then the window will -not request any size at all. -.OP \-menu menu Menu -Specifies a menu widget to be used as a menubar. On the Macintosh, the -menubar will be displayed accross the top of the main monitor. On -Microsoft Windows and all UNIX platforms, the menu will appear accross -the toplevel window as part of the window dressing maintained by the -window manager. -.OP \-screen "" "" -Specifies the screen on which to place the new window. -Any valid screen name may be used, even one associated with a -different display. -Defaults to the same screen as its parent. -This option is special in that it may not be specified via the option -database, and it may not be modified with the \fBconfigure\fR -widget command. -.OP \-use use Use -This option is used for embedding. If the value isn't an empty string, -it must be the the window identifier of a container window, specified as -a hexadecimal string like the ones returned by the \fBwinfo id\fR -command. The toplevel widget will be created as a child of the given -container instead of the root window for the screen. If the container -window is in a Tk application, it must be a frame or toplevel widget for -which the \fB\-container\fR option was specified. -This option may not be changed with the \fBconfigure\fR -widget command. -.OP \-visual visual Visual -Specifies visual information for the new window in any of the -forms accepted by \fBTk_GetVisual\fR. -If this option is not specified, the new window will use the default -visual for its screen. -The \fBvisual\fR option may not be modified with the \fBconfigure\fR -widget command. -.OP \-width width Width -Specifies the desired width for the window in any of the forms -acceptable to \fBTk_GetPixels\fR. -If this option is less than or equal to zero then the window will -not request any size at all. -.BE - -.SH DESCRIPTION -.PP -The \fBtoplevel\fR command creates a new toplevel widget (given -by the \fIpathName\fR argument). Additional -options, described above, may be specified on the command line -or in the option database -to configure aspects of the toplevel such as its background color -and relief. The \fBtoplevel\fR command returns the -path name of the new window. -.PP -A toplevel is similar to a frame except that it is created as a -top-level window: its X parent is the root window of a screen -rather than the logical parent from its path name. The primary -purpose of a toplevel is to serve as a container for dialog boxes -and other collections of widgets. The only visible features -of a toplevel are its background color and an optional 3-D border -to make the toplevel appear raised or sunken. - -.SH "WIDGET COMMAND" -.PP -The \fBtoplevel\fR command creates a new Tcl command whose -name is the same as the path name of the toplevel's window. This -command may be used to invoke various -operations on the widget. It has the following general form: -.CS -\fIpathName option \fR?\fIarg arg ...\fR? -.CE -\fIPathName\fR is the name of the command, which is the same as -the toplevel widget's path name. \fIOption\fR and the \fIarg\fRs -determine the exact behavior of the command. The following -commands are possible for toplevel widgets: -.TP -\fIpathName \fBcget\fR \fIoption\fR -Returns the current value of the configuration option given -by \fIoption\fR. -\fIOption\fR may have any of the values accepted by the \fBtoplevel\fR -command. -.TP -\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -Query or modify the configuration options of the widget. -If no \fIoption\fR is specified, returns a list describing all of -the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for -information on the format of this list). If \fIoption\fR is specified -with no \fIvalue\fR, then the command returns a list describing the -one named option (this list will be identical to the corresponding -sublist of the value returned if no \fIoption\fR is specified). If -one or more \fIoption\-value\fR pairs are specified, then the command -modifies the given widget option(s) to have the given value(s); in -this case the command returns an empty string. -\fIOption\fR may have any of the values accepted by the \fBtoplevel\fR -command. - -.SH BINDINGS -.PP -When a new toplevel is created, it has no default event bindings: -toplevels are not intended to be interactive. - -.SH "SEE ALSO" -frame(n) - -.SH KEYWORDS -toplevel, widget diff --git a/tcl/doc/winfo.n b/tcl/doc/winfo.n deleted file mode 100644 index 2d1303e2b2..0000000000 --- a/tcl/doc/winfo.n +++ /dev/null @@ -1,332 +0,0 @@ -'\" -'\" Copyright (c) 1990-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$ -'\" -.so man.macros -.TH winfo n 4.3 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -winfo \- Return window-related information -.SH SYNOPSIS -\fBwinfo\fR \fIoption \fR?\fIarg arg ...\fR? -.BE - -.SH DESCRIPTION -.PP -The \fBwinfo\fR command is used to retrieve information about windows -managed by Tk. It can take any of a number of different forms, -depending on the \fIoption\fR argument. The legal forms are: -.TP -\fBwinfo atom \fR?\fB\-displayof \fIwindow\fR? \fIname\fR -Returns a decimal string giving the integer identifier for the -atom whose name is \fIname\fR. If no atom exists with the name -\fIname\fR then a new one is created. -If the \fB\-displayof\fR option is given then the atom is looked -up on the display of \fIwindow\fR; otherwise it is looked up on -the display of the application's main window. -.TP -\fBwinfo atomname \fR?\fB\-displayof \fIwindow\fR? \fIid\fR -Returns the textual name for the atom whose integer identifier is -\fIid\fR. -If the \fB\-displayof\fR option is given then the identifier is looked -up on the display of \fIwindow\fR; otherwise it is looked up on -the display of the application's main window. -This command is the inverse of the \fBwinfo atom\fR command. -It generates an error if no such atom exists. -.TP -\fBwinfo cells \fIwindow\fR -Returns a decimal string giving the number of cells in the -color map for \fIwindow\fR. -.TP -\fBwinfo children \fIwindow\fR -Returns a list containing the path names of all the children -of \fIwindow\fR. Top-level windows are returned as children -of their logical parents. The list is in stacking order, with -the lowest window first, except for Top-level windows which -are not returned in stacking order. Use the \fBwm stackorder\fR -command to query the stacking order of Top-level windows. -.TP -\fBwinfo class \fIwindow\fR -Returns the class name for \fIwindow\fR. -.TP -\fBwinfo colormapfull \fIwindow\fR -Returns 1 if the colormap for \fIwindow\fR is known to be full, 0 -otherwise. The colormap for a window is ``known'' to be full if the last -attempt to allocate a new color on that window failed and this -application hasn't freed any colors in the colormap since the -failed allocation. -.TP -\fBwinfo containing \fR?\fB\-displayof \fIwindow\fR? \fIrootX rootY\fR -Returns the path name for the window containing the point given -by \fIrootX\fR and \fIrootY\fR. -\fIRootX\fR and \fIrootY\fR are specified in screen units (i.e. -any form acceptable to \fBTk_GetPixels\fR) in the coordinate -system of the root window (if a virtual-root window manager is in -use then the coordinate system of the virtual root window is used). -If the \fB\-displayof\fR option is given then the coordinates refer -to the screen containing \fIwindow\fR; otherwise they refer to the -screen of the application's main window. -If no window in this application contains the point then an empty -string is returned. -In selecting the containing window, children are given higher priority -than parents and among siblings the highest one in the stacking order is -chosen. -.TP -\fBwinfo depth \fIwindow\fR -Returns a decimal string giving the depth of \fIwindow\fR (number -of bits per pixel). -.TP -\fBwinfo exists \fIwindow\fR -Returns 1 if there exists a window named \fIwindow\fR, 0 if no such -window exists. -.TP -\fBwinfo fpixels \fIwindow\fR \fInumber\fR -Returns a floating-point value giving the number of pixels -in \fIwindow\fR corresponding to the distance given by \fInumber\fR. -\fINumber\fR may be specified in any of the forms acceptable -to \fBTk_GetScreenMM\fR, such as ``2.0c'' or ``1i''. -The return value may be fractional; for an integer value, use -\fBwinfo pixels\fR. -.TP -\fBwinfo geometry \fIwindow\fR -Returns the geometry for \fIwindow\fR, in the form -\fIwidth\fBx\fIheight\fB+\fIx\fB+\fIy\fR. All dimensions are -in pixels. -.TP -\fBwinfo height \fIwindow\fR -Returns a decimal string giving \fIwindow\fR's height in pixels. -When a window is first created its height will be 1 pixel; the -height will eventually be changed by a geometry manager to fulfill -the window's needs. -If you need the true height immediately after creating a widget, -invoke \fBupdate\fR to force the geometry manager to arrange it, -or use \fBwinfo reqheight\fR to get the window's requested height -instead of its actual height. -.TP -\fBwinfo id \fIwindow\fR -.VS -Returns a hexadecimal string giving a low-level platform-specific -identifier for \fIwindow\fR. On Unix platforms, this is the X -window identifier. Under Windows, this is the Windows -HWND. On the Macintosh the value has no meaning outside Tk. -.VE -.TP -\fBwinfo interps \fR?\fB\-displayof \fIwindow\fR? -Returns a list whose members are the names of all Tcl interpreters -(e.g. all Tk-based applications) currently registered for a particular display. -If the \fB\-displayof\fR option is given then the return value refers -to the display of \fIwindow\fR; otherwise it refers to -the display of the application's main window. -.TP -\fBwinfo ismapped \fIwindow\fR -Returns \fB1\fR if \fIwindow\fR is currently mapped, \fB0\fR otherwise. -.TP -\fBwinfo manager \fIwindow\fR -Returns the name of the geometry manager currently -responsible for \fIwindow\fR, or an empty string if \fIwindow\fR -isn't managed by any geometry manager. -The name is usually the name of the Tcl command for the geometry -manager, such as \fBpack\fR or \fBplace\fR. -If the geometry manager is a widget, such as canvases or text, the -name is the widget's class command, such as \fBcanvas\fR. -.TP -\fBwinfo name \fIwindow\fR -Returns \fIwindow\fR's name (i.e. its name within its parent, as opposed -to its full path name). -The command \fBwinfo name .\fR will return the name of the application. -.TP -\fBwinfo parent \fIwindow\fR -Returns the path name of \fIwindow\fR's parent, or an empty string -if \fIwindow\fR is the main window of the application. -.TP -\fBwinfo pathname \fR?\fB\-displayof \fIwindow\fR? \fIid\fR -Returns the path name of the window whose X identifier is \fIid\fR. -\fIId\fR must be a decimal, hexadecimal, or octal integer and must -correspond to a window in the invoking application. -If the \fB\-displayof\fR option is given then the identifier is looked -up on the display of \fIwindow\fR; otherwise it is looked up on -the display of the application's main window. -.TP -\fBwinfo pixels \fIwindow\fR \fInumber\fR -Returns the number of pixels in \fIwindow\fR corresponding -to the distance given by \fInumber\fR. -\fINumber\fR may be specified in any of the forms acceptable -to \fBTk_GetPixels\fR, such as ``2.0c'' or ``1i''. -The result is rounded to the nearest integer value; for a -fractional result, use \fBwinfo fpixels\fR. -.TP -\fBwinfo pointerx \fIwindow\fR -If the mouse pointer is on the same screen as \fIwindow\fR, returns the -pointer's x coordinate, measured in pixels in the screen's root window. -If a virtual root window is in use on the screen, the position is -measured in the virtual root. -If the mouse pointer isn't on the same screen as \fIwindow\fR then --1 is returned. -.TP -\fBwinfo pointerxy \fIwindow\fR -If the mouse pointer is on the same screen as \fIwindow\fR, returns a list -with two elements, which are the pointer's x and y coordinates measured -in pixels in the screen's root window. -If a virtual root window is in use on the screen, the position -is computed in the virtual root. -If the mouse pointer isn't on the same screen as \fIwindow\fR then -both of the returned coordinates are -1. -.TP -\fBwinfo pointery \fIwindow\fR -If the mouse pointer is on the same screen as \fIwindow\fR, returns the -pointer's y coordinate, measured in pixels in the screen's root window. -If a virtual root window is in use on the screen, the position -is computed in the virtual root. -If the mouse pointer isn't on the same screen as \fIwindow\fR then --1 is returned. -.TP -\fBwinfo reqheight \fIwindow\fR -Returns a decimal string giving \fIwindow\fR's requested height, -in pixels. This is the value used by \fIwindow\fR's geometry -manager to compute its geometry. -.TP -\fBwinfo reqwidth \fIwindow\fR -Returns a decimal string giving \fIwindow\fR's requested width, -in pixels. This is the value used by \fIwindow\fR's geometry -manager to compute its geometry. -.TP -\fBwinfo rgb \fIwindow color\fR -Returns a list containing three decimal values, which are the -red, green, and blue intensities that correspond to \fIcolor\fR in -the window given by \fIwindow\fR. \fIColor\fR -may be specified in any of the forms acceptable for a color -option. -.TP -\fBwinfo rootx \fIwindow\fR -Returns a decimal string giving the x-coordinate, in the root -window of the screen, of the -upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it -has no border). -.TP -\fBwinfo rooty \fIwindow\fR -Returns a decimal string giving the y-coordinate, in the root -window of the screen, of the -upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it -has no border). -.TP -\fBwinfo screen \fIwindow\fR -Returns the name of the screen associated with \fIwindow\fR, in -the form \fIdisplayName\fR.\fIscreenIndex\fR. -.TP -\fBwinfo screencells \fIwindow\fR -Returns a decimal string giving the number of cells in the default -color map for \fIwindow\fR's screen. -.TP -\fBwinfo screendepth \fIwindow\fR -Returns a decimal string giving the depth of the root window -of \fIwindow\fR's screen (number of bits per pixel). -.TP -\fBwinfo screenheight \fIwindow\fR -Returns a decimal string giving the height of \fIwindow\fR's screen, -in pixels. -.TP -\fBwinfo screenmmheight \fIwindow\fR -Returns a decimal string giving the height of \fIwindow\fR's screen, -in millimeters. -.TP -\fBwinfo screenmmwidth \fIwindow\fR -Returns a decimal string giving the width of \fIwindow\fR's screen, -in millimeters. -.TP -\fBwinfo screenvisual \fIwindow\fR -Returns one of the following strings to indicate the default visual -class for \fIwindow\fR's screen: \fBdirectcolor\fR, \fBgrayscale\fR, -\fBpseudocolor\fR, \fBstaticcolor\fR, \fBstaticgray\fR, or -\fBtruecolor\fR. -.TP -\fBwinfo screenwidth \fIwindow\fR -Returns a decimal string giving the width of \fIwindow\fR's screen, -in pixels. -.TP -\fBwinfo server \fIwindow\fR -Returns a string containing information about the server for -\fIwindow\fR's display. The exact format of this string may vary -from platform to platform. For X servers the string -has the form ``\fBX\fImajor\fBR\fIminor vendor vendorVersion\fR'' -where \fImajor\fR and \fIminor\fR are the version and revision -numbers provided by the server (e.g., \fBX11R5\fR), \fIvendor\fR -is the name of the vendor for the server, and \fIvendorRelease\fR -is an integer release number provided by the server. -.TP -\fBwinfo toplevel \fIwindow\fR -Returns the path name of the top-level window containing \fIwindow\fR. -.TP -\fBwinfo viewable \fIwindow\fR -Returns 1 if \fIwindow\fR and all of its ancestors up through the -nearest toplevel window are mapped. Returns 0 if any of these -windows are not mapped. -.TP -\fBwinfo visual \fIwindow\fR -Returns one of the following strings to indicate the visual -class for \fIwindow\fR: \fBdirectcolor\fR, \fBgrayscale\fR, -\fBpseudocolor\fR, \fBstaticcolor\fR, \fBstaticgray\fR, or -\fBtruecolor\fR. -.TP -\fBwinfo visualid \fIwindow\fR -Returns the X identifier for the visual for \fIwindow\fR. -.TP -\fBwinfo visualsavailable \fIwindow\fR ?\fBincludeids\fR? -Returns a list whose elements describe the visuals available for -\fIwindow\fR's screen. -Each element consists of a visual class followed by an integer depth. -The class has the same form as returned by \fBwinfo visual\fR. -The depth gives the number of bits per pixel in the visual. -In addition, if the \fBincludeids\fR argument is provided, then the -depth is followed by the X identifier for the visual. -.TP -\fBwinfo vrootheight \fIwindow\fR -Returns the height of the virtual root window associated with \fIwindow\fR -if there is one; otherwise returns the height of \fIwindow\fR's screen. -.TP -\fBwinfo vrootwidth \fIwindow\fR -Returns the width of the virtual root window associated with \fIwindow\fR -if there is one; otherwise returns the width of \fIwindow\fR's screen. -.TP -\fBwinfo vrootx \fIwindow\fR -Returns the x-offset of the virtual root window associated with \fIwindow\fR, -relative to the root window of its screen. -This is normally either zero or negative. -Returns 0 if there is no virtual root window for \fIwindow\fR. -.TP -\fBwinfo vrooty \fIwindow\fR -Returns the y-offset of the virtual root window associated with \fIwindow\fR, -relative to the root window of its screen. -This is normally either zero or negative. -Returns 0 if there is no virtual root window for \fIwindow\fR. -.TP -\fBwinfo width \fIwindow\fR -Returns a decimal string giving \fIwindow\fR's width in pixels. -When a window is first created its width will be 1 pixel; the -width will eventually be changed by a geometry manager to fulfill -the window's needs. -If you need the true width immediately after creating a widget, -invoke \fBupdate\fR to force the geometry manager to arrange it, -or use \fBwinfo reqwidth\fR to get the window's requested width -instead of its actual width. -.TP -\fBwinfo x \fIwindow\fR -Returns a decimal string giving the x-coordinate, in \fIwindow\fR's -parent, of the -upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it -has no border). -.TP -\fBwinfo y \fIwindow\fR -Returns a decimal string giving the y-coordinate, in \fIwindow\fR's -parent, of the -upper-left corner of \fIwindow\fR's border (or \fIwindow\fR if it -has no border). - -.SH KEYWORDS -atom, children, class, geometry, height, identifier, information, interpreters, -mapped, parent, path name, screen, virtual root, width, window diff --git a/tcl/doc/wish.1 b/tcl/doc/wish.1 deleted file mode 100644 index 4afc2be5df..0000000000 --- a/tcl/doc/wish.1 +++ /dev/null @@ -1,186 +0,0 @@ -'\" -'\" Copyright (c) 1991-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$ -'\" -.so man.macros -.TH wish 1 8.0 Tk "Tk Applications" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -wish \- Simple windowing shell -.SH SYNOPSIS -\fBwish\fR ?\fIfileName arg arg ...\fR? -.SH OPTIONS -.IP "\fB\-colormap \fInew\fR" 20 -Specifies that the window should have a new private colormap instead of -using the default colormap for the screen. -.IP "\fB\-display \fIdisplay\fR" 20 -Display (and screen) on which to display window. -.IP "\fB\-geometry \fIgeometry\fR" 20 -Initial geometry to use for window. If this option is specified, its -value is stored in the \fBgeometry\fR global variable of the application's -Tcl interpreter. -.IP "\fB\-name \fIname\fR" 20 -Use \fIname\fR as the title to be displayed in the window, and -as the name of the interpreter for \fBsend\fR commands. -.IP "\fB\-sync\fR" 20 -Execute all X server commands synchronously, so that errors -are reported immediately. This will result in much slower -execution, but it is useful for debugging. -.VS 8.0 br -.IP "\fB\-use\fR \fIid\fR" 20 -Specifies that the main window for the application is to be embedded in -the window whose identifier is \fIid\fR, instead of being created as an -independent toplevel window. \fIId\fR must be specified in the same -way as the value for the \fB\-use\fR option for toplevel widgets (i.e. -it has a form like that returned by the \fBwinfo id\fR command). -.VE -.IP "\fB\-visual \fIvisual\fR" 20 -Specifies the visual to use for the window. -\fIVisual\fR may have any of the forms supported by the \fBTk_GetVisual\fR -procedure. -.IP "\fB\-\|\-\fR" 20 -Pass all remaining arguments through to the script's \fBargv\fR -variable without interpreting them. -This provides a mechanism for passing arguments such as \fB\-name\fR -to a script instead of having \fBwish\fR interpret them. -.BE - -.SH DESCRIPTION -.PP -\fBWish\fR is a simple program consisting of the Tcl command -language, the Tk toolkit, and a main program that reads commands -from standard input or from a file. -It creates a main window and then processes Tcl commands. -If \fBwish\fR is invoked with no arguments, or with a first argument -that starts with ``\-'', then it reads Tcl commands interactively from -standard input. -It will continue processing commands until all windows have been -deleted or until end-of-file is reached on standard input. -If there exists a file \fB.wishrc\fR in the home directory of -the user, \fBwish\fR evaluates the file as a Tcl script -just before reading the first command from standard input. -.PP -If \fBwish\fR is invoked with an initial \fIfileName\fR argument, then -\fIfileName\fR is treated as the name of a script file. -\fBWish\fR will evaluate the script in \fIfileName\fR (which -presumably creates a user interface), then it will respond to events -until all windows have been deleted. -Commands will not be read from standard input. -There is no automatic evaluation of \fB.wishrc\fR in this -case, but the script file can always \fBsource\fR it if desired. - -.SH "OPTIONS" -.PP -\fBWish\fR automatically processes all of the command-line options -described in the \fBOPTIONS\fR summary above. -Any other command-line arguments besides these are passed through -to the application using the \fBargc\fR and \fBargv\fR variables -described later. - -.SH "APPLICATION NAME AND CLASS" -.PP -The name of the application, which is used for purposes such as -\fBsend\fR commands, is taken from the \fB\-name\fR option, -if it is specified; otherwise it is taken from \fIfileName\fR, -if it is specified, or from the command name by which -\fBwish\fR was invoked. In the last two cases, if the name contains a ``/'' -character, then only the characters after the last slash are used -as the application name. -.PP -The class of the application, which is used for purposes such as -specifying options with a \fBRESOURCE_MANAGER\fR property or .Xdefaults -file, is the same as its name except that the first letter is -capitalized. - -.SH "VARIABLES" -.PP -\fBWish\fR sets the following Tcl variables: -.TP 15 -\fBargc\fR -Contains a count of the number of \fIarg\fR arguments (0 if none), -not including the options described above. -.TP 15 -\fBargv\fR -Contains a Tcl list whose elements are the \fIarg\fR arguments -that follow a \fB\-\|\-\fR option or don't match any of the -options described in OPTIONS above, in order, or an empty string -if there are no such arguments. -.TP 15 -\fBargv0\fR -Contains \fIfileName\fR if it was specified. -Otherwise, contains the name by which \fBwish\fR was invoked. -.TP 15 -\fBgeometry\fR -If the \fB\-geometry\fR option is specified, \fBwish\fR copies its -value into this variable. If the variable still exists after -\fIfileName\fR has been evaluated, \fBwish\fR uses the value of -the variable in a \fBwm geometry\fR command to set the main -window's geometry. -.TP 15 -\fBtcl_interactive\fR -Contains 1 if \fBwish\fR is reading commands interactively (\fIfileName\fR -was not specified and standard input is a terminal-like -device), 0 otherwise. - -.SH "SCRIPT FILES" -.PP -If you create a Tcl script in a file whose first line is -.CS -\fB#!/usr/local/bin/wish\fR -.CE -then you can invoke the script file directly from your shell if -you mark it as executable. -This assumes that \fBwish\fR has been installed in the default -location in /usr/local/bin; if it's installed somewhere else -then you'll have to modify the above line to match. -Many UNIX systems do not allow the \fB#!\fR line to exceed about -30 characters in length, so be sure that the \fBwish\fR executable -can be accessed with a short file name. -.PP -An even better approach is to start your script files with the -following three lines: -.CS -\fB#!/bin/sh -# the next line restarts using wish \e -exec wish "$0" "$@"\fR -.CE -This approach has three advantages over the approach in the previous -paragraph. First, the location of the \fBwish\fR binary doesn't have -to be hard-wired into the script: it can be anywhere in your shell -search path. Second, it gets around the 30-character file name limit -in the previous approach. -Third, this approach will work even if \fBwish\fR is -itself a shell script (this is done on some systems in order to -handle multiple architectures or operating systems: the \fBwish\fR -script selects one of several binaries to run). The three lines -cause both \fBsh\fR and \fBwish\fR to process the script, but the -\fBexec\fR is only executed by \fBsh\fR. -\fBsh\fR processes the script first; it treats the second -line as a comment and executes the third line. -The \fBexec\fR statement cause the shell to stop processing and -instead to start up \fBwish\fR to reprocess the entire script. -When \fBwish\fR starts up, it treats all three lines as comments, -since the backslash at the end of the second line causes the third -line to be treated as part of the comment on the second line. - -.SH PROMPTS -.PP -When \fBwish\fR is invoked interactively it normally prompts for each -command with ``\fB% \fR''. You can change the prompt by setting the -variables \fBtcl_prompt1\fR and \fBtcl_prompt2\fR. If variable -\fBtcl_prompt1\fR exists then it must consist of a Tcl script -to output a prompt; instead of outputting a prompt \fBwish\fR -will evaluate the script in \fBtcl_prompt1\fR. -The variable \fBtcl_prompt2\fR is used in a similar way when -a newline is typed but the current command isn't yet complete; -if \fBtcl_prompt2\fR isn't set then no prompt is output for -incomplete commands. - -.SH KEYWORDS -shell, toolkit diff --git a/tcl/doc/wm.n b/tcl/doc/wm.n deleted file mode 100644 index ab21e01afe..0000000000 --- a/tcl/doc/wm.n +++ /dev/null @@ -1,556 +0,0 @@ -'\" -'\" Copyright (c) 1991-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$ -'\" -.so man.macros -.TH wm n 8.4 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -wm \- Communicate with window manager -.SH SYNOPSIS -\fBwm\fR \fIoption window \fR?\fIargs\fR? -.BE - -.SH DESCRIPTION -.PP -The \fBwm\fR command is used to interact with window managers in -order to control such things as the title for a window, its geometry, -or the increments in terms of which it may be resized. The \fBwm\fR -command can take any of a number of different forms, depending on -the \fIoption\fR argument. All of the forms expect at least one -additional argument, \fIwindow\fR, which must be the path name of a -top-level window. -.PP -The legal forms for the \fBwm\fR command are: -.TP -\fBwm aspect \fIwindow\fR ?\fIminNumer minDenom maxNumer maxDenom\fR? -If \fIminNumer\fR, \fIminDenom\fR, \fImaxNumer\fR, and \fImaxDenom\fR -are all specified, then they will be passed to the window manager -and the window manager should use them to enforce a range of -acceptable aspect ratios for \fIwindow\fR. The aspect ratio of -\fIwindow\fR (width/length) will be constrained to lie -between \fIminNumer\fR/\fIminDenom\fR and \fImaxNumer\fR/\fImaxDenom\fR. -If \fIminNumer\fR etc. are all specified as empty strings, then -any existing aspect ratio restrictions are removed. -If \fIminNumer\fR etc. are specified, then the command returns an -empty string. Otherwise, it returns -a Tcl list containing four elements, which are the current values -of \fIminNumer\fR, \fIminDenom\fR, \fImaxNumer\fR, and \fImaxDenom\fR -(if no aspect restrictions are in effect, then an empty string is -returned). -.VS 8.4 -.TP -\fBwm attributes \fIwindow\fR -.TP -\fBwm attributes \fIwindow\fR ?\fBoption\fR? -.TP -\fBwm attributes \fIwindow\fR ?\fBoption value option value...\fR? -.RS -This subcommand returns or sets platform specific attributes associated -with a window. The first form returns a list of the platform specific -flags and their values. The second form returns the value for the -specific option. The third form sets one or more of the values. The -values are as follows: -.PP -On Windows, \fB-disabled\fR gets or sets whether the window is in a -disabled state. \fB-toolwindow\fR gets or sets the style of the window -to toolwindow (as defined in the MSDN). \fB-topmost\fR gets or sets -whether this is a topmost window (displays above all other windows). -.PP -On Macintosh, -.PP -On Unix, there are currently no special attribute values. -.RE -.VE 8.4 -.TP -\fBwm client \fIwindow\fR ?\fIname\fR? -If \fIname\fR is specified, this command stores \fIname\fR (which -should be the name of -the host on which the application is executing) in \fIwindow\fR's -\fBWM_CLIENT_MACHINE\fR property for use by the window manager or -session manager. -The command returns an empty string in this case. -If \fIname\fR isn't specified, the command returns the last name -set in a \fBwm client\fR command for \fIwindow\fR. -If \fIname\fR is specified as an empty string, the command deletes the -\fBWM_CLIENT_MACHINE\fR property from \fIwindow\fR. -.TP -\fBwm colormapwindows \fIwindow\fR ?\fIwindowList\fR? -This command is used to manipulate the \fBWM_COLORMAP_WINDOWS\fR -property, which provides information to the window managers about -windows that have private colormaps. -If \fIwindowList\fR isn't specified, the command returns a list -whose elements are the names of the windows in the \fBWM_COLORMAP_WINDOWS\fR -property. -If \fIwindowList\fR is specified, it consists of a list of window -path names; the command overwrites the \fBWM_COLORMAP_WINDOWS\fR -property with the given windows and returns an empty string. -The \fBWM_COLORMAP_WINDOWS\fR property should normally contain a -list of the internal windows within \fIwindow\fR whose colormaps differ -from their parents. -The order of the windows in the property indicates a priority order: -the window manager will attempt to install as many colormaps as possible -from the head of this list when \fIwindow\fR gets the colormap focus. -If \fIwindow\fR is not included among the windows in \fIwindowList\fR, -Tk implicitly adds it at the end of the \fBWM_COLORMAP_WINDOWS\fR -property, so that its colormap is lowest in priority. -If \fBwm colormapwindows\fR is not invoked, Tk will automatically set -the property for each top-level window to all the internal windows -whose colormaps differ from their parents, followed by the top-level -itself; the order of the internal windows is undefined. -See the ICCCM documentation for more information on the -\fBWM_COLORMAP_WINDOWS\fR property. -.TP -\fBwm command \fIwindow\fR ?\fIvalue\fR? -If \fIvalue\fR is specified, this command stores \fIvalue\fR in \fIwindow\fR's -\fBWM_COMMAND\fR property for use by the window manager or -session manager and returns an empty string. -\fIValue\fR must have proper list structure; the elements should -contain the words of the command used to invoke the application. -If \fIvalue\fR isn't specified then the command returns the last value -set in a \fBwm command\fR command for \fIwindow\fR. -If \fIvalue\fR is specified as an empty string, the command -deletes the \fBWM_COMMAND\fR property from \fIwindow\fR. -.TP -\fBwm deiconify \fIwindow\fR -Arrange for \fIwindow\fR to be displayed in normal (non-iconified) form. -This is done by mapping the window. If the window has never been -mapped then this command will not map the window, but it will ensure -that when the window is first mapped it will be displayed -in de-iconified form. On Windows, a deiconified window will also be -raised and be given the focus (made the active window). -Returns an empty string. -.TP -\fBwm focusmodel \fIwindow\fR ?\fBactive\fR|\fBpassive\fR? -If \fBactive\fR or \fBpassive\fR is supplied as an optional argument -to the command, then it specifies the focus model for \fIwindow\fR. -In this case the command returns an empty string. If no additional -argument is supplied, then the command returns the current focus -model for \fIwindow\fR. -An \fBactive\fR focus model means that \fIwindow\fR will claim the -input focus for itself or its descendants, even at times when -the focus is currently in some other application. \fBPassive\fR means that -\fIwindow\fR will never claim the focus for itself: the window manager -should give the focus to \fIwindow\fR at appropriate times. However, -once the focus has been given to \fIwindow\fR or one of its descendants, -the application may re-assign the focus among \fIwindow\fR's descendants. -The focus model defaults to \fBpassive\fR, and Tk's \fBfocus\fR command -assumes a passive model of focusing. -.TP -\fBwm frame \fIwindow\fR -.VS -If \fIwindow\fR has been reparented by the window manager into a -decorative frame, the command returns the platform specific window -identifier for the outermost frame that contains \fIwindow\fR (the -window whose parent is the root or virtual root). If \fIwindow\fR -hasn't been reparented by the window manager then the command returns -the platform specific window identifier for \fIwindow\fR. -.VE -.TP -\fBwm geometry \fIwindow\fR ?\fInewGeometry\fR? -If \fInewGeometry\fR is specified, then the geometry of \fIwindow\fR -is changed and an empty string is returned. Otherwise the current -geometry for \fIwindow\fR is returned (this is the most recent -geometry specified either by manual resizing or -in a \fBwm geometry\fR command). \fINewGeometry\fR has -the form \fB=\fIwidth\fBx\fIheight\fB\(+-\fIx\fB\(+-\fIy\fR, where -any of \fB=\fR, \fIwidth\fBx\fIheight\fR, or \fB\(+-\fIx\fB\(+-\fIy\fR -may be omitted. \fIWidth\fR and \fIheight\fR are positive integers -specifying the desired dimensions of \fIwindow\fR. If \fIwindow\fR -is gridded (see GRIDDED GEOMETRY MANAGEMENT below) then the dimensions -are specified in grid units; otherwise they are specified in pixel -units. \fIX\fR and \fIy\fR specify the desired location of -\fIwindow\fR on the screen, in pixels. -If \fIx\fR is preceded by \fB+\fR, it specifies -the number of pixels between the left edge of the screen and the left -edge of \fIwindow\fR's border; if preceded by \fB\-\fR then -\fIx\fR specifies the number of pixels -between the right edge of the screen and the right edge of \fIwindow\fR's -border. If \fIy\fR is preceded by \fB+\fR then it specifies the -number of pixels between the top of the screen and the top -of \fIwindow\fR's border; if \fIy\fR is preceded by \fB\-\fR then -it specifies the number of pixels between the bottom of \fIwindow\fR's -border and the bottom of the screen. -If \fInewGeometry\fR is specified as an empty string then any -existing user-specified geometry for \fIwindow\fR is cancelled, and -the window will revert to the size requested internally by its -widgets. -.TP -\fBwm grid \fIwindow\fR ?\fIbaseWidth baseHeight widthInc heightInc\fR? -This command indicates that \fIwindow\fR is to be managed as a -gridded window. -It also specifies the relationship between grid units and pixel units. -\fIBaseWidth\fR and \fIbaseHeight\fR specify the number of grid -units corresponding to the pixel dimensions requested internally -by \fIwindow\fR using \fBTk_GeometryRequest\fR. \fIWidthInc\fR -and \fIheightInc\fR specify the number of pixels in each horizontal -and vertical grid unit. -These four values determine a range of acceptable sizes for -\fIwindow\fR, corresponding to grid-based widths and heights -that are non-negative integers. -Tk will pass this information to the window manager; during -manual resizing, the window manager will restrict the window's size -to one of these acceptable sizes. -Furthermore, during manual resizing the window manager will display -the window's current size in terms of grid units rather than pixels. -If \fIbaseWidth\fR etc. are all specified as empty strings, then -\fIwindow\fR will no longer be managed as a gridded window. If -\fIbaseWidth\fR etc. are specified then the return value is an -empty string. -Otherwise the return value is a Tcl list containing -four elements corresponding to the current \fIbaseWidth\fR, -\fIbaseHeight\fR, \fIwidthInc\fR, and \fIheightInc\fR; if -\fIwindow\fR is not currently gridded, then an empty string -is returned. -Note: this command should not be needed very often, since the -\fBTk_SetGrid\fR library procedure and the \fBsetGrid\fR option -provide easier access to the same functionality. -.TP -\fBwm group \fIwindow\fR ?\fIpathName\fR? -If \fIpathName\fR is specified, it gives the path name for the leader of -a group of related windows. The window manager may use this information, -for example, to unmap all of the windows in a group when the group's -leader is iconified. \fIPathName\fR may be specified as an empty string to -remove \fIwindow\fR from any group association. If \fIpathName\fR is -specified then the command returns an empty string; otherwise it -returns the path name of \fIwindow\fR's current group leader, or an empty -string if \fIwindow\fR isn't part of any group. -.TP -\fBwm iconbitmap \fIwindow\fR ?\fIbitmap\fR? -If \fIbitmap\fR is specified, then it names a bitmap in the standard -forms accepted by Tk (see the \fBTk_GetBitmap\fR manual entry for details). -This bitmap is passed to the window manager to be displayed in -\fIwindow\fR's icon, and the command returns an empty string. If -an empty string is specified for \fIbitmap\fR, then any current icon -bitmap is cancelled for \fIwindow\fR. -If \fIbitmap\fR is specified then the command returns an empty string. -Otherwise it returns the name of -the current icon bitmap associated with \fIwindow\fR, or an empty -string if \fIwindow\fR has no icon bitmap. On the Windows operating -system, an additional flag is supported: -\fBwm iconbitmap \fIwindow\fR ?\fI-default\fR? ?\fIimage\fR?. -If the \fI-default\fR -flag is given, the icon is applied to all toplevel windows (existing -and future) to which no other specific icon has yet been applied. -In addition to bitmap image types, a full path specification to -any file which contains a valid -Windows icon is also accepted (usually .ico or .icr files), or any -file for which the shell has assigned an icon. Tcl will -first test if the file contains an icon, then if it has an assigned -icon, and finally, if that fails, test for -a bitmap. -.TP -\fBwm iconify \fIwindow\fR -Arrange for \fIwindow\fR to be iconified. It \fIwindow\fR hasn't -yet been mapped for the first time, this command will arrange for -it to appear in the iconified state when it is eventually mapped. -.TP -\fBwm iconmask \fIwindow\fR ?\fIbitmap\fR? -If \fIbitmap\fR is specified, then it names a bitmap in the standard -forms accepted by Tk (see the \fBTk_GetBitmap\fR manual entry for details). -This bitmap is passed to the window manager to be used as a mask -in conjunction with the \fBiconbitmap\fR option: where the mask -has zeroes no icon will be displayed; where it has ones, the bits -from the icon bitmap will be displayed. If -an empty string is specified for \fIbitmap\fR then any current icon -mask is cancelled for \fIwindow\fR (this is equivalent to specifying -a bitmap of all ones). If \fIbitmap\fR is specified -then the command returns an empty string. Otherwise it -returns the name of the current icon mask associated with -\fIwindow\fR, or an empty string if no mask is in effect. -.TP -\fBwm iconname \fIwindow\fR ?\fInewName\fR? -If \fInewName\fR is specified, then it is passed to the window -manager; the window manager should display \fInewName\fR inside -the icon associated with \fIwindow\fR. In this case an empty -string is returned as result. If \fInewName\fR isn't specified -then the command returns the current icon name for \fIwindow\fR, -or an empty string if no icon name has been specified (in this -case the window manager will normally display the window's title, -as specified with the \fBwm title\fR command). -.TP -\fBwm iconposition \fIwindow\fR ?\fIx y\fR? -If \fIx\fR and \fIy\fR are specified, they are passed to the window -manager as a hint about where to position the icon for \fIwindow\fR. -In this case an empty string is returned. If \fIx\fR and \fIy\fR are -specified as empty strings then any existing icon position hint is cancelled. -If neither \fIx\fR nor \fIy\fR is specified, then the command returns -a Tcl list containing two values, which are the current icon position -hints (if no hints are in effect then an empty string is returned). -.TP -\fBwm iconwindow \fIwindow\fR ?\fIpathName\fR? -If \fIpathName\fR is specified, it is the path name for a window to -use as icon for \fIwindow\fR: when \fIwindow\fR is iconified then -\fIpathName\fR will be mapped to serve as icon, and when \fIwindow\fR -is de-iconified then \fIpathName\fR will be unmapped again. If -\fIpathName\fR is specified as an empty string then any existing -icon window association for \fIwindow\fR will be cancelled. If -the \fIpathName\fR argument is specified then an empty string is -returned. Otherwise the command returns the path name of the -current icon window for \fIwindow\fR, or an empty string if there -is no icon window currently specified for \fIwindow\fR. -Button press events are disabled for \fIwindow\fR as long as it is -an icon window; this is needed in order to allow window managers -to ``own'' those events. -Note: not all window managers support the notion of an icon window. -.TP -\fBwm maxsize \fIwindow\fR ?\fIwidth height\fR? -If \fIwidth\fR and \fIheight\fR are specified, they give -the maximum permissible dimensions for \fIwindow\fR. -For gridded windows the dimensions are specified in -grid units; otherwise they are specified in pixel units. -The window manager will restrict the window's dimensions to be -less than or equal to \fIwidth\fR and \fIheight\fR. -If \fIwidth\fR and \fIheight\fR are -specified, then the command returns an empty string. Otherwise -it returns a Tcl list with two elements, which are the -maximum width and height currently in effect. -The maximum size defaults to the size of the screen. -If resizing has been disabled with the \fBwm resizable\fR command, -then this command has no effect. -See the sections on geometry management below for more information. -.TP -\fBwm minsize \fIwindow\fR ?\fIwidth height\fR? -If \fIwidth\fR and \fIheight\fR are specified, they give the -minimum permissible dimensions for \fIwindow\fR. -For gridded windows the dimensions are specified in -grid units; otherwise they are specified in pixel units. -The window manager will restrict the window's dimensions to be -greater than or equal to \fIwidth\fR and \fIheight\fR. -If \fIwidth\fR and \fIheight\fR are -specified, then the command returns an empty string. Otherwise -it returns a Tcl list with two elements, which are the -minimum width and height currently in effect. -The minimum size defaults to one pixel in each dimension. -If resizing has been disabled with the \fBwm resizable\fR command, -then this command has no effect. -See the sections on geometry management below for more information. -.TP -\fBwm overrideredirect \fIwindow\fR ?\fIboolean\fR? -If \fIboolean\fR is specified, it must have a proper boolean form and -the override-redirect flag for \fIwindow\fR is set to that value. -If \fIboolean\fR is not specified then \fB1\fR or \fB0\fR is -returned to indicate whether or not the override-redirect flag -is currently set for \fIwindow\fR. -Setting the override-redirect flag for a window causes -it to be ignored by the window manager; among other things, this means -that the window will not be reparented from the root window into a -decorative frame and the user will not be able to manipulate the -window using the normal window manager mechanisms. -.TP -\fBwm positionfrom \fIwindow\fR ?\fIwho\fR? -If \fIwho\fR is specified, it must be either \fBprogram\fR or -\fBuser\fR, or an abbreviation of one of these two. It indicates -whether \fIwindow\fR's current position was requested by the -program or by the user. Many window managers ignore program-requested -initial positions and ask the user to manually position the window; if -\fBuser\fR is specified then the window manager should position the -window at the given place without asking the user for assistance. -If \fIwho\fR is specified as an empty string, then the current position -source is cancelled. -If \fIwho\fR is specified, then the command returns an empty string. -Otherwise it returns \fBuser\fR or \fBprogram\fR to indicate the -source of the window's current position, or an empty string if -no source has been specified yet. Most window managers interpret -``no source'' as equivalent to \fBprogram\fR. -Tk will automatically set the position source to \fBuser\fR -when a \fBwm geometry\fR command is invoked, unless the source has -been set explicitly to \fBprogram\fR. -.TP -\fBwm protocol \fIwindow\fR ?\fIname\fR? ?\fIcommand\fR? -This command is used to manage window manager protocols such as -\fBWM_DELETE_WINDOW\fR. -\fIName\fR is the name of an atom corresponding to a window manager -protocol, such as \fBWM_DELETE_WINDOW\fR or \fBWM_SAVE_YOURSELF\fR -or \fBWM_TAKE_FOCUS\fR. -If both \fIname\fR and \fIcommand\fR are specified, then \fIcommand\fR -is associated with the protocol specified by \fIname\fR. -\fIName\fR will be added to \fIwindow\fR's \fBWM_PROTOCOLS\fR -property to tell the window manager that the application has a -protocol handler for \fIname\fR, and \fIcommand\fR will -be invoked in the future whenever the window manager sends a -message to the client for that protocol. -In this case the command returns an empty string. -If \fIname\fR is specified but \fIcommand\fR isn't, then the current -command for \fIname\fR is returned, or an empty string if there -is no handler defined for \fIname\fR. -If \fIcommand\fR is specified as an empty string then the current -handler for \fIname\fR is deleted and it is removed from the -\fBWM_PROTOCOLS\fR property on \fIwindow\fR; an empty string is -returned. -Lastly, if neither \fIname\fR nor \fIcommand\fR is specified, the -command returns a list of all the protocols for which handlers -are currently defined for \fIwindow\fR. -.RS -.PP -Tk always defines a protocol handler for \fBWM_DELETE_WINDOW\fR, even if -you haven't asked for one with \fBwm protocol\fR. -If a \fBWM_DELETE_WINDOW\fR message arrives when you haven't defined -a handler, then Tk handles the message by destroying the window for -which it was received. -.RE -.TP -\fBwm resizable \fIwindow\fR ?\fIwidth height\fR? -This command controls whether or not the user may interactively -resize a top-level window. If \fIwidth\fR and \fIheight\fR are -specified, they are boolean values that determine whether the -width and height of \fIwindow\fR may be modified by the user. -In this case the command returns an empty string. -If \fIwidth\fR and \fIheight\fR are omitted then the command -returns a list with two 0/1 elements that indicate whether the -width and height of \fIwindow\fR are currently resizable. -By default, windows are resizable in both dimensions. -If resizing is disabled, then the window's size will be the size -from the most recent interactive resize or \fBwm geometry\fR -command. If there has been no such operation then -the window's natural size will be used. -.TP -\fBwm sizefrom \fIwindow\fR ?\fIwho\fR? -If \fIwho\fR is specified, it must be either \fBprogram\fR or -\fBuser\fR, or an abbreviation of one of these two. It indicates -whether \fIwindow\fR's current size was requested by the -program or by the user. Some window managers ignore program-requested -sizes and ask the user to manually size the window; if -\fBuser\fR is specified then the window manager should give the -window its specified size without asking the user for assistance. -If \fIwho\fR is specified as an empty string, then the current size -source is cancelled. -If \fIwho\fR is specified, then the command returns an empty string. -Otherwise it returns \fBuser\fR or \fBwindow\fR to indicate the -source of the window's current size, or an empty string if -no source has been specified yet. Most window managers interpret -``no source'' as equivalent to \fBprogram\fR. -.TP -\fBwm stackorder \fIwindow\fR ?\fIisabove|isbelow window\fR? -The stackorder command returns a list of toplevel windows -in stacking order, from lowest to highest. When a single toplevel -window is passed, the returned list recursively includes all of the -window's children that are toplevels. Only those toplevels -that are currently mapped to the screen are returned. -The stackorder command can also be used to determine if one -toplevel is positioned above or below a second toplevel. -When two window arguments separated by either \fIisabove\fR or -\fIisbelow\fR are passed, a boolean result indicates whether -or not the first window is currently above or below the second -window in the stacking order. -.TP -\fBwm state \fIwindow\fR ?newstate? -If \fInewstate\fR is specified, the window will be set to the new state, -otherwise it returns the current state of \fIwindow\fR: either -\fBnormal\fR, \fBiconic\fR, \fBwithdrawn\fR, \fBicon\fR, or (Windows only) -\fBzoomed\fR. The difference between \fBiconic\fR and \fBicon\fR is that -\fBiconic\fR refers to a window that has been iconified (e.g., with the -\fBwm iconify\fR command) while \fBicon\fR refers to a window whose only -purpose is to serve as the icon for some other window (via the \fBwm -iconwindow\fR command). The \fBicon\fR state cannot be set. -.TP -\fBwm title \fIwindow\fR ?\fIstring\fR? -If \fIstring\fR is specified, then it will be passed to the window -manager for use as the title for \fIwindow\fR (the window manager -should display this string in \fIwindow\fR's title bar). In this -case the command returns an empty string. If \fIstring\fR isn't -specified then the command returns the current title for the -\fIwindow\fR. The title for a window defaults to its name. -.TP -\fBwm transient \fIwindow\fR ?\fImaster\fR? -If \fImaster\fR is specified, then the window manager is informed -that \fIwindow\fR is a transient window (e.g. pull-down menu) working -on behalf of \fImaster\fR (where \fImaster\fR is the -path name for a top-level window). If \fImaster\fR -is specified as an empty string then \fIwindow\fR is marked as not -being a transient window any more. Otherwise the command -returns the path name of \fIwindow\fR's current master, or an -empty string if \fIwindow\fR isn't currently a transient window. -A transient window will mirror state changes in the master and -inherit the state of the master when initially mapped. It is an -error to attempt to make a window a transient of itself. -.TP -\fBwm withdraw \fIwindow\fR -Arranges for \fIwindow\fR to be withdrawn from the screen. This -causes the window to be unmapped and forgotten about by the window -manager. If the window -has never been mapped, then this command -causes the window to be mapped in the withdrawn state. Not all -window managers appear to know how to handle windows that are -mapped in the withdrawn state. -Note: it sometimes seems to be necessary to withdraw a -window and then re-map it (e.g. with \fBwm deiconify\fR) to get some -window managers to pay attention to changes in window attributes -such as group. - -.SH "GEOMETRY MANAGEMENT" -.PP -By default a top-level window appears on the screen in its -\fInatural size\fR, which is the one determined internally by its -widgets and geometry managers. -If the natural size of a top-level window changes, then the window's size -changes to match. -A top-level window can be given a size other than its natural size in two ways. -First, the user can resize the window manually using the facilities -of the window manager, such as resize handles. -Second, the application can request a particular size for a -top-level window using the \fBwm geometry\fR command. -These two cases are handled identically by Tk; in either case, -the requested size overrides the natural size. -You can return the window to its natural by invoking \fBwm geometry\fR -with an empty \fIgeometry\fR string. -.PP -Normally a top-level window can have any size from one pixel in each -dimension up to the size of its screen. -However, you can use the \fBwm minsize\fR and \fBwm maxsize\fR commands -to limit the range of allowable sizes. -The range set by \fBwm minsize\fR and \fBwm maxsize\fR applies to -all forms of resizing, including the window's natural size as -well as manual resizes and the \fBwm geometry\fR command. -You can also use the command \fBwm resizable\fR to completely -disable interactive resizing in one or both dimensions. - -.SH "GRIDDED GEOMETRY MANAGEMENT" -.PP -Gridded geometry management occurs when one of the widgets of an -application supports a range of useful sizes. -This occurs, for example, in a text editor where the scrollbars, -menus, and other adornments are fixed in size but the edit widget -can support any number of lines of text or characters per line. -In this case, it is usually desirable to let the user specify the -number of lines or characters-per-line, either with the -\fBwm geometry\fR command or by interactively resizing the window. -In the case of text, and in other interesting cases also, only -discrete sizes of the window make sense, such as integral numbers -of lines and characters-per-line; arbitrary pixel sizes are not useful. -.PP -Gridded geometry management provides support for this kind of -application. -Tk (and the window manager) assume that there is a grid of some -sort within the application and that the application should be -resized in terms of \fIgrid units\fR rather than pixels. -Gridded geometry management is typically invoked by turning on -the \fBsetGrid\fR option for a widget; it can also be invoked -with the \fBwm grid\fR command or by calling \fBTk_SetGrid\fR. -In each of these approaches the particular widget (or sometimes -code in the application as a whole) specifies the relationship between -integral grid sizes for the window and pixel sizes. -To return to non-gridded geometry management, invoke -\fBwm grid\fR with empty argument strings. -.PP -When gridded geometry management is enabled then all the dimensions specified -in \fBwm minsize\fR, \fBwm maxsize\fR, and \fBwm geometry\fR commands -are treated as grid units rather than pixel units. -Interactive resizing is also carried out in even numbers of grid units -rather than pixels. - -.SH BUGS -.PP -Most existing window managers appear to have bugs that affect the -operation of the \fBwm\fR command. For example, some changes won't -take effect if the window is already active: the window will have -to be withdrawn and de-iconified in order to make the change happen. - -.SH KEYWORDS -aspect ratio, deiconify, focus model, geometry, grid, group, icon, iconify, increments, position, size, title, top-level window, units, window manager -- 2.11.0