Custom Characters
 Jonathan Rawle, 1997 (Help file updated 1998)


             Introduction - Using the program - The iconbar menu
  Creating your own character layouts - Creating advanced character layouts


Introduction
------------

Custom Characters allows you to use text characters that are not easily
entered from the keyboard. Is is intended to be an alternative to the Chars
application which is supplied with all Acorn computers.

Custom Characters is different from other character selecting utilities, in
that it allows you to choose which characters you want to appear in the
character window, and where you want then to be in the window. This is quite
simple to do- no programming knowledge is required! You can create many
character layouts and save them so that they are always available from
Custom Characters' menu. Some example layouts are provided to get you
started.


Using the program
-----------------

Double-click on the !CustomChr icon. The program will load onto the iconbar
as usual. Clicking on the iconbar icon will open the currently selected
character window.

Characters in the character window can be clicked upon to enter them at the
caret. 
If the caret is currently in a writable menu or a dialogue box, clicking the
mouse in the character window will close the dialogue, and you will have to
start again. There are two ways of overcoming this:
1. Position the pointer over the character you require, but press Shift
   instead of clicking. This is the method used by Acorn's 'Chars', and most
   other character programs.
2. Use the 'Magic entry' option. This allows you to click the characters,
   but leaves the dialogue box open! (as if by magic?!) This is explained
   in more detail below.

Click inside the window with the menu (middle) button to open the character
menu. This allows you to select which character layout is displayed in the
window. If you create any of your own 'custom' layouts, they will also
appear in this menu.


The iconbar menu
----------------

Clicking with the menu button on the iconbar icon opens the iconbar menu
which contains the following items:

Info - This gives the usual information about the program.

Characters - Sliding off this item is another way of accessing the character
menu (also available by clicking menu over the character window).

Font - Sliding off this reveals the font menu, which will contain all the
currently installed fonts. This allows you to change the font used in the
character window.
             
Shift entry - Select this item to toggle shift entry on and off. If shift
entry is selected, pressing shift enters the character currently under the
pointer to allow entry into dialogue boxes etc. You may occasionally want to
switch this facility off though; it can be a nuisance when you are typing
away, press shift to type a capital letter, and end up with an unexpected
ellipsis or Faroese character!

Magic entry - Select this item to toggle the magic entry facility. If magic
entry is enabled, the pointer changes to a hand when it is over the
character window. You can now click characters, and they will be entered at
the caret- even if the caret is in a dialogue box or writable menu! This
means that you can always enter strange characters without worrying about
the shift key.
NOTE - the pointer may occasionally remain as a hand, even though it has
left the character window. If this happens, clicking a mouse button will
return the pointer to normal.

Save status - this saves the currently selected character layout, the window
position, the current font, and all the menu options so that they will be
selected by default next time the program is started.

Quit - this ends the program, removing the iconbar icon as normal.


You should now be able to use all of the features of the program to access
the example layouts supplied. Once you are familiar with the program, it is
far better to create your own character layouts, with just the characters
you want, positioned as you wish. To do this, read the section below


Creating your own character layouts
-----------------------------------

Character layouts are simply textfiles containing the characters you want.
They are stored in the directory !CustomChr.Characters. To access this
directory, hold shift and double-click on the !CustomChr directory. You can
now double-click and open the Characters directory. This should contain
several textfiles. You may wish to look at these as examples when you are
reading the instructions below.

The first line in your textfile should be the title for the character
window.

The second line is the width of each character 'button' in OS units. You do
not need to know what this means; making the number higher makes the buttons
wider, a lower number makes them more narrow. Usually you will use 52, as
this gives square buttons.

Subsequent lines contain your list of characters. Each character should be
on its own line, followed by return.
(Of course, these characters will often not be available from the keyboard,
so you should use Custom Characters' full character set window or Acorn's
Char application to enter them.)

As an alternative, you can use the characters ASCII code; for example type
65 for capital A. If you want to include a comma (,) in your layout, you
must use its code (44) otherwise you will confuse the program.

