TextArea 1.23 (23-Sep-03)

Name:     ArtWorks TextArea module
Purpose:  ArtWorks module providing rotatable, multi-column text areas
Author:   Martin Wrthner
Requires: RISC OS 3.5 or higher, ArtWorks 2
Status:    2003 Martin Wrthner; all rights reserved; see [6] below
WWW:      http://www.mw-software.com/

Welcome to the TextArea module!

1) The TextArea module
----------------------
The TextArea module adds a new object type to ArtWorks: rotatable, multi-column
text areas. Although this module provides many options and key short-cuts, it
is simple to use because it is designed to be very similar to the way the most
popular document processors work: Most of its features are based on those of
the Impression family (by Computer Concepts Ltd.) or Ovation Pro (by David
Pilling).

The TextArea module offers two tools in the ArtWorks Tool Box: The Text area
tool and the Text edit tool. The Text area tool is used to initially create
text area objects and to change the properties of a text area as a whole. The
Text edit tool is used to edit the text inside a text area and to change the
properties of the text.

The Text area tool is represented by an icon showing the letter A in a white
rectangle while the Text edit tool is represented by an icon showing the letter
E and a red caret in a white rectangle.

The presence of two tools may seem confusing at first, but you will find that
ArtWorks switches between them automatically depending on what you do, so most
of the time it does not matter that much which one you choose. The main
difference between them is that they display different info bars: The ones
displayed by the Text area tool allow you to change text area properties, while
the ones displayed by the Text edit tool display text properties.

1.1) Creating a text area
-------------------------
Creating a text area is as simple as creating a rectangle: Select the Text area
tool in the Tool Box (the one showing the letter A in a white rectangle),
position the pointer to where you want one corner of the text area to be, then
click Select and drag the pointer diagonally to where you want the other corner
to be.

The created text area is represented by a grey rectangle with four selection
handles. It displays a caret in its top left corner, ready for you to start
typing. The Text edit tool has been selected for your convenience, so the Info
Bar shows the current text properties: e.g., the font and the font size.

If you want to change the properties of the complete text area, such as its
position or its size you can do this by switching back to the Text area tool.
Simply click on its icon in the Tool Box (the one showing the letter A in a
white rectangle). This changes the Info Bar to display the properties of the
text area object. See 1.5 for further information.

1.2) Entering text
------------------
Whenever there is a caret in a text area, you can enter text by typing it on
your keyboard. You can enter special characters that are not on your keyboard
using utilities such as the !Chars utility supplied with RISC OS or more
sophisticated utilities such as !XChars (available free from MW Software at
http://www.mw-software.com/).

You can start a new paragraph by typing Return. Typing Ctrl-G instead of Return
also starts a new paragraph, but forces it to start at the top of the next
column. This feature is called "Force to next" (see Tutorial page 2).

There are keyboard short-cuts for two special characters: Ctrl-Shift-H inserts
a bullet point () (see 2.2 for bulletized lists) and Ctrl-Shift-_ inserts an
N-dash (see 1.17 for details about line breaks and hyphens).

You can move the caret using the arrow keys on your keyboard. The Left, Right,
Up and Down arrow keys move the caret in the corresponding direction. Holding
down the Ctrl key at the same time moves the caret as far as possible in the
given direction: Ctrl-Left to the beginning of the current line, Ctrl-Right to
the end of the current line, Ctrl-Up to the beginning of the text area and
Ctrl-Down to the end of the text area. Shift-left and Shift-right move the
caret backward and forward to the preceding or next word respectively.

You can change the appearance of the text you enter by changing any of the
values in the Info Bar. For example, if you choose a new font from the font
menu, then any text entered subsequently will use this font. Please note that
this only works if you start typing right after choosing the font without
positioning the caret somewhere else inbetween. If you click in the text area
to reposition the caret, the style at the caret position is picked up and
displayed in the Info Bar.

Some values in the Info Bar can only be changed after positioning the caret in
an input field (e.g., the "Font aspect" input field). After changing such a
value, press Return to make TextArea accept the new value. Then, in order to
continue typing into the selected text area, click somewhere over the document
window to give the caret back to the document (it does not matter where you
click, the caret will always reappear in its previous position).

1.3) Selecting text
-------------------
If you want to change the properties of existing text rather than those of text
you are going to type, you have to select the text in question. You can select
text by dragging with the Select mouse button. You can extend or reduce the
selection by clicking with the Adjust mouse button or by dragging using Adjust.

