Author:         René Zaumseil <[email protected]>
State:          Final
Type:           Project
Vote:           Done
Created:        15-Jul-2021
Post-History:   
Keywords:       Tk
Tcl-Version:    8.7
Tk-branch:      tip-606
Vote-Summary:   Accepted 6/0/0
Votes-For:      BG, FV, JN, MC, SL, KW
Votes-Against:  none
Votes-Present:  none

Abstract

This TIP proposes to provide public Tk functions for the following private functions:

void Tk_ClipDrawableToRect(Display * display, Drawable d, int x, int y, int width, int height);

void Tk_DrawHighlightBorder(Tk_Window tkwin, GC fgGC, GC bgGC, int highlightWidth, Drawable drawable);

Tcl_Obj *Tk_GetSystemDefault(Tk_Window tkwin, const char * dbName, const char * className);

int Tk_UseWindow(Tcl_Interp * interp, Tk_Window tkwin, const char * string);

void Tk_MakeContainer(Tk_Window tkwin);

Window Tk_MakeWindow(Tk_Window tkwin, Window parent);

Tk_Window Tk_GetOtherWindow(Tk_Window tkwin);

void Tk_SetMainMenubar(Tcl_Interp * interp, Tk_Window tkwin, const char * menuName);

void Tk_SetWindowMenubar(Tcl_Interp * interp, Tk_Window tkwin, const char * oldMenuName, const char * menuName);

The public function will have the same parameters as the private functions. Only the names will start with "Tk_" instead of "Tkp".

To get the colors from a border I would propose the following function:

void Tk_Get3BorderColors(Tk_3DBorder border, XColor * bgColorPtr, XColor * darkColorPtr, XColor * lightColorPtr);

Rationale

On creation of new Tk widget types in extensions it is necessary to call private Tk functions. So extensions depend on a specific Tk version. If the needed functions exist as public functions these dependencies are gone.

C-Implementation

The implementation is in the tip-606 branch. Courtesy to Jan Nijtmans for providing it.

Here is the source code of the new function to return the color values of the border. Alternatively we could provide one function for each of the 3 color values.

void Tk_Get3BorderColors(
                Tk_3DBorder border,
                XColor *bgColorPtr,
                XColor *darkColorPtr,
                XColor *lightColorPtr)
{
    if (bgColorPtr) {
	*bgColorPtr = *((TkBorder *)border)->bgColorPtr;
    }
    if (darkColorPtr) {
	*darkColorPtr = *((TkBorder *) border)->darkColorPtr;
    }
    if (lightColorPtr) {
	*lightColorPtr = *((TkBorder *) border)->lightColorPtr;
    }
}

Documentation

The following documentation is from inside the source files. these documentation will be added in the Tk C API documentation.

Added to 3DBorder.3

void Tk_ClipDrawableToRect(Display * display, Drawable d, int x, int y, int width, int height);

Clip all drawing into the drawable d to the given rectangle. If width or height are negative, reset to no clipping.

Side effects: Subsequent drawing into d is offset and clipped as specified.

void Tk_DrawHighlightBorder(Tk_Window tkwin, GC fgGC, GC bgGC, int highlightWidth, Drawable drawable);

This function draws a rectangular ring around the outside of a widget to indicate that it has received the input focus.

On Windows, we just draw the simple inset ring. On other sytems, e.g. the Mac, the focus ring is a little more complicated, so we need this abstraction.

Side effects: A rectangle "width" pixels wide is drawn in "drawable", corresponding to the outer area of "tkwin".

void Tk_Get3BorderColors(Tk_3DBorder border, XColor * bgColorPtr, XColor * darkColorPtr, XColor * lightColorPtr);

The function returns the 3 used color values of an border object.

Added to AddOption.3

Tcl_Obj *Tk_GetSystemDefault(Tk_Window tkwin, const char * dbName, const char * className);

Given a dbName and className for a configuration option, return a string representation of the option.

Results: Returns a Tk_Uid that is the string identifier that identifies this option. Returns NULL if there are no system defaults that match this pair.

Added to MainWin.3

void Tk_SetMainMenubar(Tcl_Interp * interp, Tk_Window tkwin, const char * menuName);

Puts the menu associated with a window into the menubar. Should only be called when the window is in front.

Side effects: The menubar is changed.

void Tk_SetWindowMenubar(Tcl_Interp * interp, Tk_Window tkwin, const char * menuName);

Associates a menu with a window.

Side effects: The old menu clones for the menubar are thrown away, and a handler is set up to allocate the new ones.

New documentation page WinUtil.3

int Tk_UseWindow(Tcl_Interp * interp, Tk_Window tkwin, const char * string);

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

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

Side effects: Changes the colormap and other visual information to match that of the parent window given by "string".

void Tk_MakeContainer(Tk_Window tkwin);

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

Window Tk_MakeWindow(Tk_Window tkwin, Window parent);

This function creates an X window (Mac subwindow) and returns the window id of the created window.