If you want to start a new line in your character window, include the symbol
\\
on its own line.
- You can include as many of these as you want
- Lines of characters do not have to be the same length; Custom Characters
  will size the window to accommodate the longest line
- If you do not include any \\ all the characters will appear on one line

When you have finished entering your list of characters, be sure to press
return after the last one.

Now, save the textfile into the Characters directory. The filename you
choose will be the one displayed in the Characters menu, so choose something
meaningful. If you now quit and re-load Custom Characters, your layout
should appear in the menu and you will be able to use your layout.

You now know everything you need to to create simple character layouts, and
for most layouts this is all you need to know. It is, however, possible to
have even more control over how the characters appear in the window, and
this is described below. 


Creating advanced character layouts
-----------------------------------

As an example, look at the Qwerty and QwertyC layouts supplied with Custom
Characters. Notice that the buttons are all different widths, and some are
in different colours. Notice, also, that if you click on the green 'C', the
program switches between the two layouts. You can use all of these features
in your own layouts.

Instead of just listing a character, you can use a special command to
describe the features of the character. This takes the following format:

(character displayed),(character typed),(button width)

- The displayed character is what you will see in the character window. The
  typed character is what will appear when you click the button
- Each part of the command is separated by commas
- You do not have to include all parts of the command:
  - If you omit a typed character, the displayed character is used as the
    typed character
  - If you do not include a width, the default width (from the start of the
    file) is used
  - You must include a displayed character
- You can use the ASCII code, or the actual character (where possible) for
  the displayed and for the typed character
- If you use the ASCII code for the displayed character, you can add a
  (colour number)*1000 to it. For example, 65 gives a black A, but 9065
  gives a yellow A
   (The colours follow the usual 16 colour desktop palette, except that 0 is
    black and 7 is white)

If the above description seems a little complicated, the following examples
will hopefully make things clearer:

Command         Meaning
-------         -------
A               Black 'A' which when clicked types 'A'
65              Does the same as above
11065           Red 'A' which when clicked types 'A'
7065,a          White 'A' which types a lower case 'a' when clicked
X,,104          Black 'X', types 'X' when clicked, button twice usual width
<,127,80        Black '<', deletes when clicked, 80 pixels wide
121,,32         Black 'y', types 'y' when clicked, narrower than usual
0,0             Black '0', types '0' when clicked
0,00            Black '0', types ASCII 0 when clicked (note the two digits)


You will already have come across \\ to start a new line. But if you include a number after the \\, a gap that many OS units will be left between the two lines. Examples:

\\              New line
\\4             New line, leaving a slight gap
\\52            New line, leaving a line
\\-8            New line, overlapping the line above slightly


You can leave a gap between two buttons on the same line by using >>>x
(where x is a number). Examples:

>>>4            Leave a slight gap between the last button and the next
>>>52           Leave a gap 1 button wide
>>>-16          Overlap the last button slightly

You can also include >>> commands at the start or end of a line to leave
larger gaps at the edges of the window.


The final command which you can use is the link command. If you include this
in your file, button that you defined BEFORE the link command will load a
different layout when clicked INSTEAD of typing a character. This is 
regardless of whether you specified a typed character of not.

The syntax of the link command is:

L:(filename)
where (filename) is the filename of another character layout

Examples:

A               Black 'A' which loads file 'Char1' when it is clicked
L:Char1         

15070,,104      Light blue 'F' wide button, loads file 'French' when clicked
L:French

Q,?,40          Black 'Q', narrow button, load file 'Quotes' when clicked
L:Quotes        (does not type a '?')



You should now be able to reproduce any of the examples supplied with Custom
Characters, and create your own advanced character layouts.


 ________________________
(________     ________   \
         |   |________)  | __________________________________
         |    _      ____/ Jonathan Rawle
 ________|   | \__   \___  e-mail: jonathan@rawle.org
(____________/    \______) http://jonathan.rawle.org/