Double-clicking on a word selects it. Triple-clicking selects an entire
paragraph. This is very useful when applying paragraph properties (see 1.7.2).
The keyboard short-cut Ctrl-A selects the whole text in the text area and
Ctrl-Z clears the current selection.

Any changes you make in the Info Bar while there is a text selection are
applied to the whole selection.

If you start typing while there is a selection, then the selection is deleted
and replaced by the text you type. The same applies if you paste text from the
text clipboard (see 1.10) while there is a selection.

If you ever accidentally type text while there is a selection and thereby
delete some text you wanted to keep, do not worry: First of all, the deleted
text has been placed on the text clipboard, so you can recover it by pasting it
back from the clipboard (by pressing Ctrl-V, see 1.10), and secondly, do not
forget that whichever mistake you make, there is always the Undo facility of
ArtWorks.

There is an exception to the first point mentioned above: If you paste text
from the clipboard while there is a text selection, then the deleted text is
not placed on the clipboard (because there is only one clipboard, and it
contains the text that you want to paste, so it cannot be replaced). In this
situation, only Undo can be used to recover the deleted text.

1.4) The Info Bar
-----------------
The TextArea module displays six different kinds of Info Bars. Two of them are
used to change the properties of text area objects and they are displayed while
the Text area tool is selected. The other four of them are used to change the
properties of text and are displayed while the Text edit tool is selected. They
resemble the usual button bars in word processor applications.

The Info Bar of the Text area tool contains two Info Bar switch buttons in its
bottom left corner. They can be used to switch between the Area setup (change
the position, width and height of the text area) and Column setup (change the
number of columns, the gap between columns and the text insets) Info Bar modes.
The button corresponding to the current Info Bar mode is always highlighted.

The Info Bar of the Text edit tool contains a row of four Info Bar switch
buttons in its bottom left corner. They can be used to switch between the four
Text edit Info Bar modes. From left to right, these are: Font mode, Paragraph
mode, Colour mode and Ruler mode. The button corresponding to the current Info
Bar mode is always highlighted.

Each Info Bar has a little help button that, when clicked, displays this file.

1.5) Text area properties
-------------------------
A text area behaves very similar to a rectangle object. You can change its
position, width and height from the Info Bar. To change any text area
properties, select the text area object using the Selector, then select the
Text area tool (showing the letter A in a white rectangle). This switches the
Info Bar to Area setup mode (or to Column setup mode if that was the last mode
you had used). You can only change the properties of a single text area at a
time, so if there are multiple text areas selected, the Info Bar just shows "-"
in each input field and ignores any attempts to enter new values.

1.6.1) Area setup mode

Area setup mode allows you to change the X and Y positions, the width and the
height of a text area numerically. Of course, you can also change the position
of a text area interactively using the Selector tool (by dragging the text area
to the desired position) or you can change its size by dragging one of its
selection handles (either using the Selector tool, the Text area or the Text
edit tool).

1.6.2) Column setup mode

Column setup mode allows you to change the number of columns (either by
entering a new value in the input field and pressing Return or by clicking on
the up/down arrows next to the input field), the gap between the columns and
the horizontal and vertical text insets. The latter values determine the
distance of the columns from the text area border.

Normally, the column borders are shown as green outlines while a text area is
selected. This can be switched on and off with the "Show" radio button.

1.6.3) Text area fill and line colours

When you first create a text area, its background is transparent and it does
not have an outline. Similar to a rectangle, you can apply various style
attributes to a text area. Simply select the text area, then use any of the
standard fill tools (e.g., the Flat fill tool) to change the style of the text
area in the usual way. You can even apply complex fills, such as graduated or
radial fills or pattern fills (using the Hatch or HatchPro tools available from
MW Software). You can also use the main menu to apply properties like Line
width, Dash pattern, etc. As text areas are always closed shapes, you cannot
apply Start and End arrows, nor can you apply a winding rule because text areas
never self-intersect, so there is no difference between winding rules.

Please note that setting the fill colour of a text area does not automatically
change the background colour used for anti-aliasing the text in the area. To
do this, place the caret in the text area, press Ctrl-A (Select all) and then
choose the appropriate background colour in the Colour setup Info Bar.

1.7) Text properties
--------------------
There are two ways to use the Text edit Info Bars: You can either select a
section of text and change its properties by changing any of the values in the
Info Bar, or you can place the caret somewhere in the text, change any of the
values in the Info Bar, and these values are then applied to any text you type
directly afterwards.

1.7.1) Font properties

The Font info bar is quite straightforward: It allows you to change the font,
the font size, the font aspect ("X:Y") and to create subscript and superscript
text.

- Font -

