Help on TemplEd
#Sprite 40,0 !templed
#Indent 9
TemplEd
v 1.29
#Indent 0
-------------------
 <    Licence      >
 <Loading & Saving =>LoadAndSave>
 < Mouse operation =>Mouse>
 <Positioning icons=>IconPos>
 <  Editing icons  =>EditIcon>
 < Editing windows =>EditWin>
 <  Miscellaneous  >
 < Technical info  =>TechInfo>
 <    Credits      >
-------------------
 (c) <Dick Alstein=>Address>Copyright notice
TemplEd is FreeWare, which means:
#Indent 2

* You may freely copy and distribute it.
* You may modify it for personal use, but
  copies that you distribute must contain
  all ORIGINAL files.
* I don't charge anything for it. If you
  paid a PD library for this and it cost
  you more than the price of a floppy plus
  a stamp, you have probably been ripped off.Loading and saving
Loading a template file:
  - Double-click on a template file
    (starts a new copy of TemplEd if it has
    already loaded some templates), or
  - Drop the file on the icon bar icon
    (removes the current templates and loads
    new ones), or
  - Drop an application on the icon bar
    (loads the file "Templates" in the
    application directory)

Adding the contents of a template file:
    Drop the file on the browser window

Saving the templates:
    From the menu (as usual)

TemplEd can also <load Sprites files=>LoadSprites> that
contain sprites for the templates.Template files
#Indent 5
#Sprite 0,0 file_fec
Template files contain window definitions
that are almost identical to the definition
blocks used for the SWI <Wimp_CreateWindow=>SWI.Wimp_CreateWindow>

#Indent 0
Your program can read the Templates from a file
with <Wimp_OpenTemplate=>SWI.Wimp_OpenTemplate> and  <Wimp_LoadTemplate=>SWI.Wimp_LoadTemplate>Mouse operation
Function                      Button          Remark
--------------------------    ------          ------
Select icon(s) (exclusive)    Select          <1=>Remark1>
Select icon(s) (toggle)       Adjust          <1=>Remark1>
<Move icon(s)=>MoveIcon>                  Shift+Select    <2=>Remark2>,<3=>Remark3>
<Resize icon(s)=>ResizeIcon>                Shift+Adjust    <2=>Remark2>,<3=>Remark3>
<Edit icon(s)=>EditIcon>                  Shift+Menu      <3=>Remark3>,<4=>Remark4>,<5=>Remark5>
<Move window=>MoveWindow>                   Ctrl+Select     <6=>Remark6>
<Resize window=>ResizeWindow>                 Ctrl+Adjust     <6=>Remark6>
Resize work area              Ctrl+Alt+Adjust <6=>Remark6>
<Edit window=>EditWin>                   Ctrl+Menu       <7=>Remark7>
Edit title bar                Ctrl+Menu       <8=>Remark8>,<9=>Remark9>
Renumber icon(s) (count up)   Alt+Select      <10=>Remark10>
Renumber icon(s) (count down) Alt+Adjust      <11=>Remark11>

      Some functions have a <keyboard shortcut=>Ctrlkeys>Remark 1
Clicking selects a single icon (*)
Dragging the mouse selects all icons
within the drag-box.

*: click-selecting does not work
for some button types (e.g. Menu)Remark 2
Also works for click without Shift,
if mouse button is pressed longer
than 0.5 secondsIcon positioning
 <Move=>MoveIcon>   <Resize=>ResizeIcon>   <Align>   <Space out=>SpaceOut>   <Center=>CenterIcon> Remark 3
Function operates on all
selected icons, or (if
no icons are selected) on
the icon under the pointerRemark 8
The pointer must be
over the title barRemark 10
When repeating this, next icon number is:
\<number issued on last renumber\> + 1Remark 11
When repeating this, next icon number is:
\<number issued on last renumber\> - 1Remark 4
If more than 1 icon is edited,
only the icon flags can be modifiedRemark 5
Can also be done by a
double-click with Select
on the iconMoving icons
Click Shift+Select to start the Move.
(for details see remarks <2=>Remark2> and <3=>Remark3>)

Drag the outline around the icon(s) to the
desired position. During the drag, you can
also use the <cursor keys=>CursorKeys> to move the pointer. 

Pressing the cursor keys without dragging
moves the selected icons.

- If you drop the icons in another template
  window, they will be copied to that window.
- If you move them outside any template
  window, they will be deleted (only if the
  "Delete icons moved outside" option is on).Cursor Keys
The ,, and  keys move the pointer 1 pixel
(when Shift is held: 4 pixels)Resizing icons
Click Shift+Adjust to start the Resize.
(for details see remarks <2=>Remark2> and <3=>Remark3>)

