Chapter 21. C Widget Internals

21.1.3.1. Tk::Square instance structure

Every Tk::Square instance is in reality modeled by a C Square structure. The widget creation subroutine, Tk_SquareCmd, mallocs memory for the structure, then initializes its members. Although programming at the C level is not object oriented, we can think of the Square structure as an object that maintains the widget's entire state. During widget destruction, we must release the structure's allocated memory.

typedef struct {
    Tk_Window tkwin;        /* Window that embodies the square.  NULL
                             * means window has been deleted but
                             * widget record hasn't been cleaned up yet. */
    Display *display;       /* X's token for the window's display. */
    Tcl_Interp *interp;     /* Interpreter associated with widget. */
    Tcl_Command widgetCmd;  /* Token for square's widget command. */
    int x, y;               /* Position of square's upper-left corner
                             * within widget. */
    int size;               /* Width and height of square. */

    int borderWidth;        /* Width of 3-D border around whole widget. */
    Tk_3DBorder bgBorder;   /* Used for drawing background. */
    Tk_3DBorder fgBorder;   /* For drawing square. */
    int relief;             /* Indicates whether window as a whole is
                             * raised, sunken, or flat. */
    GC gc;                  /* Graphics context for copying from
                             * off-screen pixmap onto screen. */
    int doubleBuffer;       /* Non-zero means double-buffer redisplay
                             * with pixmap;  zero means draw straight
                             * onto the display. */
    int updatePending;      /* Non-zero means a call to SquareDisplay
                             * has already been scheduled. */
} Square;

21.1.3.2. Tk::Square configuration specifications

The following table of configuration specifications should look strikingly familiar. Yes, here we define the legal widget options, which can appear on the widget creation command, or cget and configure methods. The first element of each option describes what it is, followed by the option name, resource DB name, resource DB class, and default value (the same as a ConfigSpecs entry for a Perl mega-widget).

One interesting option is -dbl, which specifies how the widget is displayed. For efficiency, and to reduce flicker, widgets are often double buffered; that is, drawn in an off-screen pixmap and then displayed. If -dbl is disabled (false), the widget is drawn directly to the screen.

static Tk_ConfigSpec configSpecs[] = {
    {TK_CONFIG_BORDER, "-background", "background", "Background",
            "#d9d9d9", Tk_Offset(Square, bgBorder), TK_CONFIG_COLOR_ONLY},
    {TK_CONFIG_BORDER, "-background", "background", "Background",
            "white", Tk_Offset(Square, bgBorder), TK_CONFIG_MONO_ONLY},
    {TK_CONFIG_SYNONYM, "-bd", "borderWidth", NULL,
            NULL, 0, 0},
    {TK_CONFIG_SYNONYM, "-bg", "background", NULL,
            NULL, 0, 0},
    {TK_CONFIG_PIXELS, "-borderwidth", "borderWidth", "BorderWidth",
            "2", Tk_Offset(Square, borderWidth), 0},
    {TK_CONFIG_INT, "-dbl", "doubleBuffer", "DoubleBuffer",
            "1", Tk_Offset(Square, doubleBuffer), 0},
    {TK_CONFIG_SYNONYM, "-fg", "foreground", NULL,
            NULL, 0, 0},
    {TK_CONFIG_BORDER, "-foreground", "foreground", "Foreground",
            "#b03060", Tk_Offset(Square, fgBorder), TK_CONFIG_COLOR_ONLY},
    {TK_CONFIG_BORDER, "-foreground", "foreground", "Foreground",
            "black", Tk_Offset(Square, fgBorder), TK_CONFIG_MONO_ONLY},
    {TK_CONFIG_RELIEF, "-relief", "relief", "Relief",
            "raised", Tk_Offset(Square, relief), 0},
    {TK_CONFIG_END, NULL, NULL, NULL,
             NULL, 0, 0}
};

21.1.3.3. Tk::Square instance constructor

All C widgets have a creation command of the form 'Tk_' . $widget_class . 'Cmd', in this case, Tk_SquareCmd. When an object of class Square is instantiated, the subroutine is called and it allocates, initializes, and configures a Square struct, and returns a standard Tcl integer result. The next section describes how the function is advertised so the rest of Tk can see it, and we can create widgets.

In Tcl, the ClientData parameter is a single word that can hold an integer or pointer value. Its interpretation is application specific, and Tk uses it to hold various data, such as the Tk_Window or Square struct pointers. If this were Tcl/Tk code, Tcl_Interp would point to an instance of the wish interpreter, but in Perl/Tk, it's a private Perl object[60] that should be left alone. Arguments are passed just like shell command-line arguments, with an argument count and a pointer to a list of strings.

[60] As of Tk 800.018, it maps Tk_Window pathnames to Perl objects and is subject to change without notice.

