PA_DetokenizeInTEHandle

version 2003

PA_DetokenizeInTEHandle (tokens; len) → PA_Handle

The routine PA_DetokenizeInTEHandle allows the 4D plug-in to retrieve the text of the 4D statement or expression corresponding to the tokenized 4D formula that has been passed.

Before the call, pass the tokenized 4D statement or expression in Tokens (which the 4D plug-in obtains using the PA_Tokenize ) and its length in len . After the call, the 4D plug-in receives a TEHandle (a handle to a Text Edit record and not a CharsHandle). The hText field of the Text Edit record points to the detokenized text.

As the TEHandle structure is specific to MacOS calls, this routine is useful only when compiling for MacOS or Windows using Mac2Win. If the plug-in is compiled for Windows without Mac2Win, the handle is still a "valid" Mac2Win Handle, but it should not be used in this case.

To detokenize in a "regular" text, use PA_Detokenize .

It is the plug in's responsibility to dispose of the TEHandle when it is no longer needed.

Suppose a developer writes a plug-in that implements callbacks of 4D formulas, for example, 4D formulas inserted in 4D plug-in areas. Because these formulas may need to be evaluated several times, the developer uses the pre-tokenization scheme provided by PA_Tokenize in order to optimize the execution time. Therefore, the developer will probably implement a dialog box where the user can enter the formula to be inserted. If the developer wants to allow the user to later modify an already inserted formula, he needs to keep the text of the formula in memory (and on disk if the 4D plug-in areas generate data or documents) or be able to retrieve it from its tokenized form. The entry point PA_DetokenizeInTEHandle allows the developer to do this. The developer does not need to maintain both the text and the tokens of the formula, only to keep the tokenized form of the formula in memory and on disk. In doing so, both memory and disk space are saved.

In addition, localization is much easier. For example, an English-speaking 4th Dimension user inserts the formula String (Year of (Current date )) in a 4D plug-in area. Then the area contents are saved into a record or a document on disk . If this record or document is reused by a French-speaking user (using a French version of 4th Dimension) and if the formula was saved as text, the user would be presented a syntax error from 4th Dimension as soon as the formula is evaluated for the first time. In addition, the French user would be a little bit puzzled by the English formulas displayed on the screen. If the formulas are saved as tokens, whatever the country version is, 4th Dimension will have no problem in executing them. In addition, a French user will see Chaine (Annee de (Date du jour )) on the screen as would be expected.

Using the tokenized form of 4D formulas not only optimizes execution time and saves space but also makes the 4D plug-in international.

Detokenize and use the TEHandle

   void UseDetokenizedText (char *tokens, long len)
   {
      TEHandle   teh = 0L;
 
      teh = PA_DetokenizeInTEHandle(tokens, len);
      if(teh && (PA_GetLastError() == eER_NoErr))
      {
         /* . . . use the text in (*teh)->hText . . .*/
 
      // Cleanup
         TEDispose(teh);
      }
   }

PA_Detokenize , PA_ExecuteTokens , PA_ExecuteTokensAsFunction , PA_Tokenize .

Use PA_GetLastError to see if an error occurred