Menu
▾
▴
[TCLCORE] TIP 6
|
From: Jeffrey H. <jef...@aj...> - 2000-10-18 02:05:40
|
Enclosed is revision 1 of TIP 6, which obsoletes TIP 5.
This incorporates ideas from Scott Stanton and George Howlett,
and I believe it addresses all concerns that have been raised
thus far. JohnO and I have reviewed the proposal and support it.
I am acting sponsor on this proposal.
Since this is a follow-on TIP that has already had siginificant
discussion, I'd like to invoke the TYANNOT process, with a
deadline of this Friday, October 20th for any new objections.
Thanks,
Jeffrey Hobbs Tcl Ambassador
hobbs@AjubaSolutions.com Ajuba Solutions (née Scriptics)
-----------------------------------------------
TIP: 6
Title: Make TkClassProcs/TkSetClassProcs public and extensible
Version: $Revision: 1.1$
Author: Eric Melski <er...@aj...>
Status: Draft
Type: Project
Tcl-Version: 8.4
Created: 17-Oct-2000
Obsoletes: 5
Post-History:
~ Abstract
At certain critical moments in the lifetime of a Tk widget, Tk will
invoke various callbacks on that widget. These callbacks enable the
widget to do lots of interesting things, such as react to
configuration changes for named fonts, or create and manage truly
native widgets (such as the scrollbar widget on Windows platforms).
The API for setting up these callbacks for a particular window are, as
of Tk 8.3.2, private. This prohibits extension widget authors from fully
utilizing this powerful system; those developers can either copy the
private declarations into their own source code (leading to future
maintainance hassles), or forego the system entirely, hampering their
ability to make truly native and well-integrated widgets. This
proposal offers an extensible means for making that API public.
~ Rationale: Why make TkClassProcs/TkSetClassProcs public?
(The following text is adapted from George Howlett [1])
The Tk toolkit was originally written strictly for Xlib. It created
wrappers for many of the Xlib calls. A good example is creating a
window. Tk's Tk_CreateWindow call in turn calls Xlib's XCreateWindow.
This is so that the toolkit can perform bookkeeping on the window and
manage it in various ways. The down side was that if you needed to
pass specific information/flags to the XCreateWindow call you
couldn't. But this only affected extensions.
Now when Tk 8.0 added native widgets, Tk also had the same problem.
For example to create a Win32 button control, you have to pass
information through the X emulation layer to the eventual Win32
CreateWindow or CreateWindowEx call.
So the Sun Tk developers created this notion of class procedures. A
widget of particular type may need to make different calls at the time
the window is created. They added to the TkWindow structure pointers
to both the widget instance (i.e. the data the represents the specific
widget) and a structure of function pointers (such as one to call when
the window is to be created).
TkClassProcs tkpButtonProcs =
CreateProc, /* createProc. */
TkButtonWorldChanged, /* geometryProc. */
NULL /* modalProc. */
};
Inside of Tk, such as in Tk_MakeWindowExist, code was added to check
if the "createProc" of the structure isn't NULL and call that routine
to create the native window.
This mechanism was also used to handle font aliasing. I can create a
font "fred" that is really a { courier bold } font and use it with any
Tk widget.
font create fred -family courier -weight bold
button .b -font fred
The widget will get the real font and use it in its graphics context.
Think of GCs like a pen drawing a particular color. A GC draws with a
particular font.
Now if I change the font, the widget's GC must be updated too.
font create fred -family helvetica -weight medium
You can see where a "geometryProc" is needed to indicate when font
aliases change. It gets called for all the widgets using the font.
Another callback is used to handle modal events. This is currently
needed only for the Win32 native scrollbar.
So here's the private structure and TkSetClassProcs call.
typedef Window (TkClassCreateProc) _ANSI_ARGS_((Tk_Window tkwin,
Window parent, ClientData instanceData));
typedef void (TkClassGeometryProc) _ANSI_ARGS_((ClientData instanceData));
typedef void (TkClassModalProc) _ANSI_ARGS_((Tk_Window tkwin,
XEvent *eventPtr));
/*
* Widget class procedures used to implement platform specific widget
* behavior.
*/
typedef struct TkClassProcs {
TkClassCreateProc *createProc;
/* Procedure to invoke when the
platform-dependent window needs to be
created. */
TkClassGeometryProc *geometryProc;
/* Procedure to invoke when the geometry of a
window needs to be recalculated as a result
of some change in the system. */
TkClassModalProc *modalProc;
/* Procedure to invoke after all bindings on a
widget have been triggered in order to
handle a modal loop. */
} TkClassProcs;
void
TkSetClassProcs(tkwin, procs, instanceData)
Tk_Window tkwin; /* Token for window to modify. */
TkClassProcs *procs; /* Class procs structure. */
ClientData instanceData;/* Data to be passed to class procedures. */
{
register TkWindow *winPtr = (TkWindow *) tkwin;
winPtr->classProcsPtr = procs;
winPtr->instanceData = instanceData;
}
Extension developers could not use this interface, however, because it
was private to Tk. The original authors of the interface didn't think
that anything outside of the Tk widgets would need it. Of course,
hindsight is 20-20, and we have since found that this is not true.
Extension developers do need to use this system: widget writers that
use fonts obviously need to know when a font alias changes, and new
Win32 native widgets also need access to this mechanism.
Most extensions authors had/have already found a workaround: copy in
the TkClassProcs structure and TkSetClassProcs routine into your code.
However, this workaround leads to future code maintainence problems.
Because the structure is private, its members and usage are not
guaranteed to remain constant between versions of Tk. If the
structure changes, the extension authors have to update all of their
code accordingly.
Making the system public locks in the format and usage of the system,
so that extension authors can rely on it existing from one version to
the next, and they will no longer have to maintain parallel redundant
copies of the structure and function definition.
~ Rationale: Why make TkClassProcs/TkSetClassProcs extensible?
Every time we've made a public structure, we've regretted it later
when we needed to extend it to handle some new feature that we didn't
originally anticipate. In general we should avoid designing new API's
that preclude making future changes without introducing
incompatibilities. [2]
This system is one that seems likely to require extension in the
future. There are currently three callbacks: create window, geometry
change, and modal event. Already one request to extend the mechanism
has been made, to support the notion of a "client area" related to
geometry management and labeled frame widgets [3, 4]. Another possible
extension is a focus management callback, to allow for smoother focus
transitions between native widgets and Tk widgets; note that this
focus management callback is a purely hypothetical extension at this
time.
If the system is one that we are likely to want to extend with
additional callbacks in the future, it behooves us to make it public
in a manner that allows us to extend it while causing the minimum
amount of disruption for extension authors. There are two concerns
here. First is binary compatibility: will an extension compiled
against a version of Tk which features the base (three callback)
TkClassProcs system work with a version of Tk that features an
extended TkClassProcs system? Second is source compatibility: will
an extension author have to update their sources when they want to
recompile their extension against a version of Tk that features an
extended TkClassProcs system? Ideally, the system that we make public
will allow extension while retaining binary and source compatibility
between versions of Tk.
~ Specification
I propose that the following steps be taken to make
TkClassProcs/TkSetClassProcs public:
1. Rename TkClassProcs to Tk_ClassProcs; rename TkSetClassProcs to
Tk_SetClassProcs; rename TkClassCreateProc, etc., to
Tk_ClassCreateProc, etc. Move the structure definition,
function prototype, and callback typedefs from tkInt.h to tk.h.
This is in keeping with Tk public interface naming conventions.
2. Add a single size field to the Tk_ClassProcs structure. This
field is initialized at the time that the structure is
allocated, and always contains the size of the structure. This
field will be used to provide a simple versioning scheme for
the structure. Portions of Tk that use the class proc
callbacks will inspect this size field to ascertain whether or
not a particular instance of the Tk_ClassProcs structure is of
a version that contains a given callback. See the example below.
3. Rename the "geometryProc" callback to "worldChangedProc". The
name "geometryProc" is somewhat misleading. Currently, the
callback is used only to support font aliasing, as described
above. This is sort of geometry related, but it doesn't
necessarily mean that geometry of the widget must change, it
just means that the widget will have to update its world view
to reflect the current state of the world. In addition, the
callback will likely be used to support color aliasing when
that is added to Tk (imagine defining a color "myColor" to mean
"#c4d3a2" and then configuring widgets to use "myColor" instead
of the literal value; this provides all the benefits for colors
that font aliasing does for fonts). When that is done,
"geometryProc" will be truly misleading, since a color change
probably does not mean a geometry change for the widget.
4. Change the order of the callback fields in the Tk_ClassProcs
structure, making "worldChangedProc" the first of the callbacks
listed in the structure. In the existing private TkClassProcs
structure, the first callback is the "createProc". It is not
strictly necessary to make "worldChangeProc" the first callback.
However, most widgets in Tk (canvas, entry, scale, text,
message, listbox, menu, menubuttons, scrollbars on Unix and
Mac, and buttons on Unix and Mac) use only this callback.
Making it first in the structure (after the size field, which
must be the very first entry) means a little bit less work for
widget authors in the common case, because they need not
include the NULL declaration for the "createProc" slot in the
structure. Compare:
static Tk_ClassProcs myClassProcs = {
sizeof(Tk_ClassProcs), NULL, myWorldChangedProc
};
with:
static Tk_ClassProcs myClassProcs = {
sizeof(Tk_ClassProcs), myWorldChangedProc
};
Since the "createProc" is used so infrequently, why require
that all widget authors explicitly declare it to be NULL? This
change just simplifies everybody's life that much more.
Usage of the public API will be very similar to usage of the existing
private API:
static Tk_ClassProcs myClassProcs = {
sizeof(Tk_ClassProcs),
myWorldChangedProc
};
static int Tk_MyWidgetObjCmd(...) {
...
Tk_SetClassProcs(widgetPtr->tkwin,myClassProcs,(ClientData)widgetPtr);
...
return TCL_OK;
}
Portions of Tk that need to use a particular callback, such as
Tk_MakeWindowExist, use code like the following:
Tk_ClassProcs *thisClassProcs = tkwin->classProcs;
createProc *procPtr;
/* Make sure the structure we were given has the createProc field
* in it by checking that the size of the structure is at least
* big enough to have that slot.
*/
if (thisClassProcs->size <= Tk_Offset(Tk_ClassProcs, createProc)) {
procPtr = NULL;
} else {
procPtr = thisClassProcs->createProc;
}
if (procPtr != NULL) {
/* Invoke the createProc for this window. */
...
} else {
/* Use the default Tk window creation mechanism. */
...
}
~ Benefits of this implementation
Benefits of this implementation are as follows:
1. Usage of Tk_ClassProcs/Tk_SetClassProcs very, very closely
parallels the usage of the existing private API. In fact, the
only difference is a small change in the particular fields of
the Tk_ClassProcs structure (especially, the new size field,
for version information, and the reordering of the callback
fields).
2. All instances of "mywidget" reference the same Tk_ClassProcs
structure. This is memory efficient.
3. We do not need to explicitly initialize to NULL those fields of
myClassProcs that we don't use. The ANSI C specification
states that static variables (and members of statically
declared structures) that are not explicitly initialized are
initialized to zero.
4. This retains binary compatibility. The size field of the
Tk_ClassProcs structure is set at compile time, so when a later
version of Tk checks the size field to see if a new callback
can be used, it will fail. That is, if extension author
A compiles the extension against version X of Tk, which has
three fields in Tk_ClassProcs, the size field of myClassProcs
will be set to 12 (assuming 4-byte pointers). When using that
extension with Tk version Y, which may have four fields in
Tk_ClassProcs, the size check for that fourth field will fail,
since the size field, set to 12, will be less than or equal to
the offset of the fourth field in the structure.
5. This retains source compatibility. Because of #3 above, unless
the extension author wants to use the new callbacks, they need
not worry about their addition, because the new fields will be
automatically set to zero.
6. There is minimal API bloat. Only one public API is added,
Tk_SetClassProcs.
7. The system is "type safe" with respect to the function signatures
of the callback functions. Any type mismatches will be caught
at compile time.
8. If desired, widget authors can directly reference elements of
the Tk_ClassProcs structure:
myClassProcs.createProc = myCreateProc;
~ Drawbacks of this implementation
The drawbacks of this implementation are as follows:
1. The required value of the size field will seem like a bit of
black magic to developers new to the system. The question "Why
does this field have to be set to this value? If it's always
the same thing, why is it stored at all?" Of course,
experienced programmers will recognize why it has to be set,
and that in fact, it is not always the same value. This issue
can best be addressed by appropriate documentation.
2. Extensions that use the existing private
TkClassProcs/TkSetClassProcs mechanism and which were compiled
against versions of Tk <= 8.3 will not work with new versions
of Tk, since the format of the Tk_ClassProcs structure will
change. However, this is the consequence of using private
structures and API's in your extensions: when those private
structures and API's change, you have to update your extension
accordingly. We cannot allow ourselves to be overly
constrained by this issue. The existing mechanism is private,
period. Authors that use it do so knowingly and willfully.
~ Reference Implementation
The implementation of this enhancement will not commence until the
proposal has been approved.
~ References
1. http://dev.scriptics.com/lists/tclcore/2000/10/msg00143.html
2. http://dev.scriptics.com/lists/tclcore/2000/10/msg00083.html
3. http://dev.scriptics.com/lists/tclcore/2000/10/msg00121.html
4. http://dev.scriptics.com/lists/tclcore/2000/10/msg00170.html
--
The TclCore mailing list is sponsored by Ajuba Solutions
To unsubscribe: email tcl...@aj... with the
word UNSUBSCRIBE as the subject.
|