TIP 606: Export more private Tk functions

Login
Bounty program for improvements to Tcl and certain Tcl packages.
Author:         RenĂ© Zaumseil <[email protected]>
State:          Draft
Type:           Project
Created:        15-Jul-2021
Post-History:   
Keywords:       Tcl
Tcl-Version:    8.7

Abstract

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

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

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

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

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

TkWindow * Tk_GetOtherWindow(TkWindow * winPtr);

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 * borderPtr, 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

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 * borderPtr,
                XColor * bgColorPtr,
                XColor * darkColorPtr,
                XColor * lightColorPtr)
{
    bgColorPtr = ((TkBorder *)borderPtr)->bgColorPtr;
    darkColorPtr = ((TkBorder *) borderPtr)->darkColorPtr;
    lightColorPtr = ((TkBorder *) borderPtr)->lightColorPtr;
}

Documentation

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

It is still to decide if each functions is documented in a separate page or if it is added to exsiting pages.

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

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.

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.

TkWindow * Tk_GetOtherWindow(TkWindow * winPtr);

If both the container and embedded window are in the same process, this procedure will return either one, given the other.

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

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

The function return the 3 used color values of an border object. The color values are valid as long as the border object exists.

Copyright

This document has been placed in the public domain.