Drag the "rubber box" outline around the icon(s).
You can move one side of the icon(s) at a time;
the side that is moved is the one that was
nearest to the pointer when you clicked.

During the drag, you can also use the <cursor keys=>CursorKeys>
to move the pointer.Aligning icons
Changes the selected icons so that they are lined up.
You can align their left-hand sides, right-hand sides,
top, bottom, or the centres (in either the horizontal
or vertical direction).

"Move icons"   - change the icon position
"Resize icons" - move only 1 side of the icon

            * <click here for an example=>AlignXmpl> *Space Out
Moves the selected icons so that there is
a constant space (horizontal or vertical)
between them.

"Use available" - use the available space
                  between the outer icons

      * <click here for an example=>SpaceXmpl> *Example of Space Out
Suppose you have four icons, positioned

                     
    A                  B    C        D 
                     

Using a fixed space gives you something like

        
    A       B      C    D 
        

and choosing "Use available" results in

                     
    A           B          C         D 
                     

(If this looks horrible, set "Redefine Chars" on.)Function keys
F2      = "Update"
F3      = "Update & Exit"
Esc, F4 = "Exit"The "Icon Edit" window
Remarks:
  - Some fields (button type, colours, font) can
    contain a limited number of values. These can
    be set either by clicking on the arrow icons
    to the left and right, or from a menu (click
    on the field to get the menu)
  - You can use the <function keys=>Editkeys> as shortcuts
    for the "Update", "Update & Exit" and "Exit"
    buttons
  - You can get <info=>IconInfo_Flags> on the meaning of the various
    buttons in the window by pressing F1 while the
    pointer is over the button
  - When editing a selection, you can change only
    the icon flags. To change a single flag, click
    Menu over "Update" or "Update & Exit" and
    choose the flag.The "Window Edit" window
Remarks:
  - The contents of the title bar are edited separately,
    using the "Icon Edit" window; click Shift+Menu
    while the pointer is over the title bar
  - You can use the <function keys=>Editkeys> as shortcuts
    for the "Update", "Update & Exit" and "Exit"
    buttons
  - You can get <info=>WinInfo_Flags> on the meaning of the various
    buttons in the window by pressing F1 while the
    pointer is over the buttonMisc.
<Min. size     =>MinSize>
<Custom sprites=>CustomSprites>
<Ensure icons  =>EnsureIcons>
<Deleted icons =>DeletedIcons>Loading sprites files
* Drop a sprite file on the icon bar icon

* If a templates file named "Templates" is
  loaded, the file "Sprites" in the same
  directory is automatically loaded with it.Keyboard shortcuts
Key     Function
------  ---------------------------
Ctrl-A  Select all icons
Ctrl-C  Copy selected icons
Ctrl-D  Copy icons downward
Ctrl-E  Edit selected icons
Ctrl-L  Copy icons to left
Ctrl-R  Copy icons to right
Ctrl-U  Copy icons upward
Ctrl-X  Delete selected icons
Ctrl-Z  Clear icon selection

Ctrl-Q  Close window (also Ctrl-F2)
Ctrl-T  Edit title bar
Ctrl-W  Edit window

Ctrl-J  Open "Align" box
Ctrl-K  Open "SpaceOut" boxMoving windows
Select-click on a window with Ctrl pressed, to
drag the window to the desired position.
During the drag, you can also use the
<cursor keys=>CursorKeys> to move the pointer.Resizing windows
Adjust-click on a window with Ctrl pressed, to
resize the window. During the drag, you can
also use the <cursor keys=>CursorKeys> to move the pointer.Credits
Thanks are due to The Risc Squad, Jonathan Marten
and Tim Browse for writing applications from which
I have "borrowed" ideas for TemplEd.

Alex Petrov wrote the MenuUtils module, Martin
Ebourne created the hires sprites.

TemplEd has also been much improved by the testing,
comments and suggestions of Stephen Burke, Martin
Ebourne, Michael Ellis, Edwin Hautus, Paul Hobbs,
Rupert Johnson, Merlin Hughes, Olaf Krumnow,
Paul Lebeau, Ian Palmer, John Pullan, Niklas Rjemo,
John Tytgat, Julian Wright, and I'm sure I forgot
some others.Centering icons
Centers the icon (or selected icons)
to the currently visible window areaRemark 7
Can also be done by a
double-click with Select
on the window backgroundRemark 9
Can also be done by a
double-click with Select
on the title barRemark 6
Only works if the "Movable"-flag
of the window is setExample of Align
This is an example of left-aligning with three
icons. Icon B is the leftmost, and does not change.