Clicking menu over the font display field or over the pop-up menu icon
displays the standard ArtWorks font menu from which you can choose a font.

- Font size -

You can change the font size by entering a new value into the input field and
pressing Return or by clicking on the up/down arrow icons. The default unit of
measurement for values you enter is whatever you configured to be the "Font
units" in the ArtWorks global choices.

- Font aspect -

By changing the font aspect you can stretch or squash a font horizontally. A
value of 100% displays the font normally with its normal proportions. Values
smaller than 100% make the font more condensed, values larger than 100% stretch
the font.

Condensing a font can sometimes be useful to squeeze more text in a column.
However, it is often better to use specific "condensed" fonts (e.g., the
popular condensed variants of Homerton/Helvetica/Swiss) in preference to
condensing a font using the "Font aspect" value because changing the font
aspect usually compromises the aesthetic harmony of a font, in particular the
relationship between horizontal and vertical stroke widths.

- Subscript and superscript -

The two icons at the top left corner of the Info Bar can be used to create
subscript and superscript text.

1.7.2) Paragraph properties

The Paragraph info bar contains options that are normally applied to complete
paragraphs ("Line spacing" is an exception as it also makes sense to apply it
to smaller sections of text).

It is straightforward to select an entire paragraph by simply triple-clicking
into it. This avoids some surprises that can happen when paragraphs have mixed
properties. Currently, TextArea always applies paragraph properties from the
start of the selection to the end of the paragraph, so you can, for instance,
have a different alignment starting in the middle of a paragraph. This is
rarely useful so it is usually better to select the entire paragraph first by
triple-clicking on it.

- Paragraph alignment -

The four buttons in the top left corner of the info bar are used to specify the
paragraph alignment. From left to right they are: Left aligned, right aligned,
centred and fully justified. The paragraph alignment is automatically applied
up to the end of the paragraph even if there is only part of the paragraph
selected (nevertheless, it is only applied starting from the beginning of the
selection, so you should normally start the selection at the beginning of the
paragraph).

- Leading/Line spacing -

Leading (also called line spacing) controls the distance between a text base
line and the next base line expressed as a percentage of the maximal font size
used in the line. The usual value to use is 120% (please note that the leading
can only be entered as a percentage and not as an absolute value).

In contrast to typical paragraph properties, such as paragraph alignment, which
have to be consistent over a paragraph, line spacing can be applied to
individual words or characters. The idea is that it controls the contribution
of each piece of text towards the overall leading. The overall leading is the
maximum of the results you get when you multiply the font size of each piece of
text multiplied with its individual leading percentage.

The advantage of this approach is that you can prevent specific pieces of text
from having an influence over line spacing by simply setting their leading
value to 0%. For example, supposed you have a single letter at 18pt in a
paragraph that is otherwise typeset at 12pt. Then, you may not want the line
containing this character to have a larger line spacing because this disrupts
the equal spacing of lines. See also 2.3.

Please note that if all the text in a line has a leading of 0% applied, then
there is no line spacing at all, i.e. the following line will be printed right
over it! If you see such a situation, simply select the section and apply a
line spacing of 120%. Selecting two lines on top of each other may be a bit
tricky, but remember that you can always use Ctrl-Left to go to the beginning
of the current line, then press Left to go the end of the preceding line, then
Ctrl-Left again to go to the beginning of that line, etc.

- Space before/after paragraph -

The "Space before" and "Space after" fields control automatic paragraph
spacing. The "Space before" value of a paragraph determines the extra space
that is added before the paragraph (this does not happen if the paragraph is at
the top of a column). The "Space after" values determines the extra space added
after the paragraph end.

- Keep -

The "Keep" feature is normally used for single heading lines: A paragraph is
only considered to fit in a column if there is at least as much space below the
paragraph as given by the "Keep" value. So, if you want to make sure that a
heading cannot be at the bottom of a column without there being space for at
least the first line of the following column, you should specify a "Keep" value
that is bigger than the current "Space after" value plus the height of the
following line ("Font size" * "Leading"). For example, if your current
"Space after" value is 4pt and the following line uses 12pt at a Leading of
120%, then specifying a "Keep" value of at least 4 pt + 120% * 12pt = 18.4pt
will make sure that the first line of the paragraph is in the same column as
the heading.

Page 2 of the Tutorial shows an example of using the "Keep" feature.

1.7.3) Text colours

The Colour info bar allows you to specify the text colour and the background
colour used for anti-aliasing. Please note that the background colour is not
displayed as such behind the text. Its only use is to give the Font Manager a
hint to allow it to apply anti-aliasing (by fading the colour of the characters
into the background colour).

