sTextIn

This can be any text, even text that is the result of a previous call to the function FormatText (see the section on result, below, for more details). That is to say, formatting can be nested.

Note that if you are supplying a blank value for sTextIn, then the macro interpreter will ignore any formatting included in sFormat and emit message 188270. While this behavior makes sense for text formatting, it can cause paragraph-only or textbox-only formatting to be optimized away.

To avoid this issue, when using the FormatText function, always check if you are supplying a blank sTextIn parameter, and if so, replace it with a nil special character token, as shown in the example below.

if sText == ''
   sText = '&x'
endif
sResult = FormatText(sText, 'STYCELL(Sundays)', -1)

sFormat

Each specifier (see list in table below) is separated from the next by a comma (no space). Any value which can be specified in decimal form must use a period as decimal separator, regardless of the workstation's Windows settings.

A sample sFormat would be:

'B+,I+,f Times New Roman, COLOR(Pantone 231U)'

Note that, despite its name, the parameter sFormat of the function FormatText can contain paragraph attributes and box attributes, as well as text attributes.

Fonts with Font Styles

If you are using QuarkXPress 2018-2025 or InDesign, then, when referring to a font using the FormatText macro function, you should specify the Font Name with the font's Postscript Name, separated by an equal sign, as shown in the sample code below.

sDate = FormatText(sWeekday, 'f Arial Bold=Arial-BoldMT', -1)

The postscript name of the fonts installed on your workstation can be found using the installed fonts tool.

In some cases, the font you are looking for appears not to have a Postscript name, as in the example below, where the font ITC Cheltenham Std Book Cond appears as a screen-only font, without a matching postscript name.

In such cases, as discussed here, the screen version, of the font you are looking for, uses a different internal font name than do QuarkXPress and/or InDesign, and the same font, under a slightly different name, will be available, referring to the exact same font. In the above example, the font ITC Cheltenham Std Book Condensed obviously is the same as the above font ITC Cheltenham Std Book Cond.

Applying Box, Table, or Cell Styles

Additionally, if you are trying to apply a box, table or cell style to a template that is not the main grid of the script (or if your script is not using the use main grid as seed generation option) then you should make sure that that template contains at least one object that uses the style you plan to use (you can then set that object to be automatically deleted by the use of a zap token such as [1Zd>0] for example). Failing to do this will most often cause message 187330 to be generated.

result

The text result of this function will not be formatted text, but rather, plain text with markers that identify it for later processing.

sDate = FormatText('New Year', 'B+,I+,f Times New Roman', -1)

For example, the result of the above call to the function FormatText would be:

'**RICH1**New Year**TEXT1**'

At the same time a command is saved for later processing, to replace the string '**RICH1**New Year**TEXT1**' with 'New Year' in the formatting specified above.

If you need to get the plain text, without the markers, you can use the PeekTokenValue function.

n32bitColor

(deprecated)

Optionally, when using QuarkXPress, you can specify a color to be applied to the text, using the n32bitColor numerical value of a scanned color.

sDate = FormatText('[d]', 'B+, f Arial', 2170914) // black in scan

However, these numerical value are subject to change from one computer to the next, and we recommend that you always refer to the colors by name.

sDate = FormatText('[d]', 'B+, f Arial, COLOR(Pantone 231U)', -1) // -1 means no color

where the value of n32bitColor is set to -1 if we want it to be ignored.Note that this option remains for backwards compatibility, but you should now use COLOR(XXX) in sFormat which refers to a colors by name, as in the example below, instead of its 32-bit representation.

sDate = FormatText('[d]', 'B+, f Arial, COLOR(Pantone 231U)', -1)

If the user interface language of your version of QuarkXPress is not English, then the name of the built-in colors (Black, White, Cyan, Magenta, Yellow, Red, Green, Blue) might be translated internally by QuarkXPress and therefore might not be found under its English name.

sDate = FormatText('[d]', 'B+, f Arial, COLOR(BLACK)', -1)

To get around this issue, you can set the name of any built-in color (Black, White, Cyan, Magenta, Yellow, Red, Green, Blue) in UPPERCASE, as in the example above, and then Q++Studio will know to look for the built-in color, not the exact name.