Tk Source Code

Check-in [1b50dc65]
Login
Bounty program for improvements to Tcl and certain Tcl packages.
Tcl 2019 Conference, Houston/TX, US, Nov 4-8
Send your abstracts to [email protected]
or submit via the online form by Sep 9.

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Man pages changes from René Zaumseil
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | tip-510
Files: files | file ages | folders
SHA3-256: 1b50dc65cd3e95a3427e8785878a22a61038f2a60efd10316e9f3f1829e1005b
User & Date: fvogel 2019-04-11 19:30:17
Context
2019-04-12
20:10
Repair test tk-1.2 check-in: e608f7c6 user: fvogel tags: tip-510
2019-04-11
19:30
Man pages changes from René Zaumseil check-in: 1b50dc65 user: fvogel tags: tip-510
06:03
Further files from René Zaumseil check-in: 88b11f8b user: fvogel tags: tip-510
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to doc/tkoWidget.3.md.

18
19
20
21
22
23
24

25

26

27

28

29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

78
79
80
81
82
83
84
..
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

116
117
118
119
120
121
122
123
124
125







126
127
128
129
130

131
132
133
134
135
136
TkoWidgetWindow -- tko widget class commands

<a name="SYNOPSIS"></a>
## SYNOPSIS

**#include "tkoWidget.h"**


int **TkoWidgetClassDefine**(*interp,clazz,classname,methods,options*)  

Tk\_Window \***TkoWidgetWindow**(*object*)  

Tcl\_Obj \***TkoWidgetOptionVar**(*object*)  

Tcl\_Obj \***TkoWidgetOptionGet**(*interp,object,option*)  

int **TkoWidgetOptionSet**(*interp,context,option,type,meta,offset*)  

<a name="ARGUMENTS"></a>
## ARGUMENTS

Tcl\_Interp **\*interp** Used interpreter.  
Tcl\_Class **clazz** Oo class of widget.  
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 tkoWidgetOptionDefine **\*options** This array contain option definitions.  
Tcl\_Object **object** This is the current object reference.  
Tcl\_Obj **\*option** The name of the used option.  
Tcl\_ObjectContext **context** The context of the current object. Used to get associated object data.  
tkoWidgetOptionType **type** A type used in the common option setting routine.  
Tcl\_ObjectMetadataType **\*meta** The type of metadata attaches to the current object.  
size\_t **offset** Offset of variable to set in the attaches meta data record.  

<a name="DESCRIPTION"></a>
## DESCRIPTION

The **TkoWidgetClassDefine** function can be used to define options and methods of an **tko::widget** subclass.

The **TkoWidgetWindow** function return the address of the internally created Tk\_Window. Subclasses should check the address on NULL after creation. If the Tk\_Window\* at these address is NULL the widget is destroyed and it should not be used.

The **TkoWidgetOptionVar** function return the globally accessible name of the array variable holding the option values. Additionall there is an element "**.**" inside containing the tk widget path name of the widget.

The **TkoWidgetOptionGet** function returns the current value of the given option.

The **TkoWidgetOptionSet** function can be used to check given *option* values and set C record structure fields at the given *offset*. The record will be retrieved using the given *meta* metadata. The *type* must be one of the **tkoWidgetOptionType** described below.

### tkoWidgetOptionDefine

typedef struct tkoWidgetOptionDefine {
    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. */
    const char *proc;      /* If not NULL it is the body of the newly created -option method */
    Tcl_MethodCallProc *method;     /* If not NULL it is the function name of the -option method */
    int flags;             /* if TKO_WIDGETOPTIONREADONLY then option is only setable at creation time */
    tkoWidgetOptionType 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 */
} **tkoWidgetOptionDefine**;

### tkoWidgetOptionType

Suported enum type in the TkowidgetOptinSet() function. In comments is the type of the address pointer.


        TKO_SET_CLASS = 1,     /* (Tcl_Obj **)address */
        TKO_SET_VISUAL, /* (Tcl_Obj **)address */
        TKO_SET_COLORMAP,       /* (Tcl_Obj **)address */
        TKO_SET_USENULL,        /* (Tcl_Obj **)address */
        TKO_SET_CONTAINER,      /* (int *)address */
        TKO_SET_TCLOBJ, /* (Tcl_Obj **)address */
        TKO_SET_XCOLOR, /* (Xcolor **)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_STRINGNULL,     /* (char **)address */
        TKO_SET_SCROLLREGION,   /* (int *[4])address */
        TKO_SET_JUSTIFY /* (Tk_Justify *)address */

<a name="SEE-ALSO"></a>
## SEE ALSO