If you apply a flat fill colour to the text area (see 1.6.3), then you should
normally apply the same colour as the font background colour of the complete
text in the area.

1.7.4) Text indents

The Indent info bar offers basic ruler facilities: The "First indent" value is
applied to the first line of every paragraph. The "Indent" value is applied to
all other lines.

- Tab stops -

In contrast to most word processors, there is no ruler bar where you can create
tab stops. Instead, you can enter a single value into the "Tab stops every"
field. This creates tab stops at every multiple of the value. So, if you enter
5mm, then this means that there are tab stops at 5mm, 10mm, 15mm, etc.

Whenever you enter a Tab character, the next character is moved to the right to
the next tab stop position.

You can use these three options to create bulletized text, to indent whole
sections of text or to mark paragraph starts by an indent automatically. See
page 1 of the Tutorial for examples.

1.8) Selecting text areas
-------------------------
Text area objects can be selected using the Selector tool by clicking on one of
the characters it contains. As with the standard ArtWorks Text line tool, it is
not enough to click in the space between characters (this feature allows you to
select other objects that are underneath text area objects and can be seen
through the gaps between the characters).

Alternatively, you can select a text area by clicking into an unselected text
area while the Text edit tool is selected. This immediately positions the caret
at the position you clicked.

Text areas without any text are slightly problematic because they are invisible
and therefore cannot be selected using the Selector. However, there is a trick
for doing this: Simply turn the WYSIWYG button to 0 (lowest quality display).
At this level, text area objects display as wire-frame rectangles. You can then
select the text area using the Selector by clicking on the wire-frame or using
the Text edit tool by clicking anywhere inside the text area.

1.9) Transforming text areas
----------------------------
Text areas can be rotated and scaled just like any other ArtWorks objects.

Even after being rotated, the text area remains fully editable. Due to the way
the Wimp works, however, editing a rotated text area will be less responsive
and will cause more flickering than editing an upright text area. If you find
this irritation, simply rotate the area back to its initial orientation before
doing major editing work. You can rotate any ArtWorks object to its initial
orientation by selecting the Rotate tool and entering 0 in the "Rotate to"
field.

When a text area object is scaled using the ArtWorks scaling tool (or the
MScale plug-in tool), then all font sizes and paragraph offsets in the text
area are scaled, too, if the "Lines" option of the scaling tool is selected.
This means that with "Lines" selected, the scaled text area looks exactly
like it did before scaling because all the line breaks remain the same.

If a text area is scaled while "Lines" is not selected, then all sizes and
offsets remain the same. This means that line breaks are likely to change
because the text remains the same size while the text area's size changes,
so the text is reformatted.

Please note that the TextArea module currently does not support non-uniform
transformations on text areas, i.e. you cannot sheer them. If you try and
scale a text area non-uniformly, then the non-uniform part of the scaling is
ignored (i.e., the value in the X:Y field of the scaling tool has no effect).

Text areas cannot be perspectivized or enveloped. Unfortunately, there is no
way for the TextArea module to tell the Perspective and Envelope tools. All
TextArea can do is display an error message when you select either tool while
a text area is selected.  You should then simply select some other tool without
moving any of the control points (you will just get another error if you
nevertheless try this). Please note that if you have several text areas
selected while selecting the Perspective and Envelope tool, then you will get
one error message for each object.

1.10) Cut, Copy and Paste and the text clipboard
------------------------------------------------
While the caret is in a text area, the key short-cuts Ctrl-X, Ctrl-C and Ctrl-V
perform the cut, copy and paste functions for text instead of performing the
corresponding functions for the currently selected objects.

Ctrl-X ("cut") deletes the selected text and places it on the text clipboard.
Ctrl-C ("copy") places the selected text on the text clipboard without deleting
it. Ctrl-V ("paste") pastes the text clipboard contents at the caret position
(if there is no selection) or replaces the selected text with the clipboard
contents (if there is a selection). Please note that if you replace some
selected text by pasting the clipboard contents, then the replaced text is not
placed on the text clipboard. You can recover the text by undoing the paste
operation.

If you use the text clipboard to copy and paste text, then the complete text
formatting is copied and pasted.

Please note that you cannot use the text clipboard to copy text between
documents (if you change documents, then the text clipboard is cleared). In
order to copy text between documents, you have to copy the complete text area
to the destination document first, then copy from there.

