Fix Tk_Get3BorderColors() signature. Add documentation, created by René Zaumseil

11 files changed, 160 insertions, 32 deletions

diff --git a/doc/3DBorder.3 b/doc/3DBorder.3
index f589e66..c9fa657 100644
--- a/doc/3DBorder.3
+++ b/doc/3DBorder.3
@@ -9,7 +9,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tk_Alloc3DBorderFromObj, Tk_Get3DBorder, Tk_Get3DBorderFromObj, Tk_Draw3DRectangle, Tk_Fill3DRectangle, Tk_Draw3DPolygon, Tk_Fill3DPolygon, Tk_3DVerticalBevel, Tk_3DHorizontalBevel, Tk_SetBackgroundFromBorder, Tk_NameOf3DBorder, Tk_3DBorderColor, Tk_3DBorderGC, Tk_Free3DBorderFromObj, Tk_Free3DBorder \- draw borders with three-dimensional appearance
+Tk_Alloc3DBorderFromObj, Tk_ClipDrawableToRect, Tk_DrawHighlightBorder, Tk_Get3DBorder, fBTk_Get3DBorderColors, Tk_Get3DBorderFromObj, Tk_Draw3DRectangle, Tk_Fill3DRectangle, Tk_Draw3DPolygon, Tk_Fill3DPolygon, Tk_3DVerticalBevel, Tk_3DHorizontalBevel, Tk_SetBackgroundFromBorder, Tk_NameOf3DBorder, Tk_3DBorderColor, Tk_3DBorderGC, Tk_Free3DBorderFromObj, Tk_Free3DBorder \- draw borders with three-dimensional appearance
 .SH SYNOPSIS
 .nf
 \fB#include <tk.h>\fR
@@ -17,9 +17,18 @@ Tk_Alloc3DBorderFromObj, Tk_Get3DBorder, Tk_Get3DBorderFromObj, Tk_Draw3DRectang
 Tk_3DBorder
 \fBTk_Alloc3DBorderFromObj(\fIinterp, tkwin, objPtr\fB)\fR
 .sp
+void
+\fBTk_ClipDrawableToRect(\fIdisplay, drawable, x, y, width, height\fB)\fR
+.sp
+void
+\fBTk_DrawHighlightBorder(\fItkwin, fgGC, bgGC, highlightWidth, drawable\fB)\fR
+.sp
 Tk_3DBorder
 \fBTk_Get3DBorder(\fIinterp, tkwin, colorName\fB)\fR
 .sp
+void
+\fBTk_Get3DBorderColors(\fIborder, bgColorPtr, darkColorPtr, lightColorPtr\fB)\fR
+.sp
 Tk_3DBorder
 \fBTk_Get3DBorderFromObj(\fItkwin, objPtr\fB)\fR
 .sp
@@ -90,6 +99,8 @@ Height of rectangle describing border or bevel, in pixels.
 Width of border in pixels. Positive means border is inside rectangle
 given by \fIx\fR, \fIy\fR, \fIwidth\fR, \fIheight\fR, negative means
 border is outside rectangle.
+.AP int highlightWidth in
+Width of ring around the outside of the widget if the widget has received the input focus.
 .AP int relief in
 Indicates 3-D position of interior of value relative to exterior;
 should be \fBTK_RELIEF_RAISED\fR, \fBTK_RELIEF_SUNKEN\fR, \fBTK_RELIEF_GROOVE\fR,
@@ -133,6 +144,16 @@ it forms the bottom side.
 .AP int which in
 Specifies which of the border's graphics contexts is desired.
 Must be \fBTK_3D_FLAT_GC\fR, \fBTK_3D_LIGHT_GC\fR, or \fBTK_3D_DARK_GC\fR.
+.AP XColor *bgColorPtr out
+Pointer to location in which to store the background color of the given border.
+.AP XColor *darkColorPtr out
+Pointer to location in which to store the color for darker areas of the given border.
+.AP XColor *lightColorPtr out
+Pointer to location in which to store the color for lighter areas of the given border.
+.AP GC fgGC in
+Foreground X graphics context.
+.AP GC fgGC in
+Background X graphics context.
 .BE
 .SH DESCRIPTION
 .PP
@@ -159,11 +180,24 @@ information about the return value in \fIobjPtr\fR, which speeds up
 future calls to \fBTk_Alloc3DBorderFromObj\fR with the same \fIobjPtr\fR
 and \fItkwin\fR.
 .PP
