summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Tk/pTk.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/pTk.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/pTk.pod550
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
-