1.11) Font substitution
-----------------------
If you load a document containing text areas with fonts that are not installed
on your machine, then you will see the familiar ArtWorks warning message. As
with the warning messages for unknown fonts in text lines, there is a Quiet
option to save you from looking at each message in turn. If there are unknown
fonts in text lines and you click on Quiet, you will nevertheless see the error
messages for unknown fonts in text areas (at least the first of them, you can
then click on Quiet again to prevent further messages from being displayed).

In contrast to earlier versions of the TextArea module, versions 1.23 and
higher automatically reformat all text areas in a document when either a font
that is used in a text area is not available (and hence has to be substituted)
or when a font is now available that was substituted at the time when the
document was saved.

If a font that was substituted because it was not known when the document was
loaded becomes available later (e.g., if you make it available from a font
management utility), then the font remains substituted in this document until
the document is closed and reloaded. If a font that was known when the document
was loaded stops being available, then it is silently substituted and the
affected text areas are not reformatted automatically. The next editing
operation in an affected line will correct the formatting. Alternatively, you
can force a reformatting of a whole text area by placing the caret in the
"Width" field of the Text Area tool and pressing Return (or by resizing the
area with the mouse and then undoing the change).

1.12) Importing text
--------------------
You can import plain text files by dragging them onto the ArtWorks icon on the
icon bar or on an ArtWorks document window. The TextArea module then asks you
whether you want the text to be placed on the text area clipboard or whether
you want it to be imported using the standard ArtWorks text loader. If you want
to use the text in a text area, you should click on the "Clipboard" button or
press Return. This causes the text to be copied to the clipboard. You can then
position the caret in a text area and paste the text by pressing Ctrl-V.

TextArea converts imported text using the following rules: Single line feeds
are replaced by spaces whereas double line feeds are replaced by paragraph
breaks. This is most convenient for importing files such as this !Help file
that was designed to be read in a text editor (but do not try to import a piece
of text as massive as this file, because it is bigger than what TextArea was
designed to hold in a single text area object - TextArea will do it but it is
likely to be too slow to be usable).

1.13) Exporting as Draw or EPS
------------------------------
When you export a document containing a text area to Draw or to EPS, then the
text is exported as many individual text lines. Lines without any style changes
are exported as complete text lines. If there are any style changes on the line
(or if the line is fully justified), then shorter sections of text are exported
as individual text line objects.

Since version 1.08 of TextArea, text areas can be exported both as text lines
and as shapes. If you export as Corel Draw or Illustrator EPS, text is
exported as shapes automatically. Otherwise, i.e. if you export in Draw or
ArtWorks EPS format, text areas appear as collections of text lines, if the
option "Convert text to shapes" in the EPS or Draw export choices is not set.
If this option is set, they appear as shapes.

1.14) The text area info box and text export
--------------------------------------------
Pressing Shift-F1 while a text area is selected displays the text area info
box. The info box displays the size of the text story (including internal
formatting codes so this is more than the number of characters) and the number
of words.

You can export the text by clicking on the Save text button. This opens a
standard RISC OS save box. The exported file is plain text without any styles
in a format suitable for importing into word-processing and DTP applications:
Paragraphs are delimited by single line feed characters.

NB: This file format is not suitable for importing into TextArea because plain
text import expects text in text editor format, i.e., it strips single line
feeds and expects paragraphs to be delimited by double line feeds, but this is
not important because you can copy text from one text area to another via the
clipboard directly without having to go through an external file.

1.15) Exporting to Impression, OvationPro, Composition etc.
-----------------------------------------------------------
Please note that Impression, Ovation Pro and other programs that claim to
render ArtWorks files are only able to render text areas if version 1.50 or
higher of AWRender (the ArtWorks rendering module) is installed. AWRender is
part of the free AWViewer utility that can be downloaded from:
  http://www.mw-software.com/software/awmodules/awrender.html#download

The original version of AWRender as published by Computer Concepts only copes
with the object types that were known to ArtWorks 1.1, so if such an old
version of AWRender is installed, Impression and other applications do not
display text areas. If you want to make sure that text areas are always
displayed correctly in other applications irrespective of the version of
AWRender that is installed, you have to use Draw export. However, this has
several drawbacks and it should not normally be necessary because it should be
easy enough to make sure that AWRender 1.50 or higher is installed.

1.16) Undo
----------
TextArea fully supports the ArtWorks undo facility. The Undo menu item in the
ArtWorks document menu shows text editing operations as "text edit" (if you
type some text) or "alter text" (if you change text properties, e.g. if you
change the font size of some existing text). Changes to text areas are
described as "alter text area". Furthermore, there are the possible operation
names "cut text", "paste text" and "new font". The entry "new font" is there
for technical reasons. It sometimes appears between text editing operations if
you have selected a new font from the font menu. So, if you click on the Undo
button and apparently nothing happens, it may have been a "new font" operation
that does not change anything visible on screen. In that case, simply click on
the Undo button again, and the operation before that is undone (which is
probably the one you meant to undo).