Original           Left-Aligned       Left-Aligned
    Position       with Move          with  Resize

                                     
                            
   A              A                 A  
                            
                    
   B                B                B   
                    
                        
       C           C                  C    
                        
                                     

(If this looks horrible, set "Redefine Chars" on.)'Border' flag
Flag ON : Icon has a rectangular border

The border type is set in the validation string,
with the <'R' command=>IconInfo_ValidStrCmdR>. (Default border is simple
rectangle in foreground colour)'Filled' flag
Flag ON : Fill icon with background colour
          when it is redrawn
Flag OFF: 'Transparent' icon'H centred' flag
Flag ON : Icon contents (text/sprite) are
          horizontally centred

(For left-justifying: set 'H centred' and
 'R justified' flags off)'V centred' flag
Icon contents (text/sprite)
are centred vertically'R justified' flag
Icon contents (text/sprite)
are right-justified

(For left-justifying: set
 'H centred' and 'R justified'
 flags off)'Needs help' flag
Flag ON : Icon requires the help of the task to be
          redrawn (generates Wimp_Poll Redraw events)
Flaf OFF: Wimp redraws icon by itself'Allow adjust' flag
Flag ON : Allow selecting more than 1 icon
          in this ESG, by clicks with Adjust
Flag OFF: Clicking Adjust always deselects
          other icons in ESG'Half size' flag
Flag ON : Draw the sprite at half its size
Flag OFF: Sprite (if present) at normal sizeIcon button type
Determines when the task is notified of mouse clicks

Button type        Meaning
-----------------  -----------------------------------------------------
Never              Ignore all clicks on the icon
Always             Notify continuously while the mouse is over the icon
Auto-repeat        Notify of click, then auto-repeat
Click              Notify once
Release            Click selects, move away deselects. Notify of release
Double click       Click selects. Double-click notifies task.
Click/Drag         As 'Click' + Notify of drag (returns button*16)
Release/Drag       As 'Release' + Notify of drag (button*16)
Double/Drag        As 'Double click' + Notify of drag (button*16)
Menu               Notify once. Select while the mouse is over the icon
Double/Click/Drag  Notify of Click (*256), Drag (*16), Doubleclick (*1)
Radio              Click toggles selection (*1), Drag notifies (*16)
Write/Click/Drag   As 'Click/Drag' + Gain caret when clicked
Writable           As 'Click' + Gain caret when clicked

(Clicks with Menu are ALWAYS passed on to the task)

Behaviour of writable icons can be controlled in the validation string,
with the <'A' command=>IconInfo_ValidStrCmdA> and <'K' command=>IconInfo_ValidStrCmdK>ESG
Exclusive Selection Group  (number from 0-31)

If ESG > 0, then clicking an icon with Select
deselects other icons with the same ESG number

Effect of click with Adjust is determined by
'<Allow adjust=>IconInfo_Allowadjust>' flag'Shaded' flag
Flag ON : Icon is shaded; it is shown in grey,
          and mouse clicks on it are ignoredFgcol
Sets the foreground colour of
 - Icon text (if not using an outline font)
 - Standard icon border (if '<Border=>IconInfo_Border>' flag set)Bgcol
Sets the background colour'Outline font' flag
Flag ON : Display icon text in outline font
          Font colours are set in validation
          string, with <'F' command=>IconInfo_ValidStrCmdF>
Flag OFF: Display icon text in system fontValidation string
Controls several aspects of
behaviour and appearance
of an icon.

    <Commands=>IconInfo_ValidStrCmd>    <Syntax=>IconInfo_ValidStrSyntax>'Max size' field
Indicates the maximum size of indirected data.

For writable icons, this determines the
maximum length of the input text.
Your program should never write longer strings
into the buffer!
(Add 1 for the string terminator.)'Indirected' flag
Is needed if:
  * you need more than 12 bytes to store
    the icon text or sprite name
  * you want to use a <validation string=>IconInfo_Validation>
  * you want both text and a sprite
    in the icon (use the <'S' command=>IconInfo_ValidStrCmdS>
    in the validation string)

The indirected data is stored in a buffer.
The buffer size is set in the '<Max size=>IconInfo_Maxsize>'
field.Technical info
#Indent 2
<   Windows    =>TechInfo_Window>
<    Icons     =>TechInfo_Icon>
<Template files=>TechInfo_Templ>Validation string syntax
Validation string = Commands, separated by ";"
Command           = Single letter +
                    command-dependent contents