int
Tk_SquareCmd(clientData, interp, argc, args)
    ClientData clientData;   /* Main window associated with
                              * interpreter. */
    Tcl_Interp *interp;      /* Current interpreter. */
    int argc;                /* Number of arguments. */
    Arg *args;               /* Argument strings. */
{
    Tk_Window mainw = (Tk_Window) clientData;
    Square *squarePtr;
    Tk_Window tkwin;
    char *name;

    if (argc < 2) {
        Tcl_AppendResult(interp, "wrong # args: should be \"",
                LangString(args[0]), " pathName ?options?\"",  NULL);
        return TCL_ERROR;
    }

Create the Square's window and initialize its class, used for resource database lookups. The window isn't visible on the display, because it hasn't been mapped by a geometry manager. Note how users can change the widget's class by using -class.

    tkwin = Tk_CreateWindowFromPath(interp, mainw, LangString(args[1]), 
            NULL);
    if (tkwin == NULL) {
        return TCL_ERROR;
    }
    name = "Square";
    if ((argc>3) && !strcmp(LangString(args[2]),"-class")) {
        argc -= 2;
        args += 2;
        name = LangString(args[1]);
    }
    Tk_SetClass(tkwin, name);

Allocate the Square structure and initialize it:

    squarePtr = (Square *) ckalloc(sizeof(Square));
    squarePtr->tkwin = tkwin;
    squarePtr->display = Tk_Display(tkwin);
    squarePtr->interp = interp;
    squarePtr->widgetCmd = Lang_CreateWidget(interp,squarePtr->tkwin, 
            SquareWidgetCmd, (ClientData) squarePtr,
            SquareCmdDeletedProc);

    squarePtr->x = 0;
    squarePtr->y = 0;
    squarePtr->size = 20;
    squarePtr->borderWidth = 0;
    squarePtr->bgBorder = NULL;
    squarePtr->fgBorder = NULL;
    squarePtr->relief = TK_RELIEF_FLAT;
    squarePtr->gc = None;
    squarePtr->doubleBuffer = 1;
    squarePtr->updatePending = 0;

Register the event processing subroutine SquareEventProc and the events that interest it. The ExposureMask bit selects Expose events, and the StructureNotifyMask bit selects both ConfigureNotify and DestroyNotify events. When SquareEventProc is called, its ClientData argument is the widget's structure pointer, squarePtr.

    Tk_CreateEventHandler(squarePtr->tkwin,
        ExposureMask|StructureNotifyMask,
        SquareEventProc, (ClientData) squarePtr);

Perform the initial widget configuration, using values from argc and resource database lookups.

    if (SquareConfigure(interp, squarePtr, argc-2, args+2, 0) != TCL_OK) {
        Tk_DestroyWindow(squarePtr->tkwin);
        return TCL_ERROR;
    }

    Tcl_ArgResult(interp,LangWidgetArg(interp,squarePtr->tkwin));
    return TCL_OK;
}

21.1.3.4. Tk::Square method processors

Now that we can create a Tk::Square widget, we need to write C code to handle method calls against it. Every C widget has a subroutine name of the form $widget_class.'WidgetCmd'; in this case, SquareWidgetCmd.

