diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/pTk.pod')
| -rw-r--r-- | Master/tlpkg/tlperl/lib/Tk/pTk.pod | 550 |
1 files changed, 0 insertions, 550 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/pTk.pod b/Master/tlpkg/tlperl/lib/Tk/pTk.pod deleted file mode 100644 index 6e1a2a04022..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/pTk.pod +++ /dev/null @@ -1,550 +0,0 @@ -=head1 NAME - -Tk2portableTk - how to make your B<Tk> source portable to other -interpreted languages. - -=for category C Programming - -=head1 Author - -Ilya Zakharevich <ilya@math.ohio-state.edu> has contributed most of -this document. Many thanks. - -=head1 DESCRIPTION - -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 -possible. - -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 -called C<argv>. - -For details on what C<munge> can do, see -L<Translation of some TCL functions>. - -=head1 B<PortableTk> API - -=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: - - TK_CONFIG_CALLBACK - TK_CONFIG_LANGARG - TK_CONFIG_SCALARVAR - TK_CONFIG_HASHVAR - TK_CONFIG_ARRAYVAR - TK_CONFIG_IMAGE - -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*>. - -=head2 Language data - -The following data types are defined: - -=over 4 - -=item C<Tcl_Obj *> - -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 -C<TK_CONFIG_LANGARG>. - -This is also a type that keeps information about contents of I<Lang> -variable. - -=item C<Var> - -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> -variable. - -=item C<LangResultSave> - -???? - -=item C<LangCallback> - -C<LangCallback*> a substitute for a C<char *> that contains command to -call. The corresponding config type is C<TK_CONFIG_CALLBACK>. - -=item C<LangFreeProc> - -It is the type that the C<Lang_SplitList> sets. Before you call it, -declare - - Args *args; - 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>. - -=back - -=head2 Conversion - -The following macros and functions are used for conversion between -strings and the additional types: - - LangCallback * LangMakeCallback(Tcl_Obj *) - Tcl_Obj * LangCallbackArg(LangCallback *) - char * LangString(Tcl_Obj *) - -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<Tcl_Obj *> 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<Tcl_Obj *>). - -The following function returns the C<Tcl_Obj *> that is a reference to C<Var>: - - Tcl_Obj * LangVarArg(Var) - -???? It is very anti-intuitive, I hope the name is changed. - - int LangCmpCallback(LangCallback *a,Tcl_Obj * b) - -(currently only a stub), and, at last, - - LangCallback * LangCopyCallback(LangCallback *) - -=head2 Callbacks - -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 *,Tcl_Obj *,char *method, - int result,int argc,...) - -???? - -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. - -=head2 Setting variables - - void LangFreeArg (Tcl_Obj *, Tcl_FreeProc *freeProc) - Tcl_Obj * LangCopyArg (Tcl_Obj *); - void Tcl_AppendArg (Tcl_Interp *interp, Tcl_Obj *) - void LangSetString(Tcl_Obj * *, char *s) - void LangSetDefault(Tcl_Obj * *, 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(Tcl_Obj * *,int) - void LangSetDouble(Tcl_Obj * *,double) - -The I<Lang> functions separate uninitialized and initialized data -comparing data with C<NULL>. So the declaration for an C<Tcl_Obj *> should -look like - - Tcl_Obj * arg = NULL; - -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 - -Use - -=over 4 - -=item C<int LangNull(Tcl_Obj *)> - -to check that an object is false; - -=item C<int LangStringMatch(char *string, Tcl_Obj * match)> - -???? - -=item C<void LangExit(int)> - -to make a proper shutdown; - -=item C<int LangEval(Tcl_Interp *interp, char *cmd, int global)> - -to call I<Lang> C<eval>; - -=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,Tcl_Obj * arg,FILE *f,Lang_FileCloseProc *proc)> - -currently stubs only; - -=item C<int LangSaveVar(Tcl_Interp *,Tcl_Obj * arg,Var *varPtr,int type)> - -to save the structure C<arg> into I<Lang> variable C<*varPtr>; - -=item C<void LangFreeVar(Var var)> - -to free the result; - -=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)> - -unsupported????; - -=item C<void Tcl_AppendArg (Tcl_Interp *interp, Tcl_Obj *)> - -=back - -Another useful construction is - - Tcl_Obj * 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<Tcl_Obj *>) 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<Tcl_Obj *> of length C<n>, use - - Tcl_Obj * *args = LangAllocVec(n); - ... - LangFreeVec(n,args); - -You can set the values of the C<Tcl_Obj *>s using C<LangSet...> functions, -and get string value using C<LangString>. - -If you want to merge an array of C<Tcl_Obj *>s into one C<Tcl_Obj *> (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>. - -=over 4 - -=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> - -Use a single command - - void Tcl_DoubleResults(Tcl_Interp *interp, int append, - int argc,...); - -C<append> governs whether it is required to clear the result first. - -A similar command for C<int> arguments is C<Tcl_IntResults>. - -=item C<Tcl_SplitList> - -Use C<Lang_SplitList> (see the description above). - -=back - -=head1 Translation back to TCL - -To use your B<portableTk> program with B<TCL>, put - - #include "ptcl.h" - -I<before> inclusion of C<tk.h>, and link the resulting code with -C<ptclGlue.c>. - -These files currently implement the following: - -=over 4 - -=item Additional config types: - - TK_CONFIG_CALLBACK - TK_CONFIG_LANGARG - TK_CONFIG_SCALARVAR - TK_CONFIG_HASHVAR - TK_CONFIG_ARRAYVAR - TK_CONFIG_IMAGE - -=item Types: - - Var, Tcl_Obj *, 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. - -=back - -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: - - TK_EVENTTYPE_NONE - TK_EVENTTYPE_STRING - TK_EVENTTYPE_NUMBER - TK_EVENTTYPE_WINDOW - TK_EVENTTYPE_ATOM - TK_EVENTTYPE_DISPLAY - TK_EVENTTYPE_DATA - -and a function - - 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). - -=head1 Additional API - -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). - -=head2 C<ListFactory> - -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 -in B<TCL>: - - void ListFactoryInit(ListFactory *) - void ListFactoryFinish(ListFactory *) - void ListFactoryFree(ListFactory *) - Tcl_Obj * * ListFactoryArg(ListFactory *) - void ListFactoryAppend(ListFactory *, Tcl_Obj * *arg) - void ListFactoryAppendCopy(ListFactory *, Tcl_Obj * *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<Tcl_Obj *> 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 -be quicker. - -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. - -=head2 DStrings - -Production of strings are still supported in B<portableTk>. - -=head2 Accessing C<Tcl_Obj *>s - -The following functions for getting a value of an C<Tcl_Obj *> I<may> be -provided: - - double LangDouble(Tcl_Obj *) - int LangInt(Tcl_Obj *) - long LangLong(Tcl_Obj *) - int LangIsList(Tcl_Obj * arg) - -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<Tcl_Obj *>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<Tcl_Obj *>, the best way to do this is to -declare a buffer in the beginning of a block by - - dArgBuffer; - -and assign this buffer to the C<Tcl_Obj *> by - - void LangSetDefaultBuffer(Tcl_Obj * *) - -You can also create the buffer(s) manually and assign them using - - void LangSetBuffer(Tcl_Obj * *, char *) - -This is the only choice if you need to assign numeric values to -several C<Tcl_Obj *>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<Tcl_Obj *> that -contains some value, you can create a leak if you do not free that -C<Tcl_Obj *> 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<Tcl_Obj *>s - -The API for creating a new C<Tcl_Obj *> is - - void LangNewArg(Tcl_Obj * *, LangFreeProc *) - -The API for creating a new C<Tcl_Obj *> is absent. Just initialize C<Tcl_Obj *> to -be C<NULL>, and apply one of C<LangSet...> methods. - -After you use this C<Tcl_Obj *>, it should be freed thusly: - -C<LangFreeArg(arg, freeProc)>. - -=head2 Evaluating a list - -Use - - int LangArgEval(Tcl_Interp *, Tcl_Obj * 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<Tcl_Obj *>. The -arguments can be send to the subroutine by reference or by value in -different languages. - -=head2 Getting result as C<Tcl_Obj *> - -Use C<Tcl_ArgResult>. It is not guaranteed that result survives this -operation, so the C<Tcl_Obj *> you get should be the only mean to access the -data from this moment on. After you use this C<Tcl_Obj *>, you should free -it with C<freeProc> C<LANG_DYNAMIC> (you can do LangSet...() in between). - -=cut - |