Extensive text editing needs quite a bit of Undo memory because every single
character insertion/deletion and every single text property change has to be
recorded by the Undo system. Therefore, it is advised that you use an Undo
buffer of at least 256k when using TextArea extensively. Remember that ArtWorks
only lets you undo as many operations as it can fit in the Undo buffer. Earlier
operations cannot be undone. The Undo buffer size for each document can be set
in the ArtWorks section of the document choices window. If you want to change
the default value of the Undo buffer size, you can do this by editing the
default document !ArtWorks.Auto.DefDoc (keep a backup copy of the original
DefDoc so you can replace your modified copy with the original in case anything
goes wrong).

1.17) Text overflow
-------------------
If there is more text in a text area than it can accomodate, then the bottom
right selection handle appears in red. This is a hint to remind you that the
additional text can be accomodated by dragging the handle to make the text area
larger. Alternative solutions are to apply a smaller font size to the text or
to delete some text.

1.18) Line breaks
----------------
When formatting text, TextArea breaks lines at spaces, at hyphens (-) or at
M-dashes (). If not even the first word (up to the first space, hyphen or
M-dash) can be fitted in the column, then as many characters as possible of
that word are accomodated in the current line and the word then continues in
the following line.

If not even the first character of a word can be fitted, then this causes a
text overflow (see 1.17).

TextArea does not break lines at N-dashes (). Therefore, if you want a hyphen
of some sort and you do not want a line break at this position (i.e., you want
a so-called non-breaking hyphen), simply use an N-dash instead (keyboard short-
cut Ctrl-Shift-_).

1.18) Defaults
--------------
You can configure the default font and font size to be used by choosing
"Choices..." from the ArtWorks icon bar menu and then clicking on the TextArea
panel. This opens the TextArea configuration window where you can choose the
default font from a font menu and edit the default size in the usual way.
As in other configuration windows, clicking on "OK" retains the setting for the
current session while "Save" saves it for later use as well.

Please note that the configured default font only affects new documents (or to
be precise, your default text area font setting is applied to documents the
first time you create a text area).

In addition to the options in the TextArea configuration dialogue box you can
change the default values given to newly created text area objects. The values
for the horizontal and vertical insets, the number of columns, the column gap,
the tabs offset and the colour of the column frame can be edited in the
ArtWorks !Choices file. Please take a backup copy of this file before modifying
anything and make sure you do not change anything else. Numerical default
values can be entered in any measurement unit that is supported by ArtWorks.

2) Hints and tips
-----------------

2.1) Font cache
---------------
If rendering text areas or editing text in text areas seems slow, check your
font cache settings. In contrast to other applications, ArtWorks does not cause
the font cache to grow automatically if there are many fonts in use (even if
you have configured a large value for FontMax). If you use the TextArea module
with many fonts, you should consider configuring a larger value for FontSize.

If your font cache size setting is too small, ArtWorks (and with it, TextArea)
suffers more than most other RISC OS applications, because of the way it works:
ArtWorks does not hog the font resources it acquires from RISC OS, but instead,
returns them to the OS (and the use of other applications) as early as
possible. This makes the fonts used by ArtWorks the first candidates to be
removed from the font cache instead of the fonts used by applications that hog
them by failing to tell the FontManager that they do not need them right now.

You can check your current settings by pressing F12 to exit from the desktop.
Then type "status FontSize" (without the quotes). The displayed value should be
at least around 320k, or preferably 512k if you want to use many fonts. You can
change the configured value by typing "configure FontSize <n>" where you
replace "<n>" by the desired size, e.g. "512k". Then press Return. Simply press
Return again to return to the Desktop.

Instead of changing your configuration, you can also drag the Font cache memory
allocation bar in the Task manager window (to bring it up, click on the Task
manager icon, displayed as an Acorn symbol or the RISC OS 4 cube in the bottom
right of the icon bar, then locate the bar labelled "Font cache" in the "System
memory allocation" section).

2.2) Bullet lists
-----------------
To create a bullet list, type a bullet point (you can enter this character by
pressing Ctrl-Shift-H), then press the Tab key and type the text of the bullet
point. If you want to start a new bullet point, press Return and do the same
thing again. Finally, switch the Info Bar to Ruler Mode by clicking on the 4th
Info Bar Mode switching button (the one showing an arrow pointing from left to
right). Then, set the "Indent" and "Tab stops every" values to the same value
(e.g., 5mm). This aligns the left margins of the actual text. "First indent"
controls the distance of the bullet points from the column margin. It should be
set to a smaller value (e.g., 0mm).