static int
SquareWidgetCmd(clientData, interp, argc, args)
    ClientData clientData;          /* Information about square widget. */
    Tcl_Interp *interp;             /* Current interpreter. */
    int argc;                       /* Number of arguments. */
    Arg *args;                      /* Argument strings. */
{
    Square *squarePtr = (Square *) clientData;
    int result = TCL_OK;
    size_t length;
    char c;

    if (argc < 2) {
        Tcl_AppendResult(interp, "wrong # args: should be \"",
                LangString(args[0]), " option ?arg arg ...?\"", NULL);
        return TCL_ERROR;
    }
    Tcl_Preserve((ClientData) squarePtr);
    c = LangString(args[1])[0];
    length = strlen(LangString(args[1]));

Here is the method processing code for the cget, configure, position, and size methods. Hopefully the code is obvious.

    if ((c == 'c') &&
            (strncmp(LangString(args[1]), "cget", length) == 0) && 
            (length >= 2)) {
        if (argc != 3) {
            Tcl_AppendResult(interp, "wrong # args: should be \"",
                    LangString(args[0]), " cget option\"", NULL);
            goto error;
        }
        result = Tk_ConfigureValue(interp, squarePtr->tkwin, configSpecs,
                (char *) squarePtr, LangString(args[2]), 0);
    } else if ((c == 'c') &&
            (strncmp(LangString(args[1]), "configure", length) == 0) &&
            (length >= 2)) {
        if (argc == 2) {
            result = Tk_ConfigureInfo(interp, squarePtr->tkwin,
                     configSpecs, (char *) squarePtr, NULL, 0);
        } else if (argc == 3) {
            result = Tk_ConfigureInfo(interp, squarePtr->tkwin,
                     configSpecs, (char *) squarePtr,
                     LangString(args[2]), 0);
        } else {
            result = SquareConfigure(interp, squarePtr, argc-2, args+2,
                    TK_CONFIG_ARGV_ONLY);
        }
    } else if ((c == 'p') &&
            (strncmp(LangString(args[1]), "position", length) == 0)) {
        if ((argc != 2) && (argc != 4)) {
            Tcl_AppendResult(interp, "wrong # args: should be \"",
                    LangString(args[0]), " position ?x y?\"", NULL);
            goto error;
        }
        if (argc == 4) {
            if ((Tk_GetPixels(interp, squarePtr->tkwin, LangString(args[2]),
                    &squarePtr->x) != TCL_OK) || (Tk_GetPixels(interp,
                    squarePtr->tkwin, LangString(args[3]), &squarePtr->y) 
                    != TCL_OK)) {
                goto error;
            }
            KeepInWindow(squarePtr);
        }
        Tcl_IntResults(interp,2,0, squarePtr->x, squarePtr->y);
    } else if ((c == 's') &&
            (strncmp(LangString(args[1]), "size", length) == 0)) {
        if ((argc != 2) && (argc != 3)) {
            Tcl_AppendResult(interp, "wrong # args: should be \"",
                    LangString(args[0]), " size ?amount?\"", NULL);
            goto error;
        }
        if (argc == 3) {
            int i;

            if (Tk_GetPixels(interp, squarePtr->tkwin, LangString(args[2]), 
                    &i) != TCL_OK) {
                goto error;
            }
            if ((i <= 0) || (i > 100)) {
                Tcl_AppendResult(interp, "bad size \"", LangString(args[2]),
                        "\"", NULL);
               goto error;
            }
            squarePtr->size = i;
            KeepInWindow(squarePtr);
        }
        Tcl_IntResults(interp,1,0, squarePtr->size);
    } else {
        Tcl_AppendResult(interp, "bad option \"", LangString(args[1]),
                "\": must be cget, configure, position, or size", NULL);
        goto error;
    }

Queue a DoWhenIdle callback to display the Square unless an update is already pending.

    if (!squarePtr->updatePending) {
        Tcl_DoWhenIdle(SquareDisplay, (ClientData) squarePtr);
        squarePtr->updatePending = 1;
    }
    Tcl_Release((ClientData) squarePtr);
    return result;

    error:
    Tcl_Release((ClientData) squarePtr);
    return TCL_ERROR;
}

21.1.3.5. Tk::Square option configurator

Subroutine SquareConfigure handles all configuration requests for a Tk::Square widget:

static int
SquareConfigure(interp, squarePtr, argc, args, flags)
    Tcl_Interp *interp;      /* Used for error reporting. */
    Square *squarePtr;       /* Information about widget. */
    int argc;                /* Number of valid entries in args. */
    Arg *args;               /* Arguments. */
    int flags;               /* Flags to pass to
                              * Tk_ConfigureWidget. */
{
    if (Tk_ConfigureWidget(interp, squarePtr->tkwin, configSpecs,
            argc, args, (char *) squarePtr, flags) != TCL_OK) {
        return TCL_ERROR;
    }

Set the window's background color. If double buffering, create a graphics context:

    Tk_SetWindowBackground(squarePtr->tkwin,
            Tk_3DBorderColor(squarePtr->bgBorder)->pixel);
    if ((squarePtr->gc == None) && (squarePtr->doubleBuffer)) {
        XGCValues gcValues;
        gcValues.function = GXcopy;
        gcValues.graphics_exposures = False;
        squarePtr->gc = Tk_GetGC(squarePtr->tkwin,
                GCFunction|GCGraphicsExposures, &gcValues);
    }

Set the window's geometry and queue a DoWhenIdle event to display it:

    Tk_GeometryRequest(squarePtr->tkwin, 200, 150);
    Tk_SetInternalBorder(squarePtr->tkwin, squarePtr->borderWidth);
    if (!squarePtr->updatePending) {
        Tcl_DoWhenIdle(SquareDisplay, (ClientData) squarePtr);
        squarePtr->updatePending = 1;
    }
    return TCL_OK;
}

21.1.3.6. Tk::Square event handler

Subroutine SquareEventProc is invoked by Tk's event dispatcher, based on the events selected when Tk_SquareCmd queued this handler. If you've run the square demonstration program and tried to drag the square outside its window, then you've noticed that you can't. That's because the ConfigureNotify event makes calls to KeepInWindow, the subroutine that enforces that rule.