+\fBTk_ClipDrawableToRect\fR will clip all drawing into the drawable d to the given rectangle. If width or height are negative, reset to no clipping.
+Subsequent drawing into d is offset and clipped as specified.
+The function is only used when \fBTK_NO_DOUBLE_BUFFERING\fR is specified at compile time.
+.PP
+\fBTk_DrawHighlightBorder\fR draws a rectangular ring around the outside of a widget
+to indicate that it has received the input focus.
+On the Macintosh, this puts a 1 pixel border in the bgGC color between
+the widget and the focus ring, except in the case where highlightWidth
+is 1, in which case the border is left out. 
+For proper Mac L&F, use highlightWidth of 3.
+.PP
 \fBTk_Get3DBorder\fR is identical to \fBTk_Alloc3DBorderFromObj\fR except
 that the color is specified with a string instead of a value.  This
 prevents \fBTk_Get3DBorder\fR from caching the return value, so
 \fBTk_Get3DBorder\fR is less efficient than \fBTk_Alloc3DBorderFromObj\fR.
 .PP
+\fBTk_Get3DBorderColors\fR returns the used colors of the given border.
+.PP
 \fBTk_Get3DBorderFromObj\fR returns the token for an existing border, given
 the window and color name used to create the border.
 \fBTk_Get3DBorderFromObj\fR does not actually create the border; it must
diff --git a/doc/AddOption.3 b/doc/AddOption.3
index c1c116a..a331455 100644
--- a/doc/AddOption.3
+++ b/doc/AddOption.3
@@ -13,6 +13,9 @@ Tk_AddOption \- Add an option to the option database
 .sp
 void
 \fBTk_AddOption\fR(\fItkwin, name, value, priority\fR)
+.sp
+void
+\fBTk_GetSystemDefault\fR(\fItkwin, dbName, className\fR)
 .SH ARGUMENTS
 .AP Tk_Window tkwin in
 Token for window.
@@ -20,12 +23,16 @@ Token for window.
 Multi-element name of option.
 .AP "const char" *value in
 Value of option.
+.AP "const char" *dbName in
+The option database name.
+.AP "const char" *className in
+The name of the option class.
 .AP int priority in
 Overall priority level to use for option.
 .BE
 .SH DESCRIPTION
 .PP
-This procedure is invoked to add an option to the database
+\fBTk_AddOption\fR is invoked to add an option to the database
 associated with \fItkwin\fR's main window.  \fIName\fR
 contains the option being specified and consists of names and/or
 classes separated by asterisks or dots, in the usual X format.
@@ -46,5 +53,7 @@ user-specific startup files.
 .IP 80
 Used for options specified interactively after the application starts
 running.
+\fBTk_GetSystemDefault\fR return a Tk_Uid string representation of the given \fIdbname\fR and \fIclassName\fR of a configuration option.
+Returns NULL if there are no system defaults that match this pair.
 .SH KEYWORDS
 class, name, option, add
diff --git a/doc/MainWin.3 b/doc/MainWin.3
index 94bd7e2..b11b6cd 100644
--- a/doc/MainWin.3
+++ b/doc/MainWin.3
@@ -17,12 +17,26 @@ Tk_MainWindow, Tk_GetNumMainWindows \- functions for querying main window inform
 Tk_Window
 \fBTk_MainWindow\fR(\fIinterp\fR)
 .sp
+void
+\fBTk_SetMainMenubar\fR(\fIinterp, tkwin, menuName\fR)
+.sp
+void
+\fBTk_SetWindowMenubar\fR(\fIinterp, tkwin, oldMenuName, menuName\fR)
+.sp
 int
 \fBTk_GetNumMainWindows\fR()
 .SH ARGUMENTS
 .AS Tcl_Interp *pathName
 .AP Tcl_Interp *interp in/out
 Interpreter associated with the application.
+.AP Tk_Window tkwin in
+Token for main window.
+.AP const char *menuName in
+The name of the new menubar that the toplevel needs to be set to.
+NULL means that their is no menu now.
+.AP const char *oldMenuName in
+The name of the menubar previously set in this toplevel.
+NULL means no menu was set previously.
 .BE
 .SH DESCRIPTION
 .PP
@@ -36,5 +50,12 @@ leaves an error message in interpreter \fIinterp\fR's result.
 .PP
 \fBTk_GetNumMainWindows\fR returns a count of the number of main
 windows currently open in the current thread.