Page 1 of the Tutorial shows a bulletized list.

2.3) Preventing irregular line spacing
--------------------------------------
Supposed you want to insert a single Dingbats character (e.g., the telephone
symbol) in a paragraph and you discover that to make it look good, you have to
make its font size larger than that of the surrounding text. Unfortunately,
this means that the line containing this character has a larger line spacing
because the line spacing depends on the font sizes used in the line. If this
line is part of a long paragraph, this disrupts the visual harmony of the
paragraph. In order to restore the line spacing of this line to its original
value, simply apply a leading of 0% to the section of text that has a larger
font size. This way, you can prevent any section of text from having an
influence on the line spacing.

2.4) Converting a text area into text lines
-------------------------------------------
Currently, there is no button or menu entry to allow you to convert a text area
into a set of text lines. However, it can be done: Simply export the text area
as Draw, then re-import it into ArtWorks by dragging the resulting Draw file
onto the ArtWorks icon on the icon bar. This opens a window with the text
lines which you can copy and paste into your original document (using
Ctrl-Shift-V so they area pasted into their original positions). If the
position does not matter then you can drop the Draw file icon on the original
document window directly. This inserts the text lines as a group object.

Please note that if the text area has a fill colour or a line colour, then the
text area itself is also exported to Draw as a rectangle in the appropriate
style. If you want the text lines only, simply delete the rectangle after
importing the Draw file.

2.5) Forcing a complete reformat
--------------------------------
Whenever you edit text or change text properties, then the TextArea module uses
a very efficient reformatting mechanism that only reformats the affected parts
of the text. If at any time you enter text or change any text properties and
the reformatting does not seem correct (e.g., the line spacing seems wrong),
you can force a complete reformat of the entire text area by selecting the Text
area tool, placing the caret in the Width or Height field and pressing the
Return key.


3) Bugs and limitations
-----------------------
- The TextArea tool should not be made the default tool (i.e., the one that is
  selected when ArtWorks is loaded) - if you do so, then the clipboard key
  short-cuts will not work correctly (they will have their usual functions to
  cut/copy/paste the currently selected objects even when there is a caret in
  a text area object) until you switch tool for the first time. The default
  tool can be changed by selecting the desired tool and choosing "Save choices"
  from the ArtWorks icon bar menu.
- After undoing a text area property change (e.g., to the "Column gap"), the
  Info Bar is not updated.
- There is a bug in the Computer Concepts TurboDrivers that prevents TextArea
  from printing fully-justified text if the "text" option is not set in the
  TurboDriver Halftone options window. If you notice that fully-justified text
  is missing and you are using the TurboDrivers, please check this option.
- Draw export of text area backgrounds and borders suffers from a known
  ArtWorks bug: The bounding boxes of these objects are slightly too small
  (ArtWorks ignores the line width when calculating the bounding box); this bug
  is in the PathTool module and will be fixed in the future; until then, there
  is a simple workaround: load the exported Draw file into the Draw application
  and save it - Draw fixes the bounding boxes of all the objects on the page


4) History
----------
Version 1.23 (23-Sep-03)
- font substitution of unknown fonts uses Trinity.Medium instead of AvantG.Book
- font substitution now works for fonts that were known when the document was
  loaded but were disabled later (using a font management utility)
- when a document is loaded and some fonts used in text areas have to be
  substituted or fonts that were substituted when the document was saved are
  now available, then all text areas in the document are reformatted
- added help buttons in Info Bars, redesigned Info Bars

Version 1.21 (09-Sep-03)
- defaults are read from ArtWorks !Choices file
- added configuration dialogue box to configure default font and size
- added word/paragraph selection by double/triple clicking

Version 1.20 (20-Aug-03)
- drag resize auto-scroll bug fixed
- enabled (pathified) text export in Illstrator and Corel Draw formats

Version 1.19 (17-Aug-03)
- added text area info window and text export
- proper menu icon in Info Bar

Version 1.18 (18-Jun-03)
- added interactive help for tools

Version 1.17 (03-Jun-03)
- on the Iyonix, PC key conventions are used for the Delete, Home and End keys

Version 1.16 (04-May-03):
- minor bug fix (prevented text tool from displaying the unknown font
  warning message)

