Tk Source Code

tkoWidget(3) -- oo class like widgets
Login
Bounty program for improvements to Tcl and certain Tcl packages.

NAME

Tko_WidgetClassDefine, Tko_WidgetCreate, Tko_WidgetDestroy, Tko_WidgetClientData, Tko_WidgetOptionGet, Tko_WidgetOptionSet,

SYNOPSIS

#include "tkoWidget.h"

int
Tko_WidgetClassDefine(interp,classname,methods,options)
int
Tko_WidgetCreate(clientdata,interp,object,isToplevel,arglist)
void Tko_WidgetDestroy(context)
ClientData Tko_WidgetClientData(context)
Tcl_Obj *
Tko_WidgetOptionGet(widget,option)
int
Tko_WidgetOptionSet(widget,option,value)

ARGUMENTS

Tcl_Interp *interp Used interpreter.
Tcl_Obj *classname Oo class name of widget.
const Tcl_MethodType *methods This array defines class methods to create. For creation methods see [Tcl_NewMethod] manpage. If the method name of the first array entry is not NULL it will be used as constructor, if the second method name is not NULL it used as destructor. Then follow public methods until an entry with an method name equal NULL comes. Then follow private methods until an entry with an method name equal NULL comes.
const Tko_WidgetOptionDefine *options This array contain option definitions.
Tcl_Object object This is the current object reference.
int isToplevel When =1 then create a toplevel otherwise a frame window.
Tcl_Obj arglist Argument list of constructor call.
ClientData cientdata Pointer to widget structure. First part in this struct is Tko_Widget. It
Tcl_ObjectContext context Context of method calls.
Tcl_Obj *option The name of the used option.
Tcl_Obj *value New value of the given option.

DESCRIPTION

The Tko_WidgetClassDefine function create a new tko widget class of classname. The function create the class add common methods (cget, configure, _tko_configure) and then add given methods and options.

The Tko_WidgetCreate function create a new window. The clientdata should be ckalloced in the widget constructor. The function add the given clientdata to the object metadata. The function should be called in a C widget constructor.

The Tko_WidgetDestroy function clears all internal widget data. The function also arrange the ckfree of the clientdata.

The Tko_WidgetClientData should be used from inside widget methods to get the widget structure data given in the Tko_WidgetCreate function.

The Tko_WidgetOptionGet function returns the current value of the given option.

The Tko_WidgetOptionSet function set the given option to the new given value.

Struct: Tko_Widget

typedef struct Tko_Widget {
  Tcl_Interp *interp;       /* Interpreter associated with widget. */
  Tcl_Object object;        /* our own object */
  Tk_Window tkWin;          /* Window that embodies the canvas. NULL means
                             * that the window has been destroyed but the 
                             * data structures haven't yet been cleaned
                             * up.*/
  Display *display;		/* Display containing widget. Used, among
                             * other things, so that resources can be
                             * freed even after tkwin has gone away. */
  Tcl_Obj *myCmd;            /* Objects "my" command. Needed to call internal methods. */
  Tcl_Command widgetCmd;     /* Token for widget command. */
  Tcl_Obj *optionsArray;     /* Name of option array variable */
  Tcl_HashTable optionsTable;/* Hash table containing all used options */
} Tko_Widget;

These structure will be filled in the Tko_WidgetCreate call and cleared in the Tko_WidgetDestroy call. Widget methods should check the value of tkWin on NULL before using it.

Struct: Tko_WidgetOptionDefine