+\fBTk_SetMainMenubar\fR
+Called when a toplevel widget is brought to front. On the Macintosh,
+sets up the menubar that goes accross the top of the main monitor. On
+other platforms, nothing is necessary.
+\fBTk_SetWindowMenubar\fR associates a menu with a window.
+The old menu clones for the menubar are thrown away, and a handler is
+set up to allocate the new ones.
 .SH KEYWORDS
 application, main window
diff --git a/doc/WinUtil.3 b/doc/WinUtil.3
new file mode 100644
index 0000000..253ed19
--- /dev/null
+++ b/doc/WinUtil.3
@@ -0,0 +1,64 @@
+'\"
+'\" 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.
+'\"
+.TH Tk_ConfigureWindow 3 4.0 Tk "Tk Library Procedures"
+.so man.macros
+.BS
+.SH NAME
+Tk_GetOtherWindow, Tk_MakeContainer, Tk_MakeWindow, Tk_UseWindow \- window utility functions
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+Tk_Window
+\fBTk_GetOtherWindow(\fItkwin\fB)\fR
+.sp
+\fBTk_MakeContainer(\fItkwin\fB)\fR
+.sp
+\fBTk_MakeWindow(\fItkwin, parent\fB)\fR
+.sp
+int
+\fBTk_UseWindow(\fIinterp, tkwin, string\fB)\fR
+.SH ARGUMENTS
+.AS XSetWindowAttributes borderWidth
+.AP Tcl_Interp * interp in
+Interpreter associated with the application.
+.AP Tk_Window tkwin in
+Token for window.
+.AP Window parent in
+Parent window.
+.AP "const char" *string in
+String identifying an X window to use for \fItkwin\fR; must be an integer value.
+.BE
+.SH DESCRIPTION
+.PP
+If both the container and embedded window are in the same process,
+\fBTk_GetOtherWindow\fR will return either one, given the other.
+If winPtr is a container, the return value is the token for the
+embedded window, and vice versa. If the "other" window isn't in this
+process, NULL is returned.
+.PP
+\fBTk_MakeContainer\fR is called to indicate that a particular window will be a
+container for an embedded application. This changes certain aspects of
+the window's behavior, such as whether it will receive events anymore.
+.PP
+\fBTk_MakeWindow\fR creates an actual window system window object based on the
+current attributes of the specified TkWindow. It returns the handle to the new
+window, or None on failure.
+.PP
+\fBTk_UseWindow\fR causes a Tk window to use a given X window as its
+parent window, rather than the root window for the screen. It is
+invoked by an embedded application to specify the window in which it
+is embedded.
+.PP
+The return value is normally TCL_OK. If an error occurs (such as
+string not being a valid window spec), then the return value is
+TCL_ERROR and an error message is left in the interp's result if
+interp is non-NULL.
+.PP
+.SH KEYWORDS
+parent, window
diff --git a/generic/tk.decls b/generic/tk.decls
index 09ab494..7c459b2 100644
--- a/generic/tk.decls
+++ b/generic/tk.decls
@@ -1124,10 +1124,10 @@ declare 287 {
     void Tk_MakeContainer(Tk_Window tkwin)
 }
 declare 288 {
-    Tk_Window Tk_GetOtherWindow(Tk_Window winPtr)
+    Tk_Window Tk_GetOtherWindow(Tk_Window tkwin)
 }
 declare 289 {
-    void Tk_Get3BorderColors(Tk_3DBorder *borderPtr, XColor *bgColorPtr, XColor *darkColorPtr,
+    void Tk_Get3DBorderColors(Tk_3DBorder border, XColor *bgColorPtr, XColor *darkColorPtr,
 	    XColor *lightColorPtr)
 }
 declare 290 {
diff --git a/generic/tk3d.c b/generic/tk3d.c
index 16871a7..65ae8d0 100644
--- a/generic/tk3d.c
+++ b/generic/tk3d.c
@@ -1405,20 +1405,20 @@ TkDebugBorder(
  */
 
 void
-Tk_Get3BorderColors(
-    Tk_3DBorder * borderPtr,
-    XColor * bgColorPtr,
-    XColor * darkColorPtr,
-    XColor * lightColorPtr)
+Tk_Get3DBorderColors(
+    Tk_3DBorder border,
+    XColor *bgColorPtr,
+    XColor *darkColorPtr,
+    XColor *lightColorPtr)
 {
     if (bgColorPtr) {
-	*bgColorPtr = *((TkBorder *)borderPtr)->bgColorPtr;
+	*bgColorPtr = *((TkBorder *)border)->bgColorPtr;
     }
     if (darkColorPtr) {
-	*darkColorPtr = *((TkBorder *) borderPtr)->darkColorPtr;
+	*darkColorPtr = *((TkBorder *) border)->darkColorPtr;
     }
     if (lightColorPtr) {
-	*lightColorPtr = *((TkBorder *) borderPtr)->lightColorPtr;
+	*lightColorPtr = *((TkBorder *) border)->lightColorPtr;
     }
 }
 
diff --git a/generic/tkDecls.h b/generic/tkDecls.h
index baad02c..dc3563a 100644
--- a/generic/tkDecls.h
+++ b/generic/tkDecls.h
@@ -919,9 +919,9 @@ EXTERN int		Tk_UseWindow(Tcl_Interp *interp, Tk_Window tkwin,
 /* 287 */
 EXTERN void		Tk_MakeContainer(Tk_Window tkwin);
 /* 288 */
-EXTERN Tk_Window	Tk_GetOtherWindow(Tk_Window winPtr);
+EXTERN Tk_Window	Tk_GetOtherWindow(Tk_Window tkwin);
 /* 289 */
-EXTERN void		Tk_Get3BorderColors(Tk_3DBorder *borderPtr,
+EXTERN void		Tk_Get3DBorderColors(Tk_3DBorder border,
 				XColor *bgColorPtr, XColor *darkColorPtr,
 				XColor *lightColorPtr);
 /* 290 */
@@ -1226,8 +1226,8 @@ typedef struct TkStubs {
     Tcl_Obj * (*tk_GetSystemDefault) (Tk_Window tkwin, const char *dbName, const char *className); /* 285 */
     int (*tk_UseWindow) (Tcl_Interp *interp, Tk_Window tkwin, const char *string); /* 286 */
     void (*tk_MakeContainer) (Tk_Window tkwin); /* 287 */
-    Tk_Window (*tk_GetOtherWindow) (Tk_Window winPtr); /* 288 */
-    void (*tk_Get3BorderColors) (Tk_3DBorder *borderPtr, XColor *bgColorPtr, XColor *darkColorPtr, XColor *lightColorPtr); /* 289 */
+    Tk_Window (*tk_GetOtherWindow) (Tk_Window tkwin); /* 288 */
+    void (*tk_Get3DBorderColors) (Tk_3DBorder border, XColor *bgColorPtr, XColor *darkColorPtr, XColor *lightColorPtr); /* 289 */
     Window (*tk_MakeWindow) (Tk_Window tkwin, Window parent); /* 290 */
 } TkStubs;
 
@@ -1819,8 +1819,8 @@ extern const TkStubs *tkStubsPtr;
 	(tkStubsPtr->tk_MakeContainer) /* 287 */
 #define Tk_GetOtherWindow \
 	(tkStubsPtr->tk_GetOtherWindow) /* 288 */
-#define Tk_Get3BorderColors \
-	(tkStubsPtr->tk_Get3BorderColors) /* 289 */
+#define Tk_Get3DBorderColors \
+	(tkStubsPtr->tk_Get3DBorderColors) /* 289 */
 #define Tk_MakeWindow \
 	(tkStubsPtr->tk_MakeWindow) /* 290 */
 
diff --git a/generic/tkStubInit.c b/generic/tkStubInit.c
index 17643e2..8a18796 100644
--- a/generic/tkStubInit.c
+++ b/generic/tkStubInit.c
@@ -1354,7 +1354,7 @@ const TkStubs tkStubs = {
     Tk_UseWindow, /* 286 */
     Tk_MakeContainer, /* 287 */
     Tk_GetOtherWindow, /* 288 */
-    Tk_Get3BorderColors, /* 289 */
+    Tk_Get3DBorderColors, /* 289 */
     Tk_MakeWindow, /* 290 */
 };
 
diff --git a/macosx/tkMacOSXEmbed.c b/macosx/tkMacOSXEmbed.c
index a5de2f1..3f5d0a4 100644
--- a/macosx/tkMacOSXEmbed.c
+++ b/macosx/tkMacOSXEmbed.c
@@ -644,7 +644,7 @@ TkpRedirectKeyEvent(
  *	this procedure will return either one, given the other.
  *
  * Results:
- *	If winPtr is a container, the return value is the token for the
+ *	If tkwin is a container, the return value is the token for the
  *	embedded window, and vice versa. If the "other" window isn't in this
  *	process, NULL is returned.
  *
@@ -656,7 +656,7 @@ TkpRedirectKeyEvent(
 
 Tk_Window
 Tk_GetOtherWindow(
-    Tk_Window winPtr)		/* Tk's structure for a container or embedded
+    Tk_Window tkwin)		/* Tk's structure for a container or embedded
 				 * window. */
 {
     Container *containerPtr;
@@ -666,15 +666,15 @@ Tk_GetOtherWindow(
      * process...
      */
 
-    if (!(((TkWindow *)winPtr)->flags & TK_BOTH_HALVES)) {
+    if (!(((TkWindow *)tkwin)->flags & TK_BOTH_HALVES)) {
 	return NULL;
     }
 
     for (containerPtr = firstContainerPtr; containerPtr != NULL;
 	    containerPtr = containerPtr->nextPtr) {
-	if ((Tk_Window)containerPtr->embeddedPtr == winPtr) {
+	if ((Tk_Window)containerPtr->embeddedPtr == tkwin) {
 	    return (Tk_Window)containerPtr->parentPtr;
-	} else if ((Tk_Window)containerPtr->parentPtr == winPtr) {
+	} else if ((Tk_Window)containerPtr->parentPtr == tkwin) {
 	    return (Tk_Window)containerPtr->embeddedPtr;
 	}
     }
diff --git a/unix/tkUnixEmbed.c b/unix/tkUnixEmbed.c
index 8881ec5..3057729 100644
--- a/unix/tkUnixEmbed.c
+++ b/unix/tkUnixEmbed.c
@@ -698,7 +698,7 @@ EmbedSendConfigure(
  *	this function will return either one, given the other.
  *
  * Results:
- *	If winPtr is a container, the return value is the token for the
+ *	If tkwin is a container, the return value is the token for the
  *	embedded window, and vice versa. If the "other" window isn't in this
  *	process, NULL is returned.
  *
@@ -710,7 +710,7 @@ EmbedSendConfigure(
 
 Tk_Window
 Tk_GetOtherWindow(
-    Tk_Window winPtr)		/* Tk's structure for a container or embedded
+    Tk_Window tkwin)		/* Tk's structure for a container or embedded
 				 * window. */
 {
     Container *containerPtr;
@@ -720,9 +720,9 @@ Tk_GetOtherWindow(
     for (containerPtr = tsdPtr->firstContainerPtr;
             containerPtr != NULL;
 	    containerPtr = containerPtr->nextPtr) {
-	if ((Tk_Window)containerPtr->embeddedPtr == winPtr) {
+	if ((Tk_Window)containerPtr->embeddedPtr == tkwin) {
 	    return (Tk_Window)containerPtr->parentPtr;
-	} else if ((Tk_Window)containerPtr->parentPtr == winPtr) {
+	} else if ((Tk_Window)containerPtr->parentPtr == tkwin) {
 	    return (Tk_Window)containerPtr->embeddedPtr;
 	}
     }
diff --git a/win/tkWinEmbed.c b/win/tkWinEmbed.c
index 3725439..7a10795 100644
--- a/win/tkWinEmbed.c
+++ b/win/tkWinEmbed.c
@@ -895,7 +895,7 @@ ContainerEventProc(
  *	this procedure will return either one, given the other.
  *
  * Results:
- *	If winPtr is a container, the return value is the token for the
+ *	If tkwin is a container, the return value is the token for the
  *	embedded window, and vice versa. If the "other" window isn't in this
  *	process, NULL is returned.
  *
@@ -907,7 +907,7 @@ ContainerEventProc(
 
 Tk_Window
 Tk_GetOtherWindow(
-    Tk_Window winPtr)		/* Tk's structure for a container or embedded
+    Tk_Window tkwin)		/* Tk's structure for a container or embedded
 				 * window. */
 {
     Container *containerPtr;
@@ -916,9 +916,9 @@ Tk_GetOtherWindow(
 
     for (containerPtr = tsdPtr->firstContainerPtr; containerPtr != NULL;
 	    containerPtr = containerPtr->nextPtr) {
-	if ((Tk_Window)containerPtr->embeddedPtr == winPtr) {
+	if ((Tk_Window)containerPtr->embeddedPtr == tkwin) {
 	    return (Tk_Window)containerPtr->parentPtr;
-	} else if ((Tk_Window)containerPtr->parentPtr == winPtr) {
+	} else if ((Tk_Window)containerPtr->parentPtr == tkwin) {
 	    return (Tk_Window)containerPtr->embeddedPtr;
 	}
     }