# E.S.O. - VLT project 
#
# "@(#) $Id: TkWidget.man3,v 1.1.1.1 2009/03/31 14:11:52 cguirao Exp $" 
#
# This file is processed by the ESO/VLT docDoManPages command to
# produce a man page in nroff, TeX and MIF formats. 
# See docDoManPages(1) for a description of the input format.
# 
# who             when       what
# --------------  ---------  ----------------------------------------
# Allan Brighton  20 Jul 95  Created

NAME
TkWidget - C++ base class for implementing new Tk Widgets

PARENT CLASS
TclCommand

DERIVED CLASSES
TkTree

SYNOPSIS
#include "TkWidget.h"


/* 
 * This is the base class for classes defining tk widgets from
 * C++ classes
 */
class TkWidget : public TclCommand {
protected:
    Tk_Window tkwin_;	// widget's Tk window
    Display *display_;	// X token for the window's display

    char* pname_;	// name of parent window
    char* wclass_;      // this widget's class

    Tk_ConfigSpec* configSpecsPtr_; // ptr to widget's config struct
    TkWidgetOptions* optionsPtr_;   // ptr to struct holding option values

    int redraw_pending_;   // flag: true if widget needs to be redrawn


    // do first time widget configuration 
    virtual int initWidget(int argc, char* argv[]);

    // configure the widget with cmd line options.
    virtual int configureWidget(int argc, char* argv[], int flags = 0);
    
    // If not already scheduled, schedule the widget to be redrawn
    virtual int eventually_redraw();

    // this method may be redefined in a derived class to redraw
    // the widget.
    virtual void redraw();

    // called for DestroyNotify events in the widget 
    virtual void destroyNotify(XEvent *eventPtr);

    // called for ConfigureNotify events (resize)
    virtual void configureNotify(XEvent *eventPtr);

public:

    // constructor: pclass is the expected parent window class type,
    // the specs and options args are used to process the command line
    // args and for the configure widget command.
    TkWidget(Tcl_Interp*, const char* pclass, 
	     Tk_ConfigSpec* specs, TkWidgetOptions& options,
	     int argc, char* argv[]);

    // destructor
    virtual ~TkWidget();

    // call a member function by name
    virtual int call(const char* name, int len, int argc, char* argv[]);

    virtual int configureCmd(int argc, char* argv[]);

    // called for the cget widget command
    virtual int cgetCmd(int argc, char* argv[]);

    // Redraw the widget by calling the virtual redraw_ method
    // which may be defined in a derived class.
    static void redrawWidget(ClientData);

    // called for StructureNotify events in the widget
    static void structureNotify(ClientData clientData, XEvent *eventPtr);
 
    // invoked by Tk_EventuallyFree to clean up widget 
    static void destroyProc(ClientData clientData);
};

DESCRIPTION
TkWidget is a base class for C++ classes defining Tk widgets.  In
addition to the features inherited from its base class TclCommand,
TkWidget adds support for creating and configuring Tk widgets.

The configure (or config) and cget subcommands are implemented here
automatically, so that derived classes don't have to handle this.  The
derived classes only need to define two structures required by Tk for
widgets:

One is the Tk_ConfigSpec structure, a static struct describing the
widget options.

The other is a non-static member struct for holding the values for
widget configuration options.  This struct must be derived from
TkWidgetOptions, which is just a dummy struct used for passing the
actual struct as a parameter.

SEE ALSO
TclCommand, TkTree(3C++)
---------------------------------------------------------------------------