<a name="KEYWORDS"></a>
## KEYWORDS

canvas, svg, widget

<a name="COPYRIGHT"></a>
## COPYRIGHT

&copy; 2019- René Zaumseil <[email protected]>

BSD style license.


<a name="SEE-ALSO"></a>
## SEE ALSO

[frame][], [labelframe][], [toplevel][], [oo::class][]

<a name="KEYWORDS"></a>
## KEYWORDS

widget, oo








[options]: options.htm
[frame]: frame.htm
[labelframe]: labelframe.htm
[toplevel]: toplevel.htm

[graph]: graph.htm
[path]: path.htm
[Tkpath]: <https://sourceforge.net/projects/tclbitprint/>
[Rbc]: <https://sourceforge.net/projects/rbctoolkit/>








>
|
>
|
>
|
>
|
>
|




|
|
|
|
|
|
|
|
|
|
|




|



|





|

|
|
|
|
|
|
|
|
|
|
|
|

|

|

>







 







<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
>









|
>
>
>
>
>
>
>





>






18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
...
100
101
102
103
104
105
106















107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
TkoWidgetWindow -- tko widget class commands

<a name="SYNOPSIS"></a>
## SYNOPSIS

**#include "tkoWidget.h"**

int  
**TkoWidgetClassDefine**(*interp,clazz,classname,methods,options*)  
Tk\_Window \*  
**TkoWidgetWindow**(*object*)  
Tcl\_Obj \*  
**TkoWidgetOptionVar**(*object*)  
Tcl\_Obj \*  
**TkoWidgetOptionGet**(*interp,object,option*)  
int  
**TkoWidgetOptionSet**(*interp,context,option,type,meta,offset*)  

<a name="ARGUMENTS"></a>
## ARGUMENTS

| Tcl\_Interp **\*interp** | Used interpreter.  
| Tcl\_Class **clazz** | Oo class of widget.  
| 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 tkoWidgetOptionDefine **\*options** | This array contain option definitions.  
| Tcl\_Object **object** | This is the current object reference.  
| Tcl\_Obj **\*option** | The name of the used option.  
| Tcl\_ObjectContext **context** | The context of the current object. Used to get associated object data.  
| tkoWidgetOptionType **type** | A type used in the common option setting routine.  
| Tcl\_ObjectMetadataType **\*meta** | The type of metadata attaches to the current object.  
| size\_t **offset** | Offset of variable to set in the attaches meta data record.  

<a name="DESCRIPTION"></a>
## DESCRIPTION

The **TkoWidgetClassDefine** function can be used to define options and methods of an **tko::widget** subclass. The function is used in the widget class definition of a new tko widget class.

The **TkoWidgetWindow** function return the address of the internally created Tk\_Window. Subclasses should check the address on NULL after creation. If the Tk\_Window\* at these address is NULL the widget is destroyed and it should not be used.

The **TkoWidgetOptionVar** function return the globally accessible name of the array variable holding the option values. Additionall there is an field "**.**" containing the tk widget path name of the widget.

The **TkoWidgetOptionGet** function returns the current value of the given option.

The **TkoWidgetOptionSet** function can be used to check given *option* values and set C record structure fields at the given *offset*. The record will be retrieved using the given *meta* metadata. The *type* must be one of the **tkoWidgetOptionType** described below.

### Struct: `tkoWidgetOptionDefine`

    typedef struct tkoWidgetOptionDefine {
      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. */
      const char *proc;      /* If not NULL it is the body of the newly created -option method */
      Tcl_MethodCallProc *method;     /* If not NULL it is the function name of the -option method */
      int flags;             /* if TKO_WIDGETOPTIONREADONLY then option is only setable at creation time */
      tkoWidgetOptionType 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 */
    } tkoWidgetOptionDefine;

### Enum: `tkoWidgetOptionType`

Suported enum type in the TkowidgetOptinSet() function. In comments is the type of the address provided in the **TkoWidgetOptionSet** funtion.

    typedef enum tkoWidgetOptionType {
        TKO_SET_CLASS = 1,     /* (Tcl_Obj **)address */
        TKO_SET_VISUAL, /* (Tcl_Obj **)address */
        TKO_SET_COLORMAP,       /* (Tcl_Obj **)address */
        TKO_SET_USENULL,        /* (Tcl_Obj **)address */
        TKO_SET_CONTAINER,      /* (int *)address */
        TKO_SET_TCLOBJ, /* (Tcl_Obj **)address */
        TKO_SET_XCOLOR, /* (Xcolor **)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_STRINGNULL,     /* (char **)address */
        TKO_SET_SCROLLREGION,   /* (int *[4])address */
        TKO_SET_JUSTIFY /* (Tk_Justify *)address */















    } tkoWidgetOptionType;