There are 4 special characters \\ ; - ~
In a command, they must be preceded by a "\\"Validation string commands
<A - Allow/disallow characters=>IconInfo_ValidStrCmdA>
<D - Display characters       =>IconInfo_ValidStrCmdD>
<F - Set outline font colours =>IconInfo_ValidStrCmdF>
<K - Handle editing keys      =>IconInfo_ValidStrCmdK>
<L - Multi-line text icon     =>IconInfo_ValidStrCmdL>
<P - Change pointer shape     =>IconInfo_ValidStrCmdP>
<R - Border type              =>IconInfo_ValidStrCmdR>
<S - Sprite name              =>IconInfo_ValidStrCmdS>Validation string - 'A' command
Syntax: A{allowed chars}|~{disallowed chars}

Controls the input of characters in writable icons

Examples: A0-9   Allow only digits
          A~$#/  Allow all characters, except $ # /
          A~\\-   Don't allow the minus
          A~     Don't allow any charactersValidation string - 'D' command
Syntax: D{character}

Display all characters in a string as a {character}
Useful when entering passwords

Example: D*  Show text as row of asterisksValidation string - 'F' command
Syntax: F{background colour}{foreground colour}

Sets the colours of the outline font used for the icon
Colours are entered in hexadecimal
Default: Black on White

Examples: F07  Black on White (the default)
          F7C  Cream on Black (yuck!)Validation string - 'L' command
Syntax: L[{number}]

Turns the icon into a multi-line text icon.
The number indicates the line spacing, but
   this is not implemented yet (in RiscOS
   3.10). The default is 40.
Outline fonts can not be used.Validation string - 'K' command
Syntax: K {A,R,T,D,N or a combination thereof}

Handles keypresses according to Acorn guidelines:

A  for  and  keys; move the caret to the
   previous/next writable icon
R  for Return key; move caret to next writable
   icon, or notify task when in last icon
T  for Tab and Shift-Tab keys; move caret to
   previous/next writable icon
D  handle keys as in RiscOS 2 (, , Delete,
   Ctrl-U, etc.) but also notify task
N  notify task of all keys

This command is not available in RiscOS 2Validation string - 'P' command
Syntax: P{sprite name},{active_x},{active_y}

Changes the shape of the pointer while over the icon.
The sprite must be present in the Wimp sprite area.
The numbers active_x and active_y are the offset for
the "active point" from the topleft corner.

This command is not available in RiscOS 2Validation string - 'R' command
Syntax: R{border type}[,{slab in colour}]

Selects the border type:
  0 - Standard single pixel border
  1 - Slab out
  2 - Slab in
  3 - Ridge
  4 - Channel
  5 - Action button
  6 - Default action button
  7 - Writable field

The slab in colour is shown when the icon is
selected (type 5 and 6). Default: 14 (orange)

This command is not available in RiscOS 2Validation string - 'S' command
Syntax: S{sprite name}[,{sprite name}]

For Text+Sprite icons.
Tells the Wimp what sprite to display.
The second sprite is displayed when the
icon is selected.

Example: Soptoff,opton  Usual setting for
                        an 'Option' iconIcons
In general, an icon is just a rectangular
area in a window. It consists of:

  Coordinates of the bounding box
      (min. X, min. Y, max. X, max. Y)
  <Icon flags=>IconInfo_Flags>
  Other icon data
      (depends on the 'Text', 'Sprite'
       and 'Indirected' icon flags)

See also SWI <Wimp_CreateIcon=>SWI.Wimp_CreateIcon>.Icon flags
Flag         Meaning
-----------  ---------------------------------------
Text         Icon contains text
Sprite       Icon contains a sprite
<Border      =>IconInfo_Border> Icon has a border
<H centred   =>IconInfo_Hcentred> Contents centered horizontally
V centred    Contents centered vertically
<Filled      =>IconInfo_Filled> Icon has a filled background
<Outline font=>IconInfo_Font> Text is in anti-aliased font
<Needs help  =>IconInfo_Needshelp> Icon requires task's help to be redrawn
<Indirected  =>IconInfo_Indirected> Icon data is indirected
<R justified =>IconInfo_Rjustified> Text is right-justified
<Allow adjust=>IconInfo_Allowadjust> If selected with Adjust, don't
             cancel other icons in same ESG
<Half size   =>IconInfo_Halfsize> Display sprite at half size
<Button type =>IconInfo_Buttontype> Icon button type
<ESG         =>IconInfo_ESG> Exclusive Selection Group
Selected     Icon is selected by user (inverted)
<Shaded      =>IconInfo_Shaded> Icon un-selectable (greyed out)
Deleted      Icon is deleted
<Fg colour   =>IconInfo_Fgcol> Foreground colour
Bg colour    Background colourWindows
A window definition contains the following data:

  Current position and scroll offset
  <Window flags=>WinInfo_Flags>
  Colours of title bar, scroll bars, etc.
  Title bar data
  Sprite area for sprites in icons
  Minimum and maximum size of the window

