[TCLCORE] Re: TIP 5: Make TkClassProcs and TkSetClassProcs public

[Jim I. <ji...@ap...>]

Eric,

How do you intend for this to be used?  Is it for the designer of NEW widgets only, or is it to allow me to get my hands on an extant widget, and modify its response to these "class level" events?  I notice that you allow me to set the callbacks on an arbitrary TkWindow, so the latter is at least possible.  If so, then I might also want not to replace but augment the existing class proc, which means that I need some way to get my hands on the WindowCallback, so I can call it from within my new callback.

Just a thought.  

Other than that, this seems okay.

Jim

On Tuesday, October 10, 2000, at 01:55 PM, Eric Melski wrote:

>  
> The following is a proposal to make the TkClassProcs/TkSetClassProcs 
> system public, to the benefit of extension widget authors.  I have cc'd 
> the tclcore mailing list and  Jeff Hobbs, as acting default maintainer for 
> Tcl, since there is as yet no maintainer that seems more appropriately 
> matched to the area affected by my proposal.  I expect a follow-up message 
> from Jeff acknowledging that he is the TCT member sponsor of the proposal 
> (unless he is not willing to sponsor it), with details about the schedule 
> for the proposal (time period for initial objections, and voting period if 
> necessary).  
>  
> The format of the proposal is as described in TIP #3. 
>  
> Thanks, 
>  
>    Eric Melski                            The Other Tcl Guy 
>    ericm at ajubasolutions.com            Ajuba Solutions 
>  
> -------------------------------------------------------------------------- 
>  
>  
> TIP:		5 
> Title:		Make TkClassProcs and TkSetClassProcs public 
> Version:	$Revision: 1.1$ 
> Author:		Eric Melski <er...@aj...> 
> Status:		Draft 
> Type:		Project 
> Tcl-Version:	8.4 
> Created:	09-Oct-2000 
> 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 
> utilizing this powerful system.  This proposal offers a scalable means 
> for making that API public. 
>  
>  
> ~ Specification 
>  
> The extant private API consists of two pieces:  the TkClassProcs 
> structure, which holds pointers to the callback functions to be used 
> for a given type of window; and the TkSetClassProcs function, which 
> associates a TkClassProcs structure and a piece of ClientData with a 
> particular TkWindow.  Those built-in widgets which take advantage of 
> the system declare a static TkClassProcs structure, which is filled in 
> with appropriate function pointers; and each a new window of that type 
> is created, TkSetClassProcs is called to associate the static 
> structure with the new window. 
>  
> I believe the best way to make the TkSetClassProcs system public is to 
> rename TkClassProcs to TkWindowCallbacks (for clarity), and introduce 
> these new API's: 
>  
>     TkWindowCallbacks *Tk_CreateWindowCallbacks(); 
>     void Tk_SetWindowCallback(TkWindowCallbacks *, proc *, which); 
>     void Tk_SetWindowCallbacks(TkWindow, TkWindowCallbacks *, ClientData); 
>  
> The type parameter for Tk_SetWindowCallback is, at first, one of 
>  
>     enum { 
> 	    TK_WINDOW_CALLBACK_CREATE, 
> 	    TK_WINDOW_CALLBACK_GEOMETRY, 
> 	    TK_WINDOW_CALLBACK_MODAL 
>     }; 
>  
> This enum can be extended in future versions, if necessary, to 
> accomodate additional callbacks.  Note that there is no need for a 
> DestroyWindowCallbacks API, as the structure will be automatically 
> reaped when Tk is destroyed, just as option tables are now. 
>  
> A typical widget (the entry, in this example) uses these functions in 
> the following manner: 
>  
>     static TkWindowCallbacks *entryCallbacks = NULL; 
>  
>     ... 
>  
>     static int Tk_EntryObjCmd(...) { 
> 	    
>     if (entryCallbacks == NULL) { 
>         entryCallbacks = Tk_CreateWindowCallbacks(); 
>         Tk_SetWindowCallback(entryCallbacks, EntryWorldChanged, 
>             TK_WINDOW_CALLBACK_GEOMETRY); 
>     } 
>     ... 
>     Tk_SetWindowCallbacks(entryPtr->tkwin, entryCallbacks, 
>         (ClientData) entryPtr); 
>     ... 
>  
>     TkWindowCallbacks *callbacks; 
>     ClientData instanceData; 
> } 
>  
>  
> ~ Rationale 
>  
> There are other ways to go about making the TkSetClassProcs system 
> public.  However, none of these is both memory efficient and 
> easily extensible. 
>  
> The simplest alternative, in the short term, is to just make the 
> TkClassProcs structure and the TkSetClassProcs function public.  The 
> benefits of this are that it's very easy to do, and it is memory 
> efficient, because there is only one TkClassProcs structure for all 
> windows of a particular type (eg, all Entries, all Labels, etc.).  The 
> main drawbacks are that the function is poorly named and thus 
> misleading in its function (it doesn't really operate on "classes" per 
> se); and that if we ever decide to add another callback to the 
> structure, it will be messy to do so, as programs based off the old 
> library won't necessarily work directly with the new library. 
>  
> A second possibility is to replace the existing API with new ones: 
>  
>     Tk_SetWindowCallback(tkwin, proc, which) 
>     Tk_SetWindowInstanceData(tkwin, clientData) 
>  
> and pull the proc pointers into the TkWindow structure directly.  This 
> is also easy to do, and it has few new API's.  It's easy to extend in 
> the future, we just add another field to TkWindow and another value 
> for the "which" argument of Tk_SetWindowCallback.  The drawbacks here 
> are that extending the callback list means changing the size of 
> TkWindow, which, although allowed because it is a private structure in 
> Tk, is frowned upon, because it is such a critical structure.  Also, 
> putting the function pointers directly in TkWindow means that every 
> TkWindow structure will be bigger by (3 * sizeof(function pointer)). 
> This is probably 12 bytes on most systems today (assuming 32-bit 
> systems), but there is a TkWindow structure for every widget.  I would 
> rather not sacrifice the memory efficiency of the existing setup if 
> possible. 
>  
> I believe that the method outlined above, though somewhat more complex 
> than either of the two described here, is superior, because it offers 
> both easy extensibility and good memory efficiency. 
>  
>  
> ~ Reference Implementation 
>  
> The implementation of this enhancement will not commence until the 
> proposal has been approved. 
>  
> -- 
> The TclCore mailing list is sponsored by Ajuba Solutions 
> To unsubscribe:  email tcl...@aj... with the  
>                  word UNSUBSCRIBE as the subject. 
>  
>  

--
The TclCore mailing list is sponsored by Ajuba Solutions
To unsubscribe:  email tcl...@aj... with the 
                 word UNSUBSCRIBE as the subject.