typedef struct Tko\_WidgetOptionDefine {
  const char *option;           /* Name of option. Starts with "-" minus sign */
  const char *dbname;           /* Option DB name or synonym option if dbclass is NULL */
  const char *dbclass;          /* Option DB class name or NULL for synonym options. */
  const char *defvalue;         /* Default value. */
  int flags;                    /* bit array of TKO_OPTION_* values to configure option behaviour */
  Tcl_MethodCallProc *method;   /* If not NULL it is the function name of the -option method */
  Tko\_WidgetOptionType type;   /* if greater 0 then option type used in common option set method */
  Tcl_ObjectMetadataType *meta; /* meta data address used in common option set method */
  int offset;                   /* offset in meta data struct */
} Tko\_WidgetOptionDefine;
#define TKO_OPTION_READONLY 0x1 /* option is only setable at creation time */
#define TKO_OPTION_HIDE     0x2 /* option is hidden in configure method */ 
#define TKO_OPTION_NULL     0x4 /* empty values are saved as NULL */

Enum: Tko_WidgetOptionType

Suported enum type in the Tko_WidgetOptionDefine definition. As comment is the type of the address provided in the Tko_WidgetOptionDefine definition.

typedef enum Tko\_WidgetOptionType {
    TKO_SET_CLASS = 1,     /* (Tcl_Obj **)address */
    TKO_SET_VISUAL, /* (Tcl_Obj **)address */
    TKO_SET_COLORMAP,       /* (Tcl_Obj **)address */
    TKO_SET_USE,        /* (Tcl_Obj **)address */
    TKO_SET_CONTAINER,      /* (int *)address */
    TKO_SET_TCLOBJ, /* (Tcl_Obj **)address */
    TKO_SET_XCOLOR, /* (Xcolor **)address */
    TKO_SET_3DBORDER,       /* (Tk_3DBorder *)address */
    TKO_SET_PIXEL,  /* (int *)address */
    TKO_SET_PIXELNONEGATIV, /* (int *)address */
    TKO_SET_PIXELPOSITIV,   /* (int *)address */
    TKO_SET_DOUBLE, /* (double *)address */
    TKO_SET_BOOLEAN,        /* (int *)address */
    TKO_SET_CURSOR, /* (Tk_Cursor *)address */
    TKO_SET_INT,    /* (int *)address */
    TKO_SET_RELIEF, /* (int *)address */
    TKO_SET_ANCHOR, /* (int *)address */
    TKO_SET_WINDOW, /* (Tk_Window *)address */
    TKO_SET_FONT,   /* (Tk_Font *)address */
    TKO_SET_STRING, /* (char **)address */
    TKO_SET_SCROLLREGION,   /* (int *[4])address */
    TKO_SET_JUSTIFY /* (Tk_Justify *)address */
} Tko\_WidgetOptionType;

EXAMPLES

static Tko_WidgetOptionDefine myOptions[] = {
    /*
     * Readonly option, only setable on creation time.
     * Use of internal standard option setting function.
     */
    {"-class","class","Class","TkoFrame",TKO_OPTION_READONLY,
        NULL,NULL,TKO_SET_CLASS,NULL,0},
    /*
     * Option value in structure have NULL value when option is empty.
     * Use of internal standard option setting function.
     */
    {"-background","background","Background",DEF_FRAME_BG_COLOR,TKO_OPTION_NULL,
        NULL,NULL,TKO_SET_3DBORDER,&frameMeta,offsetof(tkoFrame, border)},
    /*
     * Use own provided oo method to set option value.
     */
    {"-backgroundimage","backgroundImage","BackgroundImage",DEF_FRAME_BG_IMAGE,0,
        NULL,FrameMethod_backgroundimage,0,NULL,0},
    /*
     * Synonym option definition.
     */
    {"-bg","-background",NULL,NULL,0,NULL,NULL,0,NULL,0},
    /*
     * Indicate end of options in array.
     */
    {NULL,NULL,NULL,NULL,0,NULL,NULL,0,NULL,0}
};

For detailed examples see also the implementation of tko::toplevel, tko::frame and tko::labelframe widgets in file generic/tko/tkoFrame.c.

SEE ALSO

frame, labelframe, toplevel, oo::class

KEYWORDS

oo widget method option

COPYRIGHT

© 2019- RenĂ© Zaumseil [email protected]

BSD style license.