Tk2portableTk - how to make your B<Tk> source portable to other
=for category C Programming
Ilya Zakharevich <ilya@math.ohio-state.edu> has contributed most of
this document. Many thanks.
B<PortableTk> is an attempt to make B<Tk> useful from other
languages. Currently tk4.0 runs under Perl using this
approach. Below, I<Lang> is the notation for an external language to
which B<PortableTk> glues B<Tk> code.
The main problem with using the code developed for B<TCL> with
different languages is the absence of data types: almost anything is
C<char*>. It makes automatic translation hopeless. However, if you
C<typedef> several new symbols to be C<char*>, you can still use your
code in B<TCL>, I<and> it will make the automatic translation
Another problem with the approach that "everything is a string" is
impossibility to have a result that says "NotApplicable" without
setting an error. Thus different B<Tk> command return different string
values that mean "error happened", like C<"">, C<" "> or
C<"??">. Other languages can be more flexible, so in B<portableTk> you
should inform the compiler that what you want to return means "error"
(see L<Setting variables>).
Currently B<PortableTk> uses several different approachs
to simplify translation: several B<TCL> functions that are especially
dangerous to use are undefined, so you can easily find places that
need to be updated to use Language-independent functions based on
compiler warnings. Eventually a way to use these Language-independent
functions under proper B<TCL> will be also provided. The end of this
document provides a starting point for such a project.
=head1 Structure of B<pTk>, porting your code
B<pTk>, that is a port of B<Tk>, is very special with respect to porting
of other code to B<portableTk>. The problem is that currently there is
very little hope to merge the modifications back into B<Tk>, so a
special strategy is needed to maintain this port. Do not use this
strategy to port your own code.
B<pTk> is produced from B<Tk> via a two-step process: first, some
manual editing (the result is in the subdirectory C<mTk>), and second,
automatic conversion by the C<munge> script (written in Perl). Thus the
subdirectory C<pTk/mTk> contains code with minimal possible difference
from the virgin B<Tk> code, so it is easier to merge(1) the
differences between B<Tk> versions into modified code.
It looks like the strategy for a portable code should be exactly
opposite: starting from B<TCL>-based code, apply C<munge>, and then
hand-edit the resulting code. Probably it is also possible to target
your code to B<portableTk> from scratch, since this will make it
possible to run it under a lot of I<Lang>uages.
The only reason anyone would like to look into contents of C<pTk/mTk>
directory is to find out which constructs are not supported by
C<munge>. On the other hand, C<pTk> directory contains code that is
conformant to B<portableTk>, so you can look there to find example code.
C<munge> is the script that converts most common B<Tk> constructs to
their C<portableTk> equivalent. For your code to qualify, you should
follow B<Tk> conventions on indentation and names of variables, in
particular, the array of arguments for the C<...CmdProc> should be
For details on what C<munge> can do, see
L<Translation of some TCL functions>.
=head2 Checking what you are running under
B<PortableTk> provides a symbol C<????>. If this symbol is defined,
your source is compiled with it.
=head2 New types of configuration options
B<PortableTk> defines several new types of configuration options:
You should use them instead of TK_CONFIG_STRING whenever
appropriate. This allows your application to receive a direct
representation of the corresponding resource instead of the string
representation, if this is possible under given language.
???? It looks like C<TK_CONFIG_IMAGE> and C<TK_CONFIG_SCALARVAR> set
variables of type C<char*>.
The following data types are defined:
is the main datatype of the language. This is a type that your C
function gets pointers to for arguments when the corresponding I<Lang>
function is called. The corresponding config type is
This is also a type that keeps information about contents of I<Lang>
Is a substitute for a C<char *> that contains name of variable. In
I<Lang> it is an object that contains reference to another I<Lang>
C<LangCallback*> a substitute for a C<char *> that contains command to
call. The corresponding config type is C<TK_CONFIG_CALLBACK>.
It is the type that the C<Lang_SplitList> sets. Before you call it,
LangFreeProc *freeProc = NULL;
code = Lang_SplitList(interp, value,
&argc, &args, &freeProc);
After you use the split values, call
if (args != NULL && freeProc) (*freeProc)(argc,args);
It is not guaranteed that the C<args> can survive deletion of C<value>.
The following macros and functions are used for conversion between
strings and the additional types:
LangCallback * LangMakeCallback(Arg)
Arg LangCallbackArg(LangCallback *)
After you use the result of LangCallbackArg(), you should free it with
C<freeProc> C<LANG_DYNAMIC> (it is not guaranteed that any change of
C<Arg> will not be reflected in <LangCallback>, so you cannot do
LangSet...() in between, and you should reset it to C<NULL> if you
want to do any further assignments to this C<Arg>).
The following function returns the C<Arg> that is a reference to C<Var>:
???? It is very anti-intuitive, I hope the name is changed.
int LangCmpCallback(LangCallback *a,Arg b)
(currently only a stub), and, at last,
LangCallback * LangCopyCallback(LangCallback *)
Above we have seen the new datatype C<LangCallback> and the
corresponding I<Config option> C<TK_CONFIG_CALLBACK>. The following
functions are provided for manipulation of C<LangCallback>s:
void LangFreeCallback(LangCallback *)
int LangDoCallback(Tcl_Interp *,LangCallback *,
int result,int argc, char *format,...)
The argument C<format> of C<LangDoCallback> should contain a string that is
suitable for C<sprintf> with optional arguments of C<LangDoCallback>.
C<result> should be false if result of callback is not needed.
int LangMethodCall(Tcl_Interp *,Arg,char *method,
Conceptually, C<LangCallback*> is a substitute for ubiquitous C<char *>
in B<TCL>. So you should use C<LangFreeCallback> instead of C<ckfree>
or C<free> if appropriate.
void LangFreeArg (Arg, Tcl_FreeProc *freeProc)
void Tcl_AppendArg (Tcl_Interp *interp, Arg)
void LangSetString(Arg *, char *s)
void LangSetDefault(Arg *, char *s)
These two are equivalent unless s is an empty string. In this case
C<LangSetDefault> behaves like C<LangSetString> with C<s==NULL>, i.e.,
it sets the current value of the I<Lang> variable to be false.
void LangSetInt(Arg *,int)
void LangSetDouble(Arg *,double)
The I<Lang> functions separate uninitialized and initialized data
comparing data with C<NULL>. So the declaration for an C<Arg> should
if you want to use this C<arg> with the above functions. After you are
done, you should use C<LangFreeArg> with C<TCL_DYNAMIC> as C<freeProc>.
=head2 Language functions
=item C<int LangNull(Arg)>
to check that an object is false;
=item C<int LangStringMatch(char *string, Arg match)>
=item C<void LangExit(int)>
to make a proper shutdown;
=item C<int LangEval(Tcl_Interp *interp, char *cmd, int global)>
=item C<void Lang_SetErrorCode(Tcl_Interp *interp,char *code)>
=item C<char *Lang_GetErrorCode(Tcl_Interp *interp)>
=item C<char *Lang_GetErrorInfo(Tcl_Interp *interp)>
=item C<void LangCloseHandler(Tcl_Interp *interp,Arg arg,FILE *f,Lang_FileCloseProc *proc)>
=item C<int LangSaveVar(Tcl_Interp *,Arg arg,Var *varPtr,int type)>
to save the structure C<arg> into I<Lang> variable C<*varPtr>;
=item C<void LangFreeVar(Var var)>
=item C<int LangEventCallback(Tcl_Interp *,LangCallback *,XEvent *,KeySym)>
=item C<int LangEventHook(int flags)>
=item C<void LangBadFile(int fd)>
=item C<int LangCmpConfig(char *spec, char *arg, size_t length)>
=item C<void Tcl_AppendArg (Tcl_Interp *interp, Arg)>
Another useful construction is
Arg variable = LangFindVar(interp, Tk_Window tkwin, char *name);
After using the above function, you should call
LangFreeVar(Var variable);
???? Note discrepancy in types!
If you want to find the value of a variable (of type C<Arg>) given the
variable name, use C<Tcl_GetVar(interp, varName, flags)>. If you are
interested in the string value of this variable, use
C<LangString(Tcl_GetVar(...))>.
To get a B<C> array of C<Arg> of length C<n>, use
Arg *args = LangAllocVec(n);
You can set the values of the C<Arg>s using C<LangSet...> functions,
and get string value using C<LangString>.
If you want to merge an array of C<Arg>s into one C<Arg> (that will
be an array variable), use
result = Tcl_Merge(listLength, list);
=head2 Translation of some TCL functions
We mark items that can be dealt with by C<munge> by I<Autoconverted>.
=item C<Tcl_AppendResult>
does not take C<(char*)NULL>, but C<NULL> as delimiter. I<Autoconverted>.
=item C<Tcl_CreateCommand>, C<Tcl_DeleteCommand>
C<Tk_CreateWidget>, C<Tk_DeleteWidget>, the second argument is the
window itself, not the pathname. I<Autoconverted>.
=item C<sprintf(interp-E<gt>result, "%d %d %d %d",...)>
C<Tcl_IntResults(interp,4,0,...)>. I<Autoconverted>.
=item C<interp-E<gt>result = "1";>
C<Tcl_SetResult(interp,"1", TCL_STATIC)>. I<Autoconverted>.
=item Reading C<interp-E<gt>result>
C<Tcl_GetResult(interp)>. I<Autoconverted>.
=item C<interp-E<gt>result = Tk_PathName(textPtr-E<gt>tkwin);>
C<Tk_WidgetResult(interp,textPtr-E<gt>tkwin)>. I<Autoconverted>.
=item Sequence C<Tcl_PrintDouble, Tcl_PrintDouble, ..., Tcl_AppendResult>
void Tcl_DoubleResults(Tcl_Interp *interp, int append,
C<append> governs whether it is required to clear the result first.
A similar command for C<int> arguments is C<Tcl_IntResults>.
Use C<Lang_SplitList> (see the description above).
=head1 Translation back to TCL
To use your B<portableTk> program with B<TCL>, put
I<before> inclusion of C<tk.h>, and link the resulting code with
These files currently implement the following:
=item Additional config types:
Var, Arg, LangCallback, LangFreeProc.
=item Functions and macros:
Lang_SplitList, LangString, LangSetString, LangSetDefault,
LangSetInt, LangSetDouble Tcl_ArgResult, LangCallbackArg,
LangSaveVar, LangFreeVar,
LangFreeSplitProc, LangFreeArg, Tcl_DoubleResults, Tcl_IntResults,
LangDoCallback, Tk_WidgetResult, Tcl_CreateCommand,
Tcl_DeleteCommand, Tcl_GetResult.
Current implementation contains enough to make it possible to compile
C<mTk/tkText*.[ch]> with the virgin B<Tk>.
=head2 New types of events ????
PortableTk defines following new types of events:
char * Tk_EventInfo(int letter,
Tk_Window tkwin, XEvent *eventPtr,
KeySym keySym, int *numPtr, int *isNum, int *type,
int num_size, char *numStorage)
=head1 Checking for trouble
If you start with working TCL code, you can start convertion using
the above hints. Good indication that you are doing is OK is absence
of C<sprintf> and C<sscanf> in your code (at least in the part that is
working with interpreter).
What is described here is not included into base B<portableTk>
distribution. Currently it is coded in B<TCL> and as Perl macros (core
is coded as functions, so theoretically you can use the same object
files with different interpreted languages).
Dynamic arrays in B<TCL> are used for two different purposes: to
construct strings, and to construct lists. These two usages will have
separate interfaces in other languages (since list is a different type
from a string), so you should use a different interface in your code.
The type for construction of dynamic lists is C<ListFactory>. The API
below is a counterpart of the API for construction of dynamic lists
void ListFactoryInit(ListFactory *)
void ListFactoryFinish(ListFactory *)
void ListFactoryFree(ListFactory *)
Arg * ListFactoryArg(ListFactory *)
void ListFactoryAppend(ListFactory *, Arg *arg)
void ListFactoryAppendCopy(ListFactory *, Arg *arg)
ListFactory * ListFactoryNewLevel(ListFactory *)
ListFactory * ListFactoryEndLevel(ListFactory *)
void ListFactoryResult(Tcl_Interp *, ListFactory *)
The difference is that a call to C<ListFactoryFinish> should precede the
actual usage of the value of C<ListFactory>, and there are two
different ways to append an C<Arg> to a C<ListFactory>:
ListFactoryAppendCopy() guarantees that the value of C<arg> is copied
to the list, but ListFactoryAppend() may append to the list a
reference to the current value of C<arg>. If you are not going to change
the value of C<arg> after appending, the call to ListFactoryAppend may
As in B<TCL>, the call to ListFactoryFree() does not free the
C<ListFactory>, only the objects it references.
The functions ListFactoryNewLevel() and ListFactoryEndLevel() return a
pointer to a C<ListFactory> to fill. The argument of
ListFactoryEndLevel() cannot be used after a call to this function.
Production of strings are still supported in B<portableTk>.
The following functions for getting a value of an C<Arg> I<may> be
The function LangIsList() is supported only partially under B<TCL>,
since there is no data types. It checks whether there is a space
inside the string C<arg>.
=head2 Assigning numbers to C<Arg>s
While LangSetDouble() and LangSetInt() are supported ways to assign
numbers to assign an integer value to a variable, for the sake of
efficiency under B<TCL> it is supposed that the destination of these
commands was massaged before the call so it contains a long enough
string to sprintf() the numbers inside it. If you are going to
immediately use the resulting C<Arg>, the best way to do this is to
declare a buffer in the beginning of a block by
and assign this buffer to the C<Arg> by
void LangSetDefaultBuffer(Arg *)
You can also create the buffer(s) manually and assign them using
void LangSetBuffer(Arg *, char *)
This is the only choice if you need to assign numeric values to
several C<Arg>s simultaneously. The advantage of the first approach is
that the above declarations can be made C<nop>s in different languages.
Note that if you apply C<LangSetDefaultBuffer> to an C<Arg> that
contains some value, you can create a leak if you do not free that
C<Arg> first. This is a non-problem in real languages, but can be a
trouble in C<TCL>, unless you use only the above API.
=head2 Creating new C<Arg>s
The API for creating a new C<Arg> is
void LangNewArg(Arg *, LangFreeProc *)
The API for creating a new C<Arg> is absent. Just initialize C<Arg> to
be C<NULL>, and apply one of C<LangSet...> methods.
After you use this C<Arg>, it should be freed thusly:
C<LangFreeArg(arg, freeProc)>.
int LangArgEval(Tcl_Interp *, Arg arg)
Here C<arg> should be a list to evaluate, in particular, the first
element should be a C<LangCallback> massaged to be an C<Arg>. The
arguments can be send to the subroutine by reference or by value in
=head2 Getting result as C<Arg>
Use C<Tcl_ArgResult>. It is not guaranteed that result survives this
operation, so the C<Arg> you get should be the only mean to access the
data from this moment on. After you use this C<Arg>, you should free
it with C<freeProc> C<LANG_DYNAMIC> (you can do LangSet...() in between).
projects / OpenSPARC-T2-DV / blob