static void
SquareEventProc(clientData, eventPtr)
    ClientData clientData;   /* Information about window. */
    XEvent *eventPtr;        /* Information about event. */
{
    Square *squarePtr = (Square *) clientData;

    if (eventPtr->type == Expose) {
        if (!squarePtr->updatePending) {
            Tcl_DoWhenIdle(SquareDisplay, (ClientData) squarePtr);
            squarePtr->updatePending = 1;
        }
    } else if (eventPtr->type == ConfigureNotify) {
        KeepInWindow(squarePtr);
        if (!squarePtr->updatePending) {
            Tcl_DoWhenIdle(SquareDisplay, (ClientData) squarePtr);
            squarePtr->updatePending = 1;
        }
    } else if (eventPtr->type == DestroyNotify) {
        if (squarePtr->tkwin != NULL) {
            squarePtr->tkwin = NULL;
            Lang_DeleteWidget(squarePtr->interp, squarePtr->widgetCmd);
        }
        if (squarePtr->updatePending) {
            Tcl_CancelIdleCall(SquareDisplay, (ClientData) squarePtr);
        }
        Tcl_EventuallyFree((ClientData) squarePtr, SquareDestroy);
    }
}

static void
KeepInWindow(squarePtr)
    register Square *squarePtr;         /* Pointer to widget record. */
{
    int i, bd;
    bd = 0;
    if (squarePtr->relief != TK_RELIEF_FLAT) {
        bd = squarePtr->borderWidth;
    }
    i = (Tk_Width(squarePtr->tkwin) - bd) - (squarePtr->x + squarePtr->size);
    if (i < 0) {
        squarePtr->x += i;
    }
    i = (Tk_Height(squarePtr->tkwin) - bd) - (squarePtr->y + squarePtr->size);
    if (i < 0) {
        squarePtr->y += i;
    }
    if (squarePtr->x < bd) {
        squarePtr->x = bd;
    }
    if (squarePtr->y < bd) {
        squarePtr->y = bd;
    }
}

21.1.3.7. Tk::Square drawing handler

Subroutine SquareDisplay runs as a DoWhenIdle handler. This is the code responsible for displaying the widget. Note that a Drawable is either the actual display or an off-screen pixmap.

static void
SquareDisplay(clientData)
    ClientData clientData;      /* Information about window. */
{
    Square *squarePtr = (Square *) clientData;
    Tk_Window tkwin = squarePtr->tkwin;
    Pixmap pm = None;
    Drawable d;

    squarePtr->updatePending = 0;
    if (!Tk_IsMapped(tkwin)) {
        return;
    }

If required, create the off-screen pixmap for double-buffering:

if (squarePtr->doubleBuffer) {
        pm = Tk_GetPixmap(Tk_Display(tkwin), Tk_WindowId(tkwin),
                Tk_Width(tkwin), Tk_Height(tkwin),
                DefaultDepthOfScreen(Tk_Screen(tkwin)));
        d = pm;
    } else {
        d = Tk_WindowId(tkwin);
    }

Redraw the widget's background and border, and display the square:

    Tk_Fill3DRectangle(tkwin, d, squarePtr->bgBorder, 0, 0, Tk_Width(tkwin),
            Tk_Height(tkwin), squarePtr->borderWidth, squarePtr->relief);

    Tk_Fill3DRectangle(tkwin, d, squarePtr->fgBorder, squarePtr->x,
            squarePtr->y, squarePtr->size, squarePtr->size,
            squarePtr->borderWidth, TK_RELIEF_RAISED);

Copy the pixmap to the display if double buffering:

    if (squarePtr->doubleBuffer) {
        XCopyArea(Tk_Display(tkwin), pm, Tk_WindowId(tkwin), squarePtr->gc,
                0, 0, (unsigned) Tk_Width(tkwin), (unsigned) Tk_Height(tkwin),
                0, 0);
        Tk_FreePixmap(Tk_Display(tkwin), pm);
    }
}

21.1.3.8. Tk::Square destructor

Subroutine SquareCmdDeletedProc is called by core Tk to destroy a Tk::Square widget:

static void
SquareCmdDeletedProc(clientData)
    ClientData clientData;    /* Pointer to widget record for widget. */
{
    Square *squarePtr = (Square *) clientData;
    Tk_Window tkwin = squarePtr->tkwin;

    if (tkwin != NULL) {
        squarePtr->tkwin = NULL;
        Tk_DestroyWindow(tkwin);
    }
}

Subroutine SquareDestroy is called in response to a DestroyNotify event and frees the Square structure and any graphics context.

static void
SquareDestroy(memPtr)
    char *memPtr;        /* Info about square widget. */
{
    Square *squarePtr = (Square *) memPtr;

    Tk_FreeOptions(configSpecs, (char *) squarePtr, squarePtr->display, 0);
    if (squarePtr->gc != None) {
        Tk_FreeGC(squarePtr->display, squarePtr->gc);
    }
    ckfree((char *) squarePtr);
}