Version 1.15 (14-Apr-03):
- first 32-bit compatible release as ArtWorks 2 module

Version 1.13b (02-Apr-03):
- updated documentation

Version 1.13 (13-Feb-03):
- added support for SVG export

Version 1.12 (16-Sep-02):
- added support for Method_ModuleInfo
- fixed C code block problem (too short for data areas)

Version 1.11 (30-Aug-02):
- fixed minor bug that probably did not have any effect

Version 1.10 (28-Mar-02):
- text areas accept Alpha attributes (support for Crystal module)
- Draw export always creates transformed text objects even for text areas that
  are not rotated because only transformed text objects have the kerning flag

Version 1.09 (07-Dec-01):
- fixed silly typo that caused problems with Draw export if exactly 8 fonts
  were used in the text areas of a document
- added Dutch messages (thanks to Dick Tanis)

Version 1.08 (26-Apr-01):
- The wireframe rectangle displayed for text areas at WYSIWYG 0 could not be
  selected. Fixed.
- Text conversion to shapes when exporting as EPS works! This means that you
  can export text areas to Xara X and other PC programs easily. Simply switch
  on the EPS export option "Convert text to shapes".

Version 1.07 (06-Feb-01):
- Pressing the Tab key several times to advance the caret by multiple tab stops
  did not work correctly. You always had to press Tab twice to advance the
  caret to the next tab stop. This has been fixed, but it means that your
  documents may now look different as this meant that you previously inserted
  twice the amount of Tab characters as needed. You will have to remove the
  superfluous Tab characters to correct the appearance of the text. Please note
  that this change may lead to text areas being displayed incorrectly when you
  load a document that was formatted using TextArea version 1.06 or before:
  lines may extend across their column boundaries. As soon as you place the
  caret in the problematic line and start editing, the area is reformatted.
- Deleting selected text that extended to the end of a paragraph including the
  final Return character could cause incorrect formatting of subsequent text
  (this was corrected as soon as any additional editing was done). This has
  been fixed.
- If a complete paragraph including the final Return character was selected and
  a paragraph property (e.g., alignment) was applied, then the property was
  applied to the following paragraph as well. This has been fixed.
- Text area object selection has been improved: You can only place the caret in
  text areas in the active layer. This makes it much easier to work with
  overlapping text areas in multiple layers. By pressing Shift, you can place
  the caret in text areas in all layers. This is a replacement for the
  Multilayer option, which is ignored by TextArea.
- If you place the caret in a text area, other objects are deselected, so the
  text area is the only selected object. This makes it easier to find the caret
  because there are no other selected text areas around.
- Sometimes, "ghost" carets remained on screen. This has been fixed.
- When a colour table file is dragged to ArtWorks the prompt "Do you want to
  place this text on the TextArea clipboard" is not displayed (due to technical
  reasons, the prompt is not supressed if the text is transferred from another
  application, such as an editor)
- added German messages

Version 1.06 (30-Nov-00):
- ArtWorks EPS export reversed the overprint information - fixed

Version 1.05 (29-Nov-00):
- major bug fix for Draw and EPS export (PathTool and TextTool are informed of
  any font and path attribute changes performed when exporting text areas) -
  in previous versions, objects after text areas sometimes had the wrong
  colour and font attributes in exported Draw and EPS files
- exported EPS includes some additional information to help importers rebuild
  a real text area
- major bug fix for PostScript printing: The font declaration code was not
  working, so fonts that were only used in text areas came out as Courier
- the grid was ignored when dragging a handle to resize a text area - fixed
- the font menu stays open if a selection is made if Adjust

Version 1.04 (21-Nov-00):
- fixed bounding boxes of text line objects for Draw export

Version 1.03 (21-Nov-00):
- fixed Draw export problem

Version 1.02 (19-Nov-00):
- first public release version


5) Contacting me
----------------
Martin Wuerthner
Mannheimer Str. 18
67655 Kaiserslautern
Germany

Phone: +49-(0)631-3608205
Fax:   +49-(0)631-3608203

e-mail: martin@mw-software.com
WWW:    http://www.mw-software.com/


6) Copyright
------------
The ArtWorks TextArea module, related documentation and files are  Copyright
2003 by Martin Wrthner. All rights reserved. The software and documentation
may not, in  whole or part, be copied or transmitted by any means without the
explicit written consent of the copyright owner. Unless you have purchased a
site licence for this  software, it may be used on only one stand-alone
computer system at any time.

In order to use this software, you need a licence from the copyright owner. If
you do not have such a licence, you must delete this software, the TextArea
module and its related files, now.
