Archive Magazine 1996/ARCHIVE_96.iso/discs/mag_discs/volume_7/issue_09/templed/!TemplEd/Manual

Text File | 1993-09-12 | 26KB | 592 lines

                            TemplEd User Manual
                            -------------------


1. About TemplEd
________________

TemplEd is a template editor. With it, you can create and edit Template
files, which contain definitions of the windows used by an application. If
you want to know what can be in template definitions, and how they can be
read by a program, read the information about the SWIs Wimp_CreateWindow,
Wimp_CreateIcon and Wimp_LoadTemplate. This can be found in the RiscOS PRM
(Programmer's Reference Manual), and on-line in Guttorm Vik's !StrongHlp
application.

TemplEd is FreeWare. For conditions of use, read the copyright notice at the
end of this manual.


2. About this manual
____________________

If you are an experienced user, the !Help file will probably contain enough
information for you to get started. You may want to skip the boring
discussion of TemplEd's operation that follows. However, there are some
technical details that may be of interest. These have been marked with <TD>.
There is also a list of operation shortcuts and "hidden" features at the end
of this manual.


3. Starting the program and loading files
_________________________________________

After you have double-clicked on the application, the program installs
itself on the icon bar. A double-click on a Template file also starts
TemplEd, after which TemplEd loads the file.

You can load a template file by:

* Double-clicking on a Template file. If TemplEd is running and has not
loaded any templates, it loads the file. Otherwise, a new copy of TemplEd is
started.

* Dropping the file on the TemplEd icon on the icon bar. TemplEd deletes the
currently loaded templates, and loads the new file. If the current templates
have been modified, TemplEd first asks you to confirm before deleting them.

* Dropping the file in the Templates window. TemplEd adds the templates in
the file to the currently loaded ones.

If the file is called "Templates", then TemplEd will look for a sprite file
called "Sprites" in the same directory. If there is such a file, TemplEd will
assume that it contains the sprites to be used with the templates, and will
automatically load the sprite file as well.

Other sprite files with sprites used in the templates, can be loaded by
dropping them on the icon bar icon.

When you drop an application on the icon bar icon, TemplEd will load the file
"Templates" in the application directory (if present). If there is a sprite
file called "Sprites" in that directory, TemplEd will also load it.


4. Opening and closing a template window
________________________________________

A click with Select on the TemplEd icon on the icon bar opens the Templates
window. This displays the currently loaded templates. A small window icon
before the name indicates what type of window it is (scrollbars, title). A
yellow background of this icon means that it is currently open.

You can open a template by double-clicking on its name. If the template was
already open, it is closed. The "Open" and "Close" entries in the menu serve
the same purpose.


5. Selecting icons
__________________

Many operation on icons can be done on a single icon but also on a selection
of icons. There are several ways to select (and deselect) icons:

* Click with Select to select a single icon while deselecting the others. A
click on the background of the window clears the current selection.

* Click with Adjust to select an icon, without changing the rest of the
selection. If the icon was already selected, it is deselected.

* A drag with the mouse creates a drag-box in the window area. When you
release the mouse button, all icons within the box are selected.

* There are "Select all" and "Clear selection" items in the menu.

<TD> Like most other template editors, TemplEd creates a window for each
template, and creates icons exactly as they have been defined. This means
that the Wimp reacts to the mouse just as it would when a program was using
the template. That's why a menu icon is hard to select: you can click on
it, but if you move the pointer away from the icon, the icon is deselected
again. The Wimp also interferes if you want to select several radio buttons
from the same ESG. Even if you click with Adjust, the Wimp deselects the
other buttons (unless their 'Allow adjust' bit is set). You can select these
"difficult" icons with a drag-select.

<TD> If you want to check the behaviour of icons to mouse clicks, without
TemplEd reacting to the clicks, press a combination of keys (e.g. Shift +
Alt) while clicking. That way you can check if the ESGs of radio buttons
are set right, if option buttons are switched on and off, etc.


6. Moving and resizing icons
____________________________

To move an icon or a selection, click inside the window with Select while
holding down the Shift key. An outline appears around the icon(s) that moves
with the pointer until you release the mouse button. During the operation,
the pointer shape is changed to a hand.

To resize an icon or a selection, click on it with Shift+Adjust. A "rubber
box" drag is started, allowing you to move one side. The side that is moved
is the one that was nearest to the pointer when you clicked. It is also
indicated by the pointer shape. Though a resize operation will usually be
done on a single icon, it is possible to resize more than one icon at a
time; the icons are scaled according to the size of the drag-box.

An alternative way to move or resize icons is by clicking on them without
using the Shift key, and keeping the mouse button pressed for about half a
second.

During the drag, you can move the pointer with the cursor keys. The left,
right, up and down keys move the pointer 1 pixel (in the expected direction).
If you press a cursor key in combination with the Shift key, the movement is
4 times as fast.

Pressing the cursor keys without starting a drag first moves the selected
icons.


7. The "Icon Edit" dialogue window
__________________________________

Except for size, position and number, all properties of an icon can be set
from the "Icon Edit" dialogue window. To open this window, click with
Shift+Menu, or choose the "Icon ë Edit..." entry in the menu.

Icon flags can be set by clicking on the buttons, text and sprite names can
be entered in the appropriate fields. Use the up and down arrow keys to move
the cursor around. Some fields (e.g. button type, colours, font name) can
contain a limited number of values. These can be selected either by clicking
on the arrow icons to the left and right, or by clicking a mouse button while
the pointer is over the field. This pops up a menu from which you can select
a value.

<TD> The "1:1" button for the font is the only button not connected to an
icon flag. When on, it keeps X and Y size of the font equal, so you don't
have to set them both.

The changes to the icon only take effect if you press the "Update" icon.
"Exit" closes the window, leaving the icon as it was since the last update,
and "Update & Exit" combines the two.

<TD> If the indirected text that you entered is longer than the "Max
size" field allows, TemplEd automatically increases the maximum. It also
sets the "Indirected" flag if the text or sprite name uses more than 12
characters.

When you edit a selection of icons, not all fields can be modified (to be
exact: only the icon flags). The unchangeable fields are shaded. When you
press "Update" or "Update & Exit", the changeable fields are modified in
all selected icons. In some cases, you may only want to change one field,
e.g. the button type. To do this, click Menu above the "Update" or
"Update & Exit" button. A menu pops up from which you can select the flags
that must be changed.


8. Moving and resizing windows
______________________________

Usually, you can move a window by dragging the title bar, and you resize it
by dragging its resize icon. But some windows don't have a resize icon, and
some don't even have a title bar. You could of course edit the windows, give
them a title bar or resize icon, and remove these when you are done. But in
TemplEd, it is also possible (and much faster) to move and resize windows
directly. Use Ctrl+Select to move a window, and Ctrl+Adjust to resize it.

Just as with moving and resizing icons, the cursor keys can be used during
the drag to position the mouse pointer.


9. The "Window Edit" dialogue window
____________________________________

Editing the data of a window is split in two parts. Flags, colours and
button type are edited in the "Window Edit" dialogue window. This window
is opened when you click Ctrl+Menu over the window, The contents of the
title bar are edited separately, using the "Icon Edit" window. It is
accessible with a Shift+Menu click while the pointer is over the title bar.
Both dialogue windows can also be opened from the menu.

<TD> The "transparent" colour number 255, that has a special meaning as the
title foreground colour or as the work background colour, is only selectable
from the colour menu, not by clicking on the arrow icons.


10. TemplEd's menus
___________________

Most entries in the menus ought to speak for themselves. Some others may
take a small explanation:

10.1 The "Window" menu

  Create ë

  Leads to a submenu with a number of standard icons. Selecting one of these
  creates such an icon, at the position that the pointer was on when the
  menu was popped up. Selecting the "Create" entry itself is equal to
  selecting the first standard icon from the menu.

  You can change the set of standard icons, see the section "Customizing" at
  the end of this manual.

  <TD> The new icon will be positioned so that its bottom-left corner is at
  the position where the pointer was when you popped up the menu.

  Icon/Selection ë Renumber ë

  You can renumber single icons or selections. When a selection is
  renumbered, the icons are numbered from top to bottom and from left to
  right.

  <TD> It is not possible to give an icon a number that is equal to or
  higher than the number of icons in the template. If, for instance, if there
  are 10 icons, they are always numbered from 0 to 9. You may enter a higher
  number but TemplEd will decrease it to 9. (In fact, what TemplEd does when
  renumbering is swap the definitions of two icons: the one that you want to
  renumber, and the one carrying the new number.)

  <TD> After renumbering an icon, TemplEd increases the new number by one
  and stores it. You can see this the next time you open the menu. This
  feature comes in handy when you renumber using Alt+Select (see
  "Shortcuts")

  Icon/Selection ë Align ë

  Changes the selected icons so that they are lined up. There is a choice
  of aligning the left-hand sides, right-hand sides, top, bottom, and the
  centres (in either the horizontal or vertical direction).

  The icons can be either moved or resized. When resized, the coordinates
  of the icons stay the same except for the side that must be aligned.

  <TD> As an anchor for aligning, the outer icon is chosen. For horizontal
  aligning this is the leftmost icon, for top aligning the topmost, etc.
  This ensures that if the icons were inside the visible area before the
  aligning, they will remain fully visible afterwards (except for some cases
  when you align the centres).

  Icon/Selection ë Space out ë

  Moves the selected icons so that there is a constant space between the
  icons. You can choose between horizontal and vertical distribution, and
  between setting a fixed space and using the available space between the
  outer icons. For example:

  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 |
     -----        -------        ---         ---

  <TD> Before doing a Space out operation, TemplEd sorts the icons on their
  minimum coordinate. This means that the leftmost (or bottommost) icon
  always remains in place. It also means that if some icons have equal
  minimum X (or Y) coordinates, they may end up in any order.

  <TD> Both the "Align" and the "Space out" operations change the position
  of icons in only one direction. So if you do a horizontal Space out, the Y
  coordinates of the icons remain the same.

  Icon/Selection ë Min. size

  Minimizes the size of icons, keeping their bottomleft corner at the same
  position.

  <TD> It is very complicated to calculate the minimum size correctly,
  especially for icons with outline fonts, 3D borders or multi-line text.
  The procedure used may not always give the best results.

  Icon/Selection ë Center

  Centers the icon (or icon selection) in the window, relative to the
  area that is currently visible.

  Icon/Selection ë Same size

  Sets the size of the selected icons to be equal to the topleft one. The
  bottomleft corner is kept at the same position.

  Work area ë

  Leads to a window in which you can set the dimensions of the window work
  area. The "Minimize" button limits the work area to the maximum
  coordinates that are currently visible. The "Maximize" button sets the
  minimum size equal to the current window size. The "Default" button resets
  all values to those of a standard full-screen window.

  Misc ë Sprite area

  Enables you to choose from which sprite area the sprites in the template
  are read. This can be either the Wimp area or a private area that is
  created when you drop a sprite file on the TemplEd icon.

  <TD> When saving templates, TemplEd always sets the sprite area to 1 (i.e.
  the Wimp area). If your program is using a private sprite area, it will
  have to re-direct the sprite area pointers after it has loaded the
  template.

  Misc ë Tidy icons

  Does two things: (1) check if all icons are within the work area, and
  move them if needed; (2) remove deleted icons from the template
  definition, so that there are no "gaps" in the icon numbering.

  <TD> Normally, when you delete an icon, it is only marked as deleted. The
  numbering of the other icons stays the same. (If, later on, you create an
  icon, it may get the number of a deleted icon.) Also, if you save the
  templates, the deleted icons take up some space (32 bytes per icon), both
  in the file and in the memory of the program that uses the templates. To
  prevent this, you can either use "Tidy icons", or make sure that there are
  no gaps in the numbering by renumbering the existing icons.

10.2 The icon bar menu

  Options...

    Opens a window in which you can set a number of options:
    * Double click starts edit
        When on, TemplEd reacts to double-clicks on icons, window title bar
        or background, by opening an Edit window.
    * Support 'Interface' module
        Provides support for the Interface module, by making the
        appropriate calls for redrawing icons. (The Interface module
        provides a number of enhancements, the most important being
        icon borders with 3D look. Most of these are also present in
        Risc OS 3.)
        <TD> Support is limited to redrawing icons, including selecting and
        deselecting them upon a click. Other features of Interface, such as
        changing pointer shapes and strings for !Help, are not supported.
    * Support 'AEH' module
        Similarly, provides (limited) support for the AEH module.
    * Allow duplicate template names
        If this option is off and a template is added with a name that
        already exists, the old template is deleted. Renaming a template to
        an existing name will also be refused.
    * Hatch user-redrawn templates
        When on, the background of windows of which the "Auto-redraw"
        flag is cleared, will be shown with a cross-hatch pattern.
    * Show icon info
        Enables or disables the Icon info window that shows information
        on the icon that the pointer is currently over.
    * Save icons as unselected
        When on, TemplEd stores all icons as unselected when you save any
        templates. Otherwise, the "selected" state of icons is saved with
        the rest of the data to the file, and when your program uses the
        templates, it will have to make sure that the correct icons are
        selected.
    * Delete icons moved outside
        If you move icons, and drop them outside a template window, they
        will be deleted if this option is on. When off, nothing happens to
        the icons. This option allows for fast deletion of icons.
    * Grid
        Locks the position of icons that are created or modified to
        a grid (as in !Draw). This makes it easier to get icons lined
        up properly. The grid size can be set by clicking on the arrow
        icons. There are two grids:
          - Icon size grid
            Locks all four corners of an icon, so that its size will be a
            multiple of the grid size
          - Icon position grid
            Locks only the bottomleft corner of the icon; this can be handy
            if you want to keep icons lined up, but want to keep their sizes
            unchanged
        Normally, the Icon position grid will be at least as large as the
        Icon size grid.
        <TD> If you are working in a high-resolution screen mode, it is
        advisable to use at least an Icon size grid of 2x4, so that your
        templates look the same in medium-resolution modes (like 12 and 15)
        <TD> TemplEd automatically adjusts the grid size in case of a mode
        change; the grid size must be at least equal to the number of OS
        units per pixel.

    The "Save & Exit" button stores the current settings to a file in
    the application directory, then closes the window. The "Exit" button
    just closes the window.

  Statistics...

    Opens the statistics window, showing the amount of memory that the
    templates will need if you use them in a program. The amounts can be
    shown in decimal or hexadecimal numbers.

    <TD> Note that the statistics window does not change as you modify your
    templates. The figures are re-calculated only when the window is opened
    or when you click on the "Decimal" or "Hex" buttons.

  Custom sprites ë View/Edit

    "Run"s the file with the custom sprites that your templates are using.
    This ususally means that !Paint will load the file.

  Custom sprites ë Re-load

    Reads the sprite file again, e.g. after you have edited it with !Paint.

  Custom sprites ë Reset

    Removes the sprites from memory; the templates will use the sprites from
    the Wimp area.


11. Shortcuts
_____________

* Opening the Icon Edit and Window Edit windows can be done from the menu,
but a faster way is to click on them while pressing a key. Shift+Menu opens
the Icon Edit window. Ctrl+Menu opens the Window Edit window. To edit the
title bar icon, click Shift+Menu on the title bar.

* The Edit windows can also be opened with a double-click with the Select
button. Double-clicks on an icon, on the background of a window, or on the
title bar open the appropriate Edit window. This only works if the
corresponding option is on.

* Inside the Icon Edit and Window Edit windows, pressing the F2, F3 and F4
keys has the same effect as clicking on the Update, Update&Exit and Exit
icons, respectively. The Escape key has the usual function which is exiting
without doing anything. Escape works not only in these two cases, but in all
windows with writable icons, such as the Save, Space Out and Options
windows.

* Many operations on icons can also be done with a control-key:

      Ctrl-A    Select all
      Ctrl-C    Copy selection
      Ctrl-D    Copy icons downward
      Ctrl-E    Edit selection
      Ctrl-J    Open "Align" box
      Ctrl-K    Open "SpaceOut" box
      Ctrl-L    Copy icons to left
      Ctrl-Q    Close window (Ctrl-F2 works, too)
      Ctrl-R    Copy icons to right
      Ctrl-T    Edit title bar
      Ctrl-U    Copy icons upward
      Ctrl-W    Edit window
      Ctrl-X    Delete selection
      Ctrl-Z    Clear selection

(This only works if the window has the input focus, of course)

* Renumbering icons can also be done faster. Click Alt+Select on an icon, and
the icon gets the number that is visible when you open the "Icon ë Renumber"
menu. After the renumbering, this number is increased by one, so you can
number the icons sequentially by clicking on them one by one. A click with
Alt+Adjust does the same, except that the number is decreased after the
renumbering.

* A fast way to delete icons is by moving them outside the template. (This
only works if you have set the "Delete icons moved outside" option on.)


12. "Hidden" features
_____________________

TemplEd has a number of features that may not be immediately visible, but
can come in handy. (That's not counting the bugs ;-)

* It is possible to copy icons to other templates; just move the icons and
drop them into the other template. This makes it easy to use icons from
other templates.

* Extended icon info. When TemplEd starts, the Icon info window is small,
showing only the name of the template and number of the icon that the mouse
is over. If you click on the "toggle size" icon, it becomes full size and
also shows the dimensions of the icon plus the mouse position in window
coordinates. Still more icon info can be gotten from !Help, Acorn's
interactive help application. Open the help window, and move the pointer
over an icon.

* Fine-tuning when moving and resizing icons and windows is possible with
the cursor keys. The up, down, left and right keys move the pointer 1 pixel
(or 4 pixels, if Shift is pressed).

* Pressing Esc during dragging (icon move, resize, etc.) aborts the
operation.

* In the Icon Edit window, clicking Adjust on "Max Size" (the text itself,
not the writable icon) minimizes the contents of the "Max Size" field.

* Closing the Templates window with the Adjust button opens a Filer window
of the parent directory of the file you are editing. Shift+Adjust also opens
the Filer window but does not close the Templates window. (This is, in fact,
standard Acorn practice for editor-like applications.)


13. Customizing
_______________

Apart from setting the options, you can also customize TemplEd's menu of
standard icons. Load the file "Templates" in the application directory into
TemplEd. The template "StdIcons" contains the definitions of the standard
icons. TemplEd loads them at program startup. You can change these
definitions to your liking, but bear the following in mind:

* There are "name" icons that contain the text of the menu entries. They
must be indirected-text icons, with their ESG set to 31.

* The other icons contain the definitions. These MUST have a different
value for the ESG (i.e. 0-30). TemplEd links them to the "name" icon with
the number preceding them. For instance, suppose icons 0 and 3 are "name"
icons. This means that icon 1 and 2 are taken as a group belonging to
icon 0. When you select the text in icon 0 from the "Create icon ë " submenu,
these two icons will be copied to your template window.

For those who like windows with 3D-look, there is an alternative set of
templates and sprites. To make TemplEd use them, rename them to the default
"Templates" and "Sprites", after you have given the standard "2D" files a
different name. (Note: you need Risc OS version 3.10 or later to get the
3D effect.) Alternatively, run the "Use3D" Obey file in the "Extras"
directory; run "Use2D" to switch back to standard templates.


14. Credits
___________

Although the edit-dialogue windows are my own idea, not all features
implemented in TemplEd are. Some have been borrowed from RiscForm (the
version of !FormEd by The Risc Squad), some from Jonathan Marten's excellent
!DrawPlus (notably the Align and Space Out windows).

Martin Ebourne made the hires sprites file (!Sprites22). The MenuUtils
module which TemplEd uses was written by Alex Petrov.

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 R╓jemo, John Tytgat, Julian Wright, and I'm sure I forgot
some others.


15. Copyright notice
____________________

This program is FreeWare. This means that I retain the copyright. You may
freely copy and distribute it, provided that it is complete with all
original files, and that you do not sell it. PD libraries may charge a
nominal fee for the cost of duplication, postage etc. When you use the
program, you do so entirely at your own risk. You may change the program to
suit your own needs. If it's a bug fix, or if you think it's an improvement,
then please send the changes to me at the address below.

The MenuUtils module is ⌐ Alex Petrov (address: Bld. 1, Flat 107 ; Kavkazsky
boulevard, 29 ; Moscow 115541 ; RUSSIA. e-mail: [e-mail])


16. Finally
___________

If you have any questions, bug reports or suggestions for improvements,
you can contact me at the following address:

Lijnslagerstraat 204
NL-5625BP  Eindhoven
The Netherlands

or by e-mail: [e-mail]

Dick Alstein