home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The Datafile PD-CD 4
/
DATAFILE_PDCD4.iso
/
utilities
/
utilst
/
wined
/
!WinEd
/
!Help
< prev
next >
Wrap
Text File
|
1996-03-13
|
67KB
|
1,956 lines
____
| | | |
| | • __ | ___|
| | | | \ |———— / |
\ /\ / | | | | | |
\/ \/ | | | |____ \__/|
A shareware template editor for RISC OS 3.
Author:
Tony Houghton
271 Upper Weston Lane
Southampton
SO19 9HY
United Kingdom
Email: tonyh@tcp.co.uk
WWW: http://www.tcp.co.uk/~tonyh/
This manual describes release 2.34 of WinEd.
CONTENTS
About WinEd............................................................1
Requirements...........................................................1
About shareware........................................................1
Installation and registration..........................................1
Upgrades...............................................................2
Distribution...........................................................2
Disclaimer.............................................................2
Units used.............................................................2
Mode independence......................................................3
WinEd’s dialogue boxes.................................................3
Error boxes............................................................3
Interactive help.......................................................3
Loading and creating templates.........................................3
Keyboard control of the pointer........................................4
Sprite files and sprite areas..........................................4
The icon bar menu......................................................4
The Choices dialogue box...............................................5
Browsers...............................................................6
Mouse operations in browsers...........................................6
The browser menu.......................................................7
Selected window(s) submenu.............................................8
Saving templates.......................................................8
Statistics windows.....................................................8
The browser tool bar...................................................9
Preview windows........................................................9
The preview menu......................................................10
Editable windows......................................................10
Mouse operations in editable windows..................................10
The editable window menu..............................................11
Selected icon(s) submenu..............................................12
The editable window tool pane.........................................13
Edit window dialogue box..............................................13
Button types..........................................................15
The colour picker.....................................................17
The monitor...........................................................17
Creating icons: the Icon picker.......................................18
Work area dialogue box................................................18
Edit icon/title dialogue box..........................................19
Align dialogue box....................................................22
Space out dialogue box................................................23
Resize icons dialogue box.............................................23
Frame dialogue box....................................................24
Hints & tips..........................................................25
Customising WinEd.....................................................27
Bug reports & suggestions.............................................28
Acknowledgements......................................................28
WINED
________________________________________________________________________
About WinEd
———————————
WinEd is a shareware template editor. Its features are aimed at
designing templates for RISC OS 3 with a 3D look, but it can also be
used for 2D templates. The most attractive features of WinEd are:
• Main editing interfaces use dialogue boxes.
• Icons can be dragged between windows, including a customisable
‘Picker’ window containing the most commonly used icons.
• Multiple files can be loaded by one instantiation of WinEd.
• Conventions are based on Acorn’s Style Guide.
• Statistics are available on the size etc of template files.
• Powerful features for positioning icons relative to each other.
• Optional rounding of coordinates in high resolution modes to
ensure low resolution compatibility.
• Optional tool panes and keyboard short cuts enhance convenience.
• Fast loading and saving.
Requirements
————————————
WinEd requires RISC OS 3.1 or later, but will work on 1Mb systems. No
modules are required, except that because it is designed for a 3D look
you should use the NewLook suite supplied by Acorn if you have RISC OS
3.1. This includes the WindowUtils module, without which some 3D
applications may crash.
About shareware
———————————————
WinEd is shareware, not public domain. Shareware means that you are
legally obliged to register by sending a fee to the author if you
decide to continue using the software after an evaluation period.
Registration of WinEd is described below.
Please do not fail to register any shareware you use, not just WinEd.
Your support helps to preserve an excellent way of allowing users to
try before they buy and independent authors to distribute their
software conveniently.
Installation and registration
—————————————————————————————
WinEd can be run from any filing system, but the registration process
requires a writable medium. To install WinEd drag it from the
directory you receive it on to the directory you want it to ‘live’ in.
To ensure your new copy is used in preference to the original open the
application directory with Shift-Double-click and double click the
!Boot file. You only need to do this if you have just made a new copy
and intend to use it without rebooting the computer.
When you first install WinEd, you will most probably have an
unregistered version. This will be made evident by the start-up banner
asking you to register, and the string “*** Unregistered ***” in the
User field of the Info dialogue box. After registration a User file is
Page 1
WINED
________________________________________________________________________
created: the banner will be removed and your name inserted in the User
field.
The first thing you must do to register WinEd is send £10.00 sterling
(cheques payable to A. Houghton) to:
Tony Houghton
271 Upper Weston Lane
Southampton SO19 9HY
UK
Please state your name exactly as you wish it to appear in the User
field, and the version number of WinEd you are currently using. In
return I will send you your personal registration code and the latest
version of WinEd if you have an earlier version. Overseas customers
need not pay extra for postage, but S.A.E’s will be much appreciated.
When you have a registration code run WinEd and click on the Register
button in the registration banner. A sub-program takes your user name
and registration code and uses them to create the User file within
!WinEd.
Upgrades
————————
Your User file will be compatible with all future versions of WinEd.
Its main ftp site on the Internet is ftp.tcp.co.uk/pub/acorn; check my
web site (see title page of this manual) for news of updates. Users
without access can get updates from APDL at 39 Knighton Park Road,
Sydenham, London SE26 5RN. Alternatively you can get upgrades directly
from me at the above address; please state your registration code and
include a preferably padded SAE with a formatted disc (HD or DD
acceptable).
Distribution
————————————
WinEd may be freely distributed provided all the files, including this
and other documentation, are left intact and unaltered, except for any
User file which must be removed. Customised template files must be
replaced with the originals. If you are doing more than giving a copy
to a friend (eg you run a BBS or PD library) please ensure you have the
latest version.
Disclaimer
——————————
I, the author can accept no liability for any loss or damage caused by
installing or using WinEd. I reserve the right to change the
specification of WinEd without notice and upgrade it or not as I see
fit.
Units used
——————————
The units used and referred to throughout are OS units, except where
Page 2
WINED
________________________________________________________________________
stated. If a writable icon expecting a number is left blank, zero is
assumed.
Remember that work area coordinates have the origin at the top left and
anything below this is negative.
Mode independence
—————————————————
WinEd has been designed so that you do not have to design your
templates in low resolution modes to ensure compatibility. This is
done by providing an option to round all coordinates to the nearest 4
OS units (equivalent to one pixel in the lowest resolution desktop
modes), including the dashed outline in drags.
WinEd’s dialogue boxes
——————————————————————
Most of WinEd’s dialogue boxes are static ie a click outside them does
not close them. This slightly improves convenience and consistency.
Action buttons generally close the dialogue box they are in unless
clicked with Adjust instead of Select. Cancel buttons always close the
dialogue box.
Pressing Return in any writable icon has the same effect as clicking
Select on the default action icon. Use the up and down cursor keys or
(Shift-) Tab to move the caret between icons.
When clicked with Select, down ‘bumper’ icons (arrows) decrease values
shown in adjacent fields, up bumpers increase the values. Adjust does
the reverse of this.
Error boxes
———————————
Error boxes are usually used when WinEd encounters a problem such as
lack of memory or missing resources. Where possible, when WinEd is
being used to edit data, it tries to continue after such problems, but
you should save your data as soon as possible. If WinEd can not
continue there will be a Cancel button instead of OK or Continue.
Interactive help
————————————————
WinEd supports interactive help, including its menus; you may find this
helpful at first.
Loading and creating templates
——————————————————————————————
WinEd can be loaded by double clicking it in a directory display or by
double clicking any template file. Naturally the WinEd icon appears on
the icon bar, also a browser (see below) is opened for any template
file that was used to invoke WinEd. Once WinEd is loaded any more
template files can be loaded by double clicking or dragging to WinEd.
The number of files WinEd can load and edit is only limited by memory.
To create a new file click once with Select on the WinEd icon; this
Page 3
WINED
________________________________________________________________________
opens an empty browser (see below).
Files can be merged by dragging one file into a browser containing the
other.
Keyboard control of the pointer
———————————————————————————————
While WinEd is on the icon bar and no other windows have input focus,
each press of one of the cursor keys moves the mouse pointer by one
pixel in the appropriate direction.
Sprite files and sprite areas
—————————————————————————————
In some windows it is necessary to create icons with sprites that
belong to an application instead of the Wimp’s sprite pool. You can
load 'user' sprite files into WinEd by dragging them to its icon.
WinEd only has one sprite pool which it shares between all windows
loaded in it, but it can load sprite files dragged to any of its
windows or its icon bar.
Holding shift while dragging a sprite file to WinEd causes it to be
merged with the Wimp sprite pool and the screen is redrawn.
From version 2.30 onwards, all sprite area fields are saved with the
value 1 (use Wimp sprites) and WinEd makes no distinction between the
Wimp sprite pool and the user sprite pool. RISC OS 3 allows all sprite
area pointers to be set to a user sprite area and it will look for
sprites in the Wimp pool if they are not found in the user's area. It
is up to the target application to change sprite area pointers to its
own sprite area if necessary.
The icon bar menu
—————————————————
Info
----
Moving the pointer right opens the Info dialogue box which contains
information about WinEd including the version and whether there is a
registered user.
Icon picker
-----------
This opens the icon picker immediately above the right hand end of the
icon bar. The icon picker is described in a later section.
Monitor
-------
This opens the monitor window at the top right of the screen. The
monitor is described in a later section.
Choices
-------
Page 4
WINED
________________________________________________________________________
This opens the Choices dialogue box, described later.
Clear sprites
-------------
Clears the user sprite area to save memory.
Quit
----
This removes WinEd and all its files from memory. If data has been
altered without saving you will be presented with a warning dialogue
box.
Click the Discard button to discard data and allow WinEd to quit, or
the Cancel button to keep WinEd and its data. This dialogue box also
appears if the Task Manager asks WinEd to quit without saving data, eg
during a Shutdown.
The Choices dialogue box
————————————————————————
Opened from the icon bar menu, this allows you to configure some of
WinEd’s behaviour. The choices will not take effect until you click OK
or Save, but will then take immediate effect, updating any displayed
windows if necessary. The Save button creates a Choices file within
the !WinEd directory, to read the options from next time WinEd is
loaded. If WinEd can not find a valid Choices file it quietly chooses
suitable defaults.
Automatic monitor
-----------------
If selected the monitor will automatically open and close when editable
or preview windows are opened and closed, as described in the section
about The monitor.
Automatic icon picker
---------------------
This makes the icon picker open and close with editable windows in a
similar way to the monitor.
Browser tool bar
----------------
This causes a tool bar to be displayed along the top of browsers.
Editable window tool pane
-------------------------
This causes a tool pane to be attached to the top left of editable
windows.
Keyboard short cuts
-------------------
If selected, browsers and editable windows will claim input focus and
respond to keyboard short cuts. The short cuts are shown in the menus
if this option is selected.
Page 5
WINED
________________________________________________________________________
Hatch user-drawn windows
------------------------
If selected, a cross hatch pattern will be displayed in any editable
window which needs the task’s help to be redrawn.
Round coordinates
-----------------
This causes all coordinates to be rounded to the nearest 4 OS units as
described in the section on Mode independence.
Editable window tool icons
--------------------------
This causes editable windows to be displayed with all the tools (title
bar, scroll bars etc) to save you having to repeatedly switch them on
and off every time you want to move or scroll the window. A Preview
system is provided to see how your windows will actually look.
Auto-load sprites
-----------------
When a template file is loaded WinEd will load a Sprites or Sprites22
file from the same directory if one exists and this option is set.
Browsers
————————
Browser is the term for a window which displays a list of the
window/dialogue box definitions in a file. Each entry is shown as a
small icon depicting a dialogue box (with no scroll bars) or window
(with scroll bars) next to its template identifier. The windows are
displayed in the order they appear in the file left to right.
The title bar of a browser shows the file name of the templates, with
an asterisk if they have been edited. Closing a browser removes the
templates from memory, unless they have not been saved in which case
you will see a warning dialogue box.
Click Discard to discard the templates and close the browser, Cancel to
keep the browser open or Save to open the save dialogue box. If you
choose the latter the browser will be closed following a successful
save.
If you click Adjust on a browser’s close tool WinEd will attempt to
open the directory the templates were last loaded or saved in, keeping
the browser open if you hold Shift. Iconising a browser (Shift-Select
on the close tool) closes any windows which ‘belong’ to it, thus it can
be used for a quick tidy-up.
Mouse operations in browsers
————————————————————————————
Where ‘work area’ is shown in brackets below it refers to clicking over
a part of the window not covered by an icon. Similarly, ‘(icon)’ means
clicking over an icon; each icon corresponds to a window or dialogue
Page 6
WINED
________________________________________________________________________
box definition. If neither are present it refers to any part of the
window.
Select (icon) Exclusively select icon
Select (work area) Clear selection
Adjust (icon) Toggle selection state of icon without
affecting others
Double-click Select (icon) Open window for editing, or close it if
already open
Double-click Adjust (icon) Open window for preview, or close it if
already open
Drag Select Start dragging rubber box; when complete
all icons within the box are selected
Drag Adjust Start dragging rubber box; all icons
inside will have their selection state
toggled
Menu Open browser menu. If not more than
one icon was previously selected, any
icon under the pointer is selected
instead
The browser menu and the processes of editing and previewing windows
are described below.
The browser menu
————————————————
The Selection and Clear selection entries are greyed out if there is no
selection, and the Selection entry is changed to Window ‘xxxx’ if only
one window is selected.
Create
------
Move the pointer right to a small dialogue box to enter the name
(identifier) of a new window. This must contain at least one
character, and you will be asked for confirmation if you are about to
overwrite any existing windows with the same name.
Selection
---------
Move the pointer right to open the Window/Selection submenu described
below.
Select all
----------
Selects all the windows in a browser.
Clear selection
---------------
Clears the selection.
Save
----
Page 7
WINED
________________________________________________________________________
Move the pointer right to open the Save as dialogue box.
Statistics
----------
Opens a statistics window for the file in the browser. This is
described below.
Selected window(s) submenu
——————————————————————————
If more than one window is selected only the Delete entry can be
selected, the others are greyed out.
Copy
----
Move the pointer right to make a copy of the selected window. This is
similar to creating a new window, described above.
Rename
------
Move the pointer right to enter a new name for the selected window;
again, see the section about creating a new window.
Delete
------
Deletes the selected window(s).
Edit
----
Open the selected window for editing (see the section on Editable
windows below).
Preview
-------
Open the selected window for previewing (see the section on Preview
windows below).
Saving templates
————————————————
The Save as dialogue box is opened from the browser menu. Drag the
file icon or enter a path name in the writable icon and click Save. If
one or more windows are selected the Selection button will be
selectable. Select this if you only want to save the selected
templates. Note that when you save a selection, the fonts for the
whole file are saved with it. To remove superfluous fonts load the
file back into WinEd.
Statistics windows
——————————————————
The top row shows the column headings. The Identifier column shows the
name of the window, Icons shows how many icons the window contains.
Buffer shows the size of the buffer needed to load the window block
Page 8
WINED
________________________________________________________________________
with Wimp_LoadTemplate; similarly Indirected shows the size of buffer
needed to hold the icons’ indirected data. Note that the Buffer size
is the size that will be requested by Wimp_LoadTemplate and includes a
temporary buffer for indirected data.
Each row in the main section of the window shows the data described
above for each window definition in the file.
The penultimate row shows the total of each column for all the windows
in the file.
The bottom row shows, from left to right, the number of windows in the
file, the number of different font definitions used, and the size in
bytes of the file as stored on disc. Note the latter is generally
smaller than the total size needed to load the templates, this is
because only the parts of indirected strings which contain data are
stored in the file, but the application using the templates needs to
reserve space for the maximum possible length of the string.
The browser tool bar
————————————————————
This is a row of tool icons which can optionally be displayed along the
top of browser windows. The tools provide short cuts for the functions
described above, available from the browser menu. They are (from left
to right):
Create (opens writable submenu)
Select all
Clear selection
Save
Copy (opens writable submenu)
Rename (opens writable submenu)
Delete
Statistics
Edit
Preview
Preview windows
———————————————
Since editable windows have their attributes altered to make them
easier to edit, it is necessary to have a system of viewing exactly how
your finished windows will look and behave. This is what preview
windows are for. They can be opened by double clicking Adjust on a
window in a browser or by choosing Preview from the browser menu.
Previews can also be used to fine tune the size and appearance of
windows in ways which are not practical or possible with editable
windows.
It is possible to drag a preview window by dragging an empty part (ie
not covered by an icon) of its work area while pressing Ctrl. Using
Select has the same effect as dragging the title bar (move window) and
Page 9
WINED
________________________________________________________________________
Adjust is the same as dragging the adjust size tool (resize window).
It may also be necessary to see how windows fit with each other (eg for
panes) without superfluous tools.
Once you are satisfied with the size and position of a preview window
remember to store the position and size with the preview menu (see
below), otherwise they will be reset next time you open the window.
The preview menu
————————————————
Close
-----
Closes the window (in case there is no close tool).
Store position
-------------
Stores the current on-screen size and position of the window in the
template definition.
Store icon states
-----------------
Stores the selection states of the window’s icons in the template
definition. However, it is better practice to leave any selection to
the application which finally uses the templates.
Editable windows
————————————————
The changes you make to editable windows directly affect the template
data, including moving and resizing. Editable windows are optionally
always shown with all tools (title bar, scroll bars etc) to make
editing easier. All icons are given the same button type to make them
selectable. To see how your windows will really look use the preview
system.
Many of the following sections refer to dialogue boxes; each of these
is described in its own section.
Mouse operations in editable windows
————————————————————————————————————
These are summarised below with numbered notes. Note also that all
mouse operations in editable windows can be modified in the same way
with the Ctrl key. This has the effect of making the operation act as
if over an empty bit of work area instead of over an icon. All
irreversible drags (ie excepting rubber boxes) can be cancelled by
pressing Esc when you release the mouse.
Select (work area) Clear selection
Select (non-selected icon) Exclusively select icon
Menu Open editable window menu. If not more
than one icon was previously selected,
Page 10
WINED
________________________________________________________________________
any icon under the pointer is selected
instead
Adjust (non-selected icon) Select icon without affecting others
Adjust (selected icon) Deselect icon
Drag Select (work area) Drag a rubber box to select icons ¹
Drag Select (icon) Move (local)/Copy (export) icon ²
Drag Adjust (work area) Drag a rubber box to invert the
selection state of icons ¹
Drag Adjust (icon) Resize icon, moving the edge nearest the
pointer ³
Drag Shift-Adjust (icon) Resize icon, moving the corner nearest
the pointer ³
Drag Shift-Select (icon) Copy (local)/Move (export) icon ²
Drag Shift-Adjust (icon) Resize icon, moving only the edge
nearest
the pointer ³
Drag Shift-Ctrl-Select Move window as if dragging title bar
Drag Shift-Ctrl-Adjust Resize window as if dragging adjust size
tool
Double click Select (work area) Edit window (open dialogue) †
Double click Select (icon) Edit icon " †
Double click Adjust (work area) Edit work area " †
Double click Adjust (icon) Minimise icon ‡
Double ⇧-Select (work area) Edit window title icon " †
¹ This is similar to the same type of drag in browsers.
² This follows the conventions of Drag & Drop as outlined in the
Style Guide. The unmodified drag and Shift-modified drag have the
opposite effect depending on whether the drag is local (finishing in
the same window as it started) or an export (to a different window).
In the local case an unmodified drag moves the icon and a Shift-drag
copies it, in the export case an unmodified drag copies the icon, a
Shift-drag effectively moves the icon by making a copy in the
destination window and deleting the original. If the pointer leaves
the window during a drag the window is scrolled if possible; if the
drag turns out to be an export the scroll bars are reset to their
original positions. The Shift key is polled at the start of the drag,
not the end.
³ Resize drags are limited by the window’s visible area.
† These operations open the relevant dialogue box.
‡ This minimises both the width and height of an icon;
minimisation makes the icon just large enough to display its contents
and is described in more detail in the section about the Resize icons
dialogue box.
The editable window menu
————————————————————————
The Selection and Clear selection entries are greyed out if there is no
selection, and the Selection entry is changed to Icon nnn if only one
icon is selected.
Selection
Page 11
WINED
________________________________________________________________________
--------
Move the pointer right to open the Selection submenu.
Select all
----------
Selects all the icons in the window.
Clear selection
---------------
Deselects all the icons.
Work area...
------------
Opens the Work area dialogue box.
Edit window...
--------------
Opens the Edit window dialogue box.
Edit title...
-------------
Opens the Edit icon dialogue box for the title icon.
Close window
------------
Closes the window.
Selected icon(s) submenu
————————————————————————
If only one icon is selected, the title bar of the menu shows Icon and
the Align... option is greyed out. The Edit... option is greyed out
and the title bar shows Selection for multiple selections.
Delete
------
Deletes the selected icon(s). Deleted icons are entirely removed from
the template; any icons with higher numbers are renumbered to ‘fill the
gap’.
Renumber nn
-----------
Renumbers the selection, starting from the number shown. A different
number can be entered by moving the pointer right. Groups of icons can
be renumbered as well as single icons. When renumbering a group they
are kept in the same order but are made consecutive, starting from the
new number. After renumbering the number in the menu and dialogue box
is updated to the number following the new number of the last
renumbered icon.
Edit...
-------
Opens the Edit icon dialogue box, a long winded alternative to
Page 12
WINED
________________________________________________________________________
double-clicking.
Align...
--------
Opens the Align icons dialogue box.
Space out...
------------
Opens the Space out dialogue box.
Resize...
---------
Opens the Resize icons dialogue box.
Frame...
--------
Opens the Frame icons dialogue box.
The editable window tool pane
—————————————————————————————
This is optionally attached to the top-left edge of editable windows
and provides short cuts for the menu functions described above. The
tools are (left to right, top to bottom):
Select all
Clear selection
Work area...
Edit window...
Edit title...
Delete
Renumber (Select opens writable submenu, Adjust renumbers with value
currently shown in menu)
Align...
Space out...
Resize...
Frame...
Edit window dialogue box
————————————————————————
This can be opened from an editable window menu or by double clicking
Select in the window’s work area. It is for editing various attributes
of a window. The identifier of the window being edited is shown in the
title bar.
Most monitors will not be capable of displaying the dialogue box at
full height, but the tall, narrow design seems to be the most
convenient. If necessary the dialogue box can be redesigned by the
user (see the section on Customising WinEd).
Tools
-----
These option icons determine which of the named tools will appear
Page 13
WINED
________________________________________________________________________
around the border of the window.
Btn type
--------
This shows the button type of the window’s work area. The button icon
to the right of this field pops up the button type menu when clicked.
Button types are described later.
Update
------
Updates the template data with the settings in the dialogue box.
The following option icons affect the state of the window’s flags.
Each explanation refers to when the flag is set.
Movable
-------
The window can be dragged by its title bar.
Auto redraw
-----------
The window can be entirely redrawn by the Wimp, the application does
not need code to redraw it.
Pane
----
The window is a pane. This makes the title bar of the window behind
(parent) change colour when the pane gains input focus.
Force to back
-------------
No windows can be opened behind this one; it becomes a backdrop.
Hot keys
--------
Keypress events will be passed to the application without the window
having input focus. Note that the event data does not necessarily
indicate the window which claimed the event in this case.
Allow off screen
----------------
The window can be opened off screen; usually (when this flag is
cleared) the Wimp forces the window entirely on screen when first
opened and after mode changes.
Keep on screen
--------------
The window cannot be dragged off screen.
Ignore right extent
-------------------
Ignore bottom extent
Page 14
WINED
________________________________________________________________________
--------------------
I am not sure what these are for; the only noticeable difference is
that the pointer can move outside the Adjust tool when resizing.
Scroll events
-------------
If either of the radios is set the window receives scroll events when
the scroll arrows are clicked. Debounced means the mouse button has to
be released and clicked again to reproduce an event, auto repeat means
events are received at the same rate as the keyboard auto repeat is
set. Click Adjust on whichever is currently selected to deselect both
and ignore scroll events.
The following items are for editing the window’s colours. Each icon
(from left to right) is: colour name, abbreviated to its initials to
save space in the dialogue box; a display of the current colour; bumper
arrows for changing the colour by one step at a time; a pop-up menu
button for choosing the colour from WinEd’s colour picker (see below).
TF Title bar Foreground.
TB Title bar Background.
WF Work area Foreground.
WB Work area Background.
SO Scroll bar Outer.
SI Scroll bar Inner.
IF Input focus (the colour the title bar changes
to when the window has input focus).
Default
-------
Sets all the colours to their recommended default values. This button
doesn’t close the dialogue box.
GCOL colours
------------
If set the above colours are taken to be GCOL values. This was
originally intended for 256 colour modes and should not really be used.
WinEd only supports colours in the usual range of 0-15 (and 255/-1 for
transparent).
Button types
————————————
Button types for icons and work areas are chosen from a menu which can
be popped up from the editing dialogue boxes. Note that in all cases a
click with Menu causes an event with a button state of 2 (Menu button)
no matter what the button type of the icon/work area is.
0 Never
-------
All clicks are ignored except Menu.
1 Continuous
Page 15
WINED
________________________________________________________________________
------------
The task is continually notified (with click events) while the pointer
is over the icon/work area.
2 Auto repeat
-------------
A click notifies the task; if the mouse button is held the event is
repeated at the rate of the keyboard auto repeat setting.
3 Click
-------
A click notifies the task without auto repeat.
4 Release
---------
Releasing the mouse button causes a click event.
5 Double click
--------------
A double click notifies the task as if it was a single click.
6 Click/Drag
------------
As 3, but a drag causes an additional event with the button state
multiplied by 16.
7 Release/Drag
--------------
As 4, but can also be dragged (returns button state * 16).
8 Double/Drag
-------------
As 5, but can also be dragged (returns button state * 16).
9 Menu
------
For work areas this has the same effect as 3. For icons, moving the
pointer over the icon selects it, moving the pointer away deselects it.
A click notifies the task.
10 Double/Click/Drag
--------------------
A click returns the button state * 256.
A drag returns the button state * 16.
A double click returns the button state * 1.
11 Radio
--------
A click returns the button state * 1. If over an icon the icon is
selected.
A drag returns the button state * 16.
Page 16
WINED
________________________________________________________________________
12 (Reserved)
-------------
13 (Reserved)
-------------
Use is undefined.
14 Writable/Drag
----------------
As 15 but can also be dragged.
Not applicable to work areas.
15 Writable
-----------
A click causes the window to gain input focus. If over an icon the
caret is placed in the icon.
The colour picker
—————————————————
This should not be confused with the RISC OS colour picker introduced
with RISC OS 3.5. WinEd’s colour picker is for picking Wimp colours
and transparent where allowed.
The colour picker should be treated as a menu rather than a dialogue
box; the only reason a dialogue box is used is because it is a more
convenient shape. Clicking on a colour or the Transparent button
immediately updates the field, and closes the colour picker unless
Adjust is used.
The monitor
———————————
The monitor always opens at the top right of the screen. When first
opened only the top two fields are visible, it can be resized to show
dimensions.
The monitor shows the following information about any window/icon under
the pointer, provided it is in a template loaded in WinEd.
Window
------
The identifier of the window under the pointer. A trailing * means it
is an editable window, otherwise it is a preview window.
Icon
----
The number of the icon under the pointer, or “Work area”.
Position
-------
The work area coordinates of each edge of the icon is shown in its
relative position to the Position label.
Size
Page 17
WINED
________________________________________________________________________
----
The size of the icon, shown as <width> x <height>.
If the pointer is over an empty bit of work area instead of an icon,
the dimensions refer to the visible portion of the work area. This
information is generally the most useful, it can be used to accurately
position icons near the visible edge of a window.
The monitor can be opened from the icon bar menu and closed with its
close icon as a manual override, but it also opens automatically (this
is optional) when any editable or preview windows are opened and closes
when no editable or preview windows are open.
Creating icons: the Icon picker
———————————————————————————————
The icon picker is a convenient alternative to creating icons from a
menu. You simply drag one or more icons from the picker to where you
want them in an editable window. It behaves rather like an editable
window, but most of the functions are suppressed. The only action
which can be carried out, apart from making selections, is to export
icons from it to other editable windows.
The icon picker always opens immediately above the right end of the
icon bar. Like the monitor it can be opened from the icon bar menu and
closed with its close icon as a manual override, but it also opens
automatically when any editable or preview windows are opened and
closes when no editable or preview windows are open.
The icon picker contains examples of most of the common types of icon,
but it can be customised. See the section on Customising WinEd.
Work area dialogue box
——————————————————————
This is for editing the size of a window’s work area, opened from an
editable window menu or by double-clicking Adjust in a window’s work
area. The identifier of the window being edited is shown in the title
bar.
Work area
---------
The work area coordinate field icons are arranged in a formation which
indicates which icon refers to which edge. New coordinates can be
typed in or changed with the bumper arrows.
Keep origin
-----------
This has a similar effect to the Minimise button (below), but the
origin (X0 & Y1) coordinates are set to zero.
Minimise
--------
This sets the values in the work area coordinate fields to the work
Page 18
WINED
________________________________________________________________________
area coordinates of the portion of the window currently visible. It is
not recommended that the origin (X0 & Y1) coordinates are set to any
value other than zero, hence the Keep origin button is provided.
Neither the Keep origin or Minimise buttons close the dialogue box.
Minimum size
------------
These icons set the minimum size (both values are positive) the window
can be dragged to with the Adjust size tool. Zero values mean the size
will be determined by the size of the title bar and window tools. The
Maximise button sets the values to the current size of the window
(without closing the dialogue box).
Update
------
Updates the template data with the settings in the dialogue box.
Edit icon/title dialogue box
————————————————————————————
This is opened from an editable window menu or by double clicking
Shift-Select over an editable window’s work area. The number of the
icon being edited or the word Title is shown in the dialogue box’s
title bar.
Like the window editing dialogue box, the shape and size of this window
may not suit some users, but it can be customised.
To edit an icon double click it with Select, to edit a title use the
editable window menu or double click Shift-Select over the work area.
Some of the icons are greyed out depending on the state of others (eg
the Validation field if not indirected) or if they do not apply to
title icons (eg button type, colours) and a title is being edited.
Txt/sprt
--------
If the icon contains a text or sprite, enter the text or sprite name
here.
Text
----
Sprite
These flags determine whether the icon contains text and/or a sprite.
Indirected
----------
If set the icon is indirected. It is set automatically if the text
becomes longer than 12 characters.
Validation
---------
Page 19
WINED
________________________________________________________________________
You can enter a validation string here for indirected text icons.
Max text length
---------------
Enter the maximum allowed length (including terminator) of the text for
indirected text icons. This can be set to the length of the string in
the Txt/sprt field by clicking the Minimise button (this doesn’t close
the dialogue box).
Btn type
--------
As in the Edit window dialogue box.
Don’t resize
------------
Update
------
These both update the template data with settings from the dialogue
box. Update also resizes the icon if it is currently too small to
display its data (see Resize icons dialogue box).
The following icons affect the icon flags. Each description refers to
the flag being set.
Border
------
The icon has a border.
H centre
--------
V centre
--------
R align
-------
These affect the alignment of the icon, horizontally centred,
vertically centred and right aligned respectively. Right alignment
overrides horizontal centering.
Filled
------
The icon’s background is filled in with its background colour.
Needs help
----------
If the icon is deleted etc the part of the window it occupies will be
redrawn.
Allow adjust
------------
If the icon is part of an Exclusive Selection Group it can be selected
without deselecting its fellows by clicking with Adjust.
Page 20
WINED
________________________________________________________________________
Half size
---------
If the icon contains a sprite it is displayed at half size.
Selected
--------
Shaded
------
Deleted
-------
These are only provided for completeness, their actions should only
really be carried out by an application using the template. Icons are
displayed as if these flags are clear in editable windows.
ESG
---
The ESG (Exclusive Selection Group) can be set to any value from 0 to
31 by typing or using the bumper arrows. Out of range values are
changed to zero.
Icons grouped with the same non-zero ESG can usually only be selected
one at a time, selecting one deselects any others.
Foreground colour
-----------------
The colour used to draw the icon’s text, and its border if not 3D.
Background colour
-----------------
The colour used to fill the icon if filled.
Editing colours is described under Edit window dialogue box.
If the icon has an outline font the values for the colour fields are
read from the L command in the validation string, if any.
Outline font
------------
If set the icon uses the outline font shown in the field below; fonts
can be chosen from a menu by clicking the menu button. The height can
be entered in points (decimals are allowed). The Aspect ratio is the
ratio of width to height expressed as a percentage.
Outline fonts do not seem to work in icons with validation strings
containing the L command.
Validate
--------
Font handles overwrite the colour fields in icon flags, therefore the
colour data is held in an F command in the validation string. The
Validate button reads the colours from the fields in the dialogue box
and ensures the validation string contains the correct L command,
Page 21
WINED
________________________________________________________________________
forcing the indirected flag on if necessary.
Align dialogue box
——————————————————
This is opened from an editable window menu tree. It is for aligning
groups of icons with each other. The top group of radio icons
determines along which edge the icons will be aligned.
Left
----
The icons will all share the same left (minimum x) coordinate.
H centre
--------
The icons will be arranged so that half their width is each side of a
notional vertical mid-line. This mid-line is calculated from the
left-most or right-most mid-point of all the icons, depending on
whether the Move left or Move right icon is selected.
Right
-----
The icons will all share the same right (maximum x) coordinate.
Top
---
The icons will all share the same top (maximum y) coordinate.
V centre
--------
The icons will be arranged so that half their height is each side of a
notional horizontal mid-line. This mid-line is calculated from the
topmost or bottom-most mid-point of all the icons, depending on whether
the Move down or Move up icon is selected.
Bottom
------
The icons will all share the same bottom (minimum y) coordinate.
Group box & label
-----------------
This is only applicable if exactly two icons are selected in the
editable window and the lower-numbered of them has a border and no text
and the other has text and no border. The icons will be aligned so
that the label’s left edge 32 OS units to the right of the left edge of
the group box and its bottom edge is 24 OS units below the top of the
group box (ideal for labels 44 OS units high).
Move
----
Resize
------
Icons can either be moved or resized to achieve alignment. If Move is
Page 22
WINED
________________________________________________________________________
chosen, icons are moved without changing their size. If Resize is
chosen, only the edge that has to be aligned is moved, thus resizing
the icon; icons will not be allowed to become too small to be selected.
Move left/down/label
--------------------
Move right/up/box
-----------------
These determine which way the icons will be moved or resized. For
instance if one of the horizontal alignments is selected above and Move
left is selected all the icons will be aligned with the originally
left-most icon. In the special case of Group box & label these options
determine whether the label or the box is moved.
Space out dialogue box
——————————————————————
Opened from an editable window menu tree, the Space out dialogue box
can either be used to space a group of icons out from each other or a
single icon from the edge of the visible area.
The icons are sorted into order depending on their horizontal or
vertical positions and spaced out from each other by the number of OS
units entered in the Gap icon. The direction radio icons determine
which icon is used as the ‘anchor’ eg if you choose From left the
left-most icon stays still and all the others are spaced out to its
right.
If only a single icon is selected it is spaced out from the edge of the
visible area corresponding to the direction radio icons.
Resize icons dialogue box
—————————————————————————
This dialogue box is for changing the size of icons, either making a
group all the same size, making a single icon or group just large
enough to display its data, or a single icon a specified size. The
resizing is carried out on the right and top edges, leaving the bottom
left corner fixed.
Minimise
--------
These action buttons change the width and/or height of the selected
icon(s), making it just large enough to display its data, using fairly
intelligent rules.
The size needed for text (taking outline fonts into account) is first
calculated, adding a few pixels to each side to satisfy Style Guide
conventions. Then the size needed for any sprite is calculated if
possible. These two sizes are combined, taking into account the icon’s
alignment flags. If there is a border, sufficient pixels are added,
depending on the type of border. If the icon still has a zero size it
is made just large enough to click with the mouse.
Page 23
WINED
________________________________________________________________________
Icons with ‘L’ validation commands can now also be minimised fairly
sensibly. The program ensures that the current width is sufficient to
display the longest word, then makes the icon just the right size to
preserve the current format of the text. This does not take outline
fonts into account; they do not work with the L command in RISC OS 3.1
anyway.
Versions 2.12 onwards ensure that icons that use the system font are
also large enough for the current RISC PC Desktop font. If the Desktop
font is the System font or you are using RISC OS 3.1 Homerton.Medium
(12pt) is used. Note that this does not apply to L validation, but it
is unlikely that an outline font will take more room than the System
font for long strings.
Make same size
--------------
This only applies to multiple selections. All the icons can be set to
the same width or height, either taking on the width of the narrowest
or the widest or the height of the tallest or shortest.
X & Y
-----
In the case of a single selection a new width (X) and/or height (Y) can
be typed into the writable icons; press Return or click Resize to make
the change.
Frame dialogue box
——————————————————
This is for placing a frame around the selected icons. The frame can
consist of the window’s visible area or an empty bordered icon (group
box) with a lower number than any of the selected icons.
Gap
---
Enter the minimum gap (OS units) to leave between the frame and any
icons inside it. This varies depending on whether the frame is the
window’s visible area (8-16 looks best) or an icon with a 3D border
(usually R4 validation, 20 or more looks better).
Visible area
------------
If selected the frame is made by resizing the window’s visible area to
fit the selection. The window’s work area must be large enough to
accommodate it.
Icon
----
If selected the frame is made by moving and resizing the icon specified
in the adjacent writable field to make a group box. It must satisfy
the requirements outlined above.
Allow for label
Page 24
WINED
________________________________________________________________________
---------------
Group boxes often have a label at the top. If this option is selected
an extra gap (read from the writable icon, the default is 24 OS units)
is left between the top of the frame and the topmost selected icon to
make room for a text label.
Top, Left, Right, Bottom
------------------------
Only the frame’s edges indicated by which of these icons are selected
are moved (unless the frame would become too small or have negative
size). This is useful because frames are often initially placed in
relation to objects outside them and resized when their contents have
been entered.
Hints & tips
————————————
Size of dialogue boxes
----------------------
When designing dialogue boxes and non-scrollable windows, try to make
sure they will fit on screen in as many modes as possible. Mode 22
support (768 * 576 OS units) is not strictly necessary, but you should
at least fit your windows on a Mode 27 screen (1280 * 960 OS units).
The Style Guide recommends a maximum of 800 * 600 OS units for dialogue
boxes.
Positioning icons
-----------------
Icons with similar functions should be the same size as each other and
aligned. When aligning icons, some of which have double borders (eg R6
validation), align with the inner border (use the centre alignment
options). If a dialogue box has several groups of icons (eg two or
more groups of radio icons with two or more different ESG’s) place
group boxes around them.
Place action icons, particularly the default action and Cancel buttons
aligned up the side or preferably along the bottom of dialogue boxes.
Position the default action button at the bottom right.
Your dialogue boxes will look more attractive the more you space out
icons, up to a point. The larger the dialogue box, the more space you
should leave. The Style Guide suggests a gap of at least 8 OS units
between icons, but 16 or more generally looks far better.
Note that WinEd’s window and icon editing dialogue boxes are not spaced
out very much, in this case it was considered more important to make
them as small as possible. It is also unconventional to have scrolling
dialogue boxes unless they are a pane with the default action and
Cancel buttons in the parent window so they are also visible. Panes
were used in WinEd 1.00, but were too restrictive.
Writable icons
--------------
Page 25
WINED
________________________________________________________________________
The Style Guide is a bit contradictory on the subject of validation
strings for writable icons; it says the string should be
Ktar;Pptr_write, followed by any necessary ‘A’ command, but also says
that pressing Return in any icon should act as a click on the default
action button. The above validation string causes Return to move the
caret to the next writable icon and only causes key press events with a
code of 13 (Return) when it is pressed in the last writable icon.
You would expect that you could arrange for your application to receive
all Return key events by using Kta instead of Ktar, but it isn’t that
simple. There is an OS ‘feature’ (in RISC OS 3.1 at least) which
causes the presence of ‘t’ or ‘a’ in validation commands to act as if
‘r’ is also present.
One fix is to use Ktan and receive all key events, but then you should
strictly filter out keys trapped by your application before passing
them on with Wimp_ProcessKey. However, passing on all keys should not
do any harm.
In its own icons WinEd does away with the ‘K’ validation command
altogether and handles the up and down cursor keys and (Shift-) Tab
with its own code. This way it can also confine the caret to icons in
the same ESG in RISC OS 3.1 as well as 3.5.
In RISC OS 3.1 the ‘A’ validation command must be the last command in
the string or subsequent commands will not work. This appears to have
been fixed in RISC OS 3.6, but I am not sure about 3.5.
Outline fonts
-------------
Outline fonts in icons should generally be avoided. Apart from the
latest versions of RISC OS now being able to automatically use outline
fonts in all icons there are a couple of bugs.
In RISC OS 3.1 using an outline font in the title bar of a window
causes a terrible mess if a customised title bar (eg NewLook’s 3D one)
is used.
In RISC OS 3.5 using an outline font in slabbing icons (R5 and R6
validation) causes the default desktop font to be reset or disappear or
something.
In RISC OS 3.1 at least, outline fonts seem to be incompatible with ‘L’
validation commands.
Modifying other people’s templates
----------------------------------
Be careful when modifying other people’s templates; always make sure
you have a backup of the original file. Some programs may object to
changes in their template files eg adding outline fonts, changing the
order of windows in the file, and increasing the amount of indirected
data. Never renumber any icons.
Page 26
WINED
________________________________________________________________________
Deleting icons
--------------
Unlike many template editors, when deleting an icon in WinEd its
definition is entirely removed from the template, subsequent icons are
renumbered to ‘fill the gap’.
The Delete flag is best avoided, having deleted icons in your templates
can cause confusion when using other template editors.
Customising WinEd
—————————————————
As well as the Choices dialogue box WinEd can be customised by editing
its own template file; this is the file called ‘Templates’ within the
!WinEd directory.
WinEd can not handle outline fonts in its own template file, but
changing the order of windows and the amount of indirected data is not
a problem.
Some windows you may wish to customise are:
Icon picker
-----------
You can put any icons you want in here (but no outline fonts),
depending on which icons you like to create most often. Its initial
position depends on its template.
Monitor
-------
The monitor’s initial position depends on its template.
Edit window dialogue box
------------------------
Edit icon dialogue box
----------------------
The shape, size and initial positions of these dialogue boxes may be
inconvenient to you so you may wish to rearrange the icons. Do not
renumber or delete any icons; if you want to get rid of any
non-functional icons such as group boxes and labels, temporarily
enlarge the work area and move them out of the way.
Tool panes
----------
You can customise these by editing the WinTools and BrowTools templates
and/or the Sprites and Sprites22 files. Note that you will have to
disable the Editable window tool icons option to avoid inadvertently
resizing the current browser tool bar. You can make these panes any
size you like, within reason. If you design some that you think are
better than mine, which are perhaps a little small, please let me know.
Many of the default values shown in writable icons etc in the dialogue
Page 27
WINED
________________________________________________________________________
boxes are determined by the values in WinEd’s templates.
If you alter WinEd’s templates be sure to back up the original file;
WinEd must be distributed with this Templates file.
Bug reports & suggestions
—————————————————————————
I hope that you will find WinEd to be reliable; I would not release it
with known bugs. However, no application is entirely bug free and this
is still a sufficiently early version of WinEd to be considered beta,
so you are advised to keep backups and save your work regularly.
Bug reports will be welcome from all users, even if you have not
registered (yet). Suggestions will be more welcome from registered
users; please do not say things like, “I’ll only register if you add
such and such,” if a feature is really worth adding I’ll add it.
If you do find a bug please do your best to inform me of the exact
circumstances that cause it, ideally sending template files on disc or
by email if they seem to be triggering a problem. Where possible I
will personally send you a corrected upgrade if the bug is serious and
a corrected version is not already in circulation.
Acknowledgements
————————————————
WinEd was written in C (compiled by Acorn C Release 5) with extensive
use of DeskLib. DeskLib is a set of freeware C libraries written by
Jason Williams and many others. All C programmers should consider this
an essential replacement for RISC_OSLib.
The text editor used was !Zap, an excellent PD program written by
Dominic Symes with extensions by several other skilled programmers.
The templates were initially created with TemplEd, a PD template
editor. I consider this to be WinEd’s main rival and I have aimed to
improve on it in every aspect.
I would like to thank David Holden of APDL for his advice from one
shareware author to another and for some useful suggestions about WinEd.
Page 28