<a name="SEE-ALSO"></a>
## SEE ALSO

[frame][], [labelframe][], [toplevel][], [oo::class][]

<a name="KEYWORDS"></a>
## KEYWORDS

oo widget method option

<a name="COPYRIGHT"></a>
## COPYRIGHT

&copy; 2019- René Zaumseil <[email protected]>

BSD style license.

[options]: options.htm
[frame]: frame.htm
[labelframe]: labelframe.htm
[toplevel]: toplevel.htm
[oo::class]: class.htm
[graph]: graph.htm
[path]: path.htm
[Tkpath]: <https://sourceforge.net/projects/tclbitprint/>
[Rbc]: <https://sourceforge.net/projects/rbctoolkit/>


Changes to doc/tkoWidget.n.md.

1
2
3
4
5
6
7
8
9

10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
..
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
...
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164

165









166
167















168
169
170
171
172
173
174
175
176
177







178
179
180
181
182

183
184
185
186
187
188
# tko::widget(n) -- oo class like widgets

*   [SYNOPSIS](#SYNOPSIS)
*   [TKO STANDARD OPTIONS](#TKO-STANDARD-OPTIONS)  
  [-class, class, Class](#-class)  
  [-screen, screen, Screen](#-screen)  
*   [DESCRIPTION](#DESCRIPTION)  
*   [WIDGET OPTIONS](#WIDGET-OPTIONS)  
*   [WIDGET METHODS](#WIDGET-METHODS)  

*   [TKO WIDGETS](#TKO-WIDGETS)  

*   [KEYWORDS](#KEYWORDS)  
*   [COPYRIGHT](#COPYRIGHT)  

<a name="SYNOPSIS"></a>
## SYNOPSIS

**oo::class create** *widgetClass* {
  {\*}$::tko::unknown ;# define unknown method to support common tk widget style
  superclass *tkoClass* ;# one of the provided tko widget class's
  variable tko ;# array with options *$tko(-option)* and widget path *$tko(.)*
}

The command creates a new Tcl class whose name is *widgetClass*. This command may be used to create new widgets. Each new widget class has as a *tkoClass* as superclass. The common functionality is in the **tko::widget** class. Currently the following *tkoClass* superclasses are provided:

**::tko::toplevel** *pathName ?option value? ..*

**::tko::frame** *pathName ?option value? ..*

................................................................................
These class contain the functionality of the [Rbc][] graph widget command. It is described in detail in the [graph][] manpage.

<a name="tko-path"></a>
## path

These class contain the functionality of the [Tkpath][] widget command. It is described in detail in the [path][] manpage.

<a name="WIDGET-OPTIONS"></a>
### WIDGET OPTIONS

Widget options can be dynamically added and removed at class or object level.

<a name="WIDGET-METHODS"></a>
### WIDGET METHODS

Widget methods can be dynamically added and removed at class or object level.

**NOTE** Do not change *tkoClass*'s behaviour. Instead create your own class and modify it to your need! Or change created widget objects behaviour.

................................................................................
> > Delete the given option and unset the entry in the tko array variable. The created *-option* method's are not deleted. This is the task of the caller.

> **configure optionvar**

> > The method return the global varname of the tko array variable holding all option values.

<a name="method-cget"></a>
**_tko_configure**

> This is an virtuel method of the **tko::widget** class. This method will be called at the end of each **configure** *-option value ..* call. It can be implemented in each class to amke necessary changes. If it is implemented it should also call **next** to notify underlying classes.

<a name="KEYWORDS"></a>
## KEYWORDS

canvas, svg, widget

<a name="COPYRIGHT"></a>
## COPYRIGHT


&copy; 2019- René Zaumseil <[email protected]>










BSD style license.
















<a name="SEE-ALSO"></a>
## SEE ALSO

[frame][], [labelframe][], [toplevel][], [oo::class][]

<a name="KEYWORDS"></a>
## KEYWORDS

widget, oo








[options]: options.htm
[frame]: frame.htm
[labelframe]: labelframe.htm
[toplevel]: toplevel.htm

[graph]: graph.htm
[path]: path.htm
[Tkpath]: <https://sourceforge.net/projects/tclbitprint/>
[Rbc]: <https://sourceforge.net/projects/rbctoolkit/>








<

>
|
<






|
|
|
|
|







 







<
<
<
<
<







 







|



|
|

|

|
<

>
|
>
>
>
>
>
>
>
>
>
|
<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>









|
>
>
>
>
>
>
>





>






1
2
3
4
5
6
7

8
9
10

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
..
75
76
77
78
79
80
81





82
83
84
85
86
87
88
...
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156

157
158
159
160
161
162
163
164
165
166
167
168
169

170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
# tko::widget(n) -- oo class like widgets

*   [SYNOPSIS](#SYNOPSIS)
*   [TKO STANDARD OPTIONS](#TKO-STANDARD-OPTIONS)  
  [-class, class, Class](#-class)  
  [-screen, screen, Screen](#-screen)  
*   [DESCRIPTION](#DESCRIPTION)  

*   [WIDGET METHODS](#WIDGET-METHODS)  
*   [WIDGET OPTIONS](#WIDGET-OPTIONS)  
*   [SEE ALSO](#SEE-ALSO)  

*   [KEYWORDS](#KEYWORDS)  
*   [COPYRIGHT](#COPYRIGHT)  

<a name="SYNOPSIS"></a>
## SYNOPSIS

    oo::class create "widgetClass" {
      {*}$::tko::unknown    ;# define unknown method to support common tk widget style
      superclass "tkoClass" ;# one of the provided tko widget class's
      variable tko          ;# array with options *$tko(-option)* and widget path *$tko(.)*
    }

The command creates a new Tcl class whose name is *widgetClass*. This command may be used to create new widgets. Each new widget class has as a *tkoClass* as superclass. The common functionality is in the **tko::widget** class. Currently the following *tkoClass* superclasses are provided:

**::tko::toplevel** *pathName ?option value? ..*

**::tko::frame** *pathName ?option value? ..*

................................................................................
These class contain the functionality of the [Rbc][] graph widget command. It is described in detail in the [graph][] manpage.

<a name="tko-path"></a>
## path

These class contain the functionality of the [Tkpath][] widget command. It is described in detail in the [path][] manpage.






<a name="WIDGET-METHODS"></a>
### WIDGET METHODS

Widget methods can be dynamically added and removed at class or object level.

**NOTE** Do not change *tkoClass*'s behaviour. Instead create your own class and modify it to your need! Or change created widget objects behaviour.

................................................................................
> > Delete the given option and unset the entry in the tko array variable. The created *-option* method's are not deleted. This is the task of the caller.

> **configure optionvar**

> > The method return the global varname of the tko array variable holding all option values.

<a name="method-cget"></a>
**\_tko\_configure**

> This is an virtuel method of the **tko::widget** class. This method will be called at the end of each **configure** *-option value ..* call. It can be implemented in each class to amke necessary changes. If it is implemented it should also call **next** to notify underlying classes.

<a name="WIDGET-OPTIONS"></a>
### WIDGET OPTIONS

Widget options can be dynamically added and removed at class or object level.

Add options at class level:


    oo::class create myWidget {
      {*}$::tko::unknown
      superclass ::tko::frame
      variable tko
      method -myoption {} {puts $tko(-myoption)}
      method -myreadonly {} {puts $tko(-myreadonly)}
      constructor {optionlist arglist} {
        next [concat $optionlist {
          {-myoption myOption MyOption value}
          {-myreadonly myReadonly MyReadonly value 1}
        }] $arglist
      }

    }

Deal with optons at object level. This is the raw part. May be we should add some sugar to it.

    myWidget .w
    oo::objdefine .w method -o1 {} {puts $tko(-o1)}
    oo::objdefine .w method -o2 {} {puts $tko(-o2)}
    .w configure optionadd -o1 o1 O1 v1 1
    .w configure optionadd -o2 o2 O2 v2
    ...
    .w optiondel -o1

Widget option values are saved in an option array. The option name is the field name in the array. Additionally is an field "**.**" containing the tk widget path name of the widget. The name of the option array variable can be retrieved using the following code:
    set myVar [.w configure optionvar]
    parray $myVar

<a name="SEE-ALSO"></a>
## SEE ALSO

[frame][], [labelframe][], [toplevel][], [oo::class][]

<a name="KEYWORDS"></a>
## KEYWORDS

oo widget method option

<a name="COPYRIGHT"></a>
## COPYRIGHT

&copy; 2019- René Zaumseil <[email protected]>

BSD style license.

[options]: options.htm
[frame]: frame.htm
[labelframe]: labelframe.htm
[toplevel]: toplevel.htm
[oo::class]: class.htm
[graph]: graph.htm
[path]: path.htm
[Tkpath]: <https://sourceforge.net/projects/tclbitprint/>
[Rbc]: <https://sourceforge.net/projects/rbctoolkit/>