See also the SWI <Wimp_CreateWindow=>SWI.Wimp_CreateWindow>.Window flags
#Table 10 16
<Moveable      =>WinInfo_Moveable>
<Auto-redraw   =>WinInfo_Auto-redraw>
<Hot keys      =>WinInfo_Hotkeys>
<Pane          =>WinInfo_Pane>
<No bounds     =>WinInfo_Nobounds>
<Back window   =>WinInfo_Backwindow>
<Keep on Screen=>WinInfo_OnScreen>
<Button type   =>WinInfo_Buttontype>
<GCOL colours  =>WinInfo_GCOL>
<Scroll        =>WinInfo_Scroll>
Back 
Close 
Title bar 
Toggle 
V scroll 
Adjust 
H scroll 
<New format    =>WinInfo_Newformat>

<Ignore Extent =>WinInfo_NoExtent>
#EndTable'Moveable' flag
Flag ON : Window can be dragged around
          by clicking on the title bar
Flag OFF: Window can only be opened at
          another place by the program'Auto-redraw' flag
Flag ON : Wimp redraws window without
          asking help from the task
Flag OFF: Task gets Wimp_Poll Redraw
          events'Hot keys' flag
Flag ON : Task is notified of 'Hot key' presses
Flag OFF: Window only gets KeyPress events if it
          has the input focus'Scroll' flags
Flags ON : Task gets Scroll_Request events when
           user clicks on scrollbar
            - repeat: repeat events until button
                      is released
            - 1:      debounced, 1 event per click
Flags OFF: Clicks on scrollbar are handled in
           standard way (scroll+redraw window)'Pane' flag
Flag ON : Window is a 'Pane' window - see PRM
Flag OFF: Normal window'No bounds' flag
Flag ON : Window can be opened/dragged outside
          the screen area
Flag OFF: Window stays fully on-screen'Back window' flag
Flag ON : Other windows can not be opened
          below this one (for e.g. backdrop)'New format' flag
When off, the window flags are
in old (pre-RiscOS) format.

Leave it on.'GCOL colours' flag
Flag ON : Treat colour numbers as GCOL colours; colour
          numbers can be from 0-254 in 256-colour modes
          (not colour 255: it is used as 'transparent')
Flag OFF: Colours from standard 16-colour Wimp paletteWindow button type
Determines when the task is notified of mouse clicks

Button type        Meaning
-----------------  ----------------------------------------------------
Never              Ignore all clicks on the window
Always             Notify continuously while mouse is over the window
Auto-repeat        Notify of click, then auto-repeat
Click              Notify once
Release            Notify of release
Double click       Notify of double-click
Click/Drag         As 'Click' + Notify of drag (returns button*16)
Release/Drag       As 'Release' + Notify of drag (button*16)
Double/Drag        As 'Double click' + Notify of drag (button*16)
Double/Click/Drag  Notify of Click (*256), Drag (*16), Doubleclick (*1)
Writable           As 'Click' + Gain caret when clicked

(Clicks with Menu are ALWAYS passed on to the task)'Ignore extent' flags
Flags ON : Ignore window extent when resizing it
           Drag-box is unbounded to the right
           (H flag) or to bottom (V flag)
Flags OFF: Bounded drag-box, calculated from
           window extent

These flags are not known in RiscOS 2'Keep on Screen' flag
Flag ON : When moving or resizing, visible area
          is kept fully within screen area
Flag OFF: Window can be dragged partly off-screenMin. size
Minimizes the icon size, in X-, Y- or
both dimensions. The bottomleft corner
of the icons is kept at the same positionCustom sprites
View/Edit   Run the file with custom sprites
            (i.e. make !Paint load it) 
Re-load     Read the file again (after you
            have edited it)
Reset       Discard the sprites, use the
            Wimp areaEnsure icons
Check the position of icons, making sure
that they are
  - within the window's work area, or
  - within the currently visible area

and move them if needed  Deleted icons
To retrieve icons that have been
marked as deleted, or to
definitively remove themAddress
You can send your comments, bug reports,
questions, postcards, etc. to:

#Indent 4
Dick Alstein
Lijnslagerstraat 204
NL-5625BP  Eindhoven
The Netherlands

e-mail: wsinda@info.win.tue.nl
        (until 15-Sep-94)