<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>WinEd</title>
<link rel="stylesheet" type="text/css" href="../Styles">
</head>

<body>
<div id="head"><div id="head-liner">
<div class="title-flex"><h1>WinEd</h1>
<div class="title-side">
<div class="version">Version 3.27</div>
<div class="date">27 April 2024</div>
</div></div>
<div class="strapline">A template editor for RISC&nbsp;OS</div>
<div class="credit">&copy; Tony&nbsp;Houghton,&nbsp;1995; Adam&nbsp;Richardson,&nbsp;2007; Stephen&nbsp;Fryatt,&nbsp;2020</div>
</div></div>

<div id="body"><div id="body-liner">

<h2>Contents</h2>


<ul class="contents-list">
<li><a href="#about">1. About <cite>WinEd</cite></a></li>
<li><a href="#requirements">2. Requirements</a></li>
<li><a href="#licence">3. Conditions of use and distribution</a></li>
<li><a href="#install">4. Installation</a></li>
<li><a href="#disclaimer">5. Disclaimer</a></li>
<li><a href="#units">6. Units used</a></li>
<li><a href="#mode">7. Mode independence</a></li>
<li><a href="#dialogue">8. <cite>WinEd</cite>&rsquo;s dialogue boxes</a></li>
<li><a href="#error">9. Error handling</a></li>
<li><a href="#help">10. Interactive help</a></li>
<li><a href="#loading">11. Loading and creating templates</a></li>
<li><a href="#keyboard">12. Keyboard control of the pointer</a></li>
<li><a href="#sprite">13. Sprite files and sprite areas</a></li>
<li><a href="#iconbar">14. The iconbar menu</a></li>
<li><a href="#choices">15. The Choices dialogue box</a></li>
<li><a href="#browsers">16. Browser windows</a></li>
<li><a href="#mouse">17. Mouse operations in <span class="window">Browser</span> windows</a></li>
<li><a href="#browsermenu">18. The <span class="window">Browser</span> menu</a></li>
<li><a href="#save">19. Saving templates</a></li>
<li><a href="#stats">20. Statistics windows</a></li>
<li><a href="#browsertool">21. The <span class="window">Browser</span> tool bar</a></li>
<li><a href="#export">22. Exporting icon names</a></li>
<li><a href="#preview">23. Preview windows</a></li>
<li><a href="#previewmenu">24. The preview menu</a></li>
<li><a href="#edit">25. Editable windows</a></li>
<li><a href="#mouseedit">26. Mouse operations in editable windows</a></li>
<li><a href="#select">27. Selected icon(s) submenu</a></li>
<li><a href="#edittool">28. The editable window tool bar</a></li>
<li><a href="#editwindow">29. Edit window dialogue box</a></li>
<li><a href="#goto">30. Goto icon menu option</a></li>
<li><a href="#monitor">31. The monitor</a></li>
<li><a href="#creatingicons">32. Creating icons: the Icon picker</a></li>
<li><a href="#workarea">33. Work area dialogue box</a></li>
<li><a href="#visiblearea">34. Visible area dialogue box</a></li>
<li><a href="#editicon">35. Edit icon/title dialogue box</a></li>
<li><a href="#editicons">36. Edit multiple icons dialogue box</a></li>
<li><a href="#align">37. Align dialogue box</a></li>
<li><a href="#space">38. Space out dialogue box</a></li>
<li><a href="#resize">39. Resize icons dialogue box</a></li>
<li><a href="#coords">40. Coordinates dialogue box</a></li>
<li><a href="#frame">41. Frame dialogue box</a></li>
<li><a href="#hints">42. Hints &amp; tips</a></li>
<li><a href="#custom">43. Customising <cite>WinEd</cite></a></li>
<li><a href="#versions">44. Version history</a></li>
<li><a href="#bug">45. Bug reports &amp; suggestions</a></li>
<li><a href="#acknowledgements">46. Acknowledgements</a></li>
</ul>

<h2 id="about">1. About <cite>WinEd</cite></h2>


<p><cite>WinEd</cite> is a template editor. Its most attractive features are:</p>

<ul>
<li>Main editing interfaces use dialogue boxes.</li>
<li>Icons can be dragged between windows, including a customisable &lsquo;Picker&rsquo; window containing the most commonly used icons.</li>
<li>Multiple files can be loaded by one instantiation of <cite>WinEd</cite>.</li>
<li>Conventions are based on Acorn&rsquo;s <cite>Style Guide</cite>.</li>
<li>Statistics are available on the size etc of template files.</li>
<li>Powerful features for positioning icons relative to each other.</li>
<li>Optional rounding of coordinates in high resolution modes to ensure low resolution compatibility.</li>
<li>Optional tool panes and keyboard short cuts enhance convenience.</li>
<li>Fast loading and saving.</li>
</ul>

<p><cite>WinEd</cite> was originally written by Tony Houghton, and his final release was <a href="http://www.snowstone.org.uk/riscos/realh/index.html#wined">version 2.87</a>. Up to and including the release of version 3.22a, <cite>WinEd</cite> was developed by <a href="http://www.snowstone.org.uk/riscos/" class="external">Adam Richardson</a>. Since then, some work to allow the code to be built for modern systems has been done by <a href="http://www.stevefryatt.org.uk/risc-os/wined" class="external">Steve Fryatt</a>.</p>

<p>Some changes have been made to this help file, but the majority of the text remains the work of Tony Houghton. Any comments should be made to Steve Fryatt at <a href="mailto:info@stevefryatt.org.uk">info@stevefryatt.org.uk</a>.</p>

<h2 id="requirements">2. Requirements</h2>


<p>This release of <cite>WinEd</cite> requires RISC&nbsp;OS&nbsp;4.0 or later. It may well work on earlier systems if you manually alter the <span class="filename">!Run</span> file, but this is not supported.</p>

<h2 id="licence">3. Conditions of use and distribution</h2>


<p><cite>WinEd</cite> is released under the GNU General Public Licence. For details of what this means, <a href="Copying">see the Copying file</a>. The source code for <cite>WinEd</cite> is available from <a href="https://github.com/riscos-dot-info/wined" class="external">GitHub</a>.</p>

<h2 id="install">4. Installation</h2>


<p><cite>WinEd</cite> can be run from any filing system. To install <cite>WinEd</cite> drag it from the directory you receive it on to the directory you want it to &lsquo;live&rsquo; in. To ensure that your new copy is used in preference to the original, simply run it from the new location.</p>

<h2 id="disclaimer">5. Disclaimer</h2>


<p>Whilst every effort has been made to ensure that this software works correctly, no responsibility for any loss or damage caused by its use is accepted by the authors.</p>

<h2 id="units">6. Units used</h2>


<p>The units used and referred to throughout are OS&nbsp;units, except where stated. If a writable icon expecting a number is left blank, zero is assumed.</p>

<p>Remember that work area coordinates have the origin at the top left and anything below this is negative.</p>

<h2 id="mode">7. Mode independence</h2>


<p><cite>WinEd</cite> has been designed so that you do not have to design your templates in low resolution modes to ensure compatibility. This is done by &ldquo;snapping&rdquo; icons to a 4&times;4&nbsp;OS&nbsp;unit grid. (4&nbsp;OS&nbsp;units is equivalent to one pixel in the lowest resolution desktop modes). This can be overridden using the keyboard cursor arrows, together with either <span class="key">Ctrl</span> or <span class="key">Shift</span>.</p>

<h2 id="dialogue">8. <cite>WinEd</cite>&rsquo;s dialogue boxes</h2>


<p>Most of <cite>WinEd</cite>&rsquo;s dialogue boxes are static: that is, a click outside them does not close them. This slightly improves convenience and consistency.</p>

<h2 id="error">9. Error handling</h2>


<p>Where possible, <cite>WinEd</cite> tries to continue after an error, but you should save your data as soon as possible. If <cite>WinEd</cite> can not continue there will be a <span class="icon">Cancel</span> button instead of <span class="icon">OK</span> or <span class="icon">Continue</span>. After a fatal error <cite>WinEd</cite> will attempt to save files with unsaved changes in <span class="filename"><span class="variable">&lt;Wimp$ScrapDir&gt;</span>.WinEd</span>. I hope that you never have occasion to find this useful. &#128578;</p>

<h2 id="help">10. Interactive help</h2>


<p><cite>WinEd</cite> supports interactive help, including its menus; you may find this helpful at first.</p>

<h2 id="loading">11. Loading and creating templates</h2>


<p>Template files can be loaded by double clicking or dragging them to <cite>WinEd</cite>&rsquo;s icon on the iconbar. The number of files that <cite>WinEd</cite> can load and edit is only limited by memory. To create a new file click the <cite>WinEd</cite> icon; this opens an <a href="#browsers">empty <span class="window">Browser</span> window</a>.</p>

<p>Files can be merged by dragging one file into a <span class="window">Browser</span> window containing the other.</p>

<h2 id="keyboard">12. Keyboard control of the pointer</h2>


<p>While <cite>WinEd</cite> has the input focus, each press of one of the cursor keys moves the mouse pointer by one pixel in the appropriate direction.</p>

<p>Alternatively, the cursor keys can be made to &lsquo;nudge&rsquo; any selected icons without using the mouse. The icons are moved by 4&nbsp;OS&nbsp;units, unless the <span class="key">Shift</span> or <span class="key">Ctrl</span> modifier keys are held down, in which case the icons are moved by 2 or 1&nbsp;OS&nbsp;units, respectively.</p>

<h2 id="sprite">13. Sprite files and sprite areas</h2>


<p>In some windows it is necessary to create icons with sprites that belong to an application instead of the Wimp&rsquo;s sprite pool. You can load such &lsquo;user&rsquo; sprite files into <cite>WinEd</cite> by dragging them to its icon. <cite>WinEd</cite> 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 iconbar.</p>

<p>Holding <span class="key">Shift</span> while dragging a sprite file to <cite>WinEd</cite> causes it to be merged with the Wimp sprite pool and the screen is redrawn.</p>

<p>From version 2.30 onwards, all sprite area fields are saved with the value 1 (use Wimp sprites) and <cite>WinEd</cite> makes no distinction between the Wimp sprite pool and the user sprite pool. RISC&nbsp;OS&nbsp;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 area. It is up to the target application to change sprite area pointers to its own sprite area if necessary.</p>

<h2 id="iconbar">14. The iconbar menu</h2>


<p><cite>WinEd</cite>&rsquo;s iconbar menu can be accessed in the usual manner, with a <span class="mouse">Menu</span> click over <cite>WinEd</cite>&rsquo;s iconbar icon. The options contained within the menu are described in this section.</p>

<h3>14.1. Info</h3>


<p>Moving the pointer right opens a typical dialogue box containing information about <cite>WinEd</cite>, including buttons to email the current maintainer or visit the current <cite>WinEd</cite> website.</p>

<h3>14.2. Help</h3>


<p>The <span class="menu">Help...</span> entry will launch this user manual. If a web browser has been seen, an HTML version will be loaded; otherwise, a plain text version will open instead.</p>

<h3>14.3. Icon picker</h3>


<p>This entry opens the <span class="window">icon picker</span> immediately above the right hand end of the iconbar. The icon picker is <a href="#creatingicons">described in a later section</a>.</p>

<h3>14.4. Monitor</h3>


<p>This opens the <span class="window">monitor</span> window at the top right of the screen. The monitor is <a href="#monitor">described in a later section</a>.</p>

<h3>14.5. Choices...</h3>


<p>The <span class="menu">Choices...</span> entry will open the <a href="#choices"><span class="window">Choices</span> dialogue</a>, allowing some aspects of <cite>WinEd</cite>&rsquo;s operation to be configured.</p>

<h3>14.6. Clear sprites</h3>


<p>Clears the <a href="#sprite">user sprite area</a> to save memory.</p>

<h2 id="choices">15. The Choices dialogue box</h2>


<p>The <span class="window">Choices</span> dialogue box can be opened by selecting <span class="menu">Choices...</span> from the <a href="#iconbar">iconbar menu</a>. It allows a number of aspects of <cite>WinEd</cite>&rsquo;s operation to be configured.</p>

<p>Clicking on the <span class="icon">OK</span> button will cause any changes made to the choices to take effect; if <span class="mouse">Adjust</span> is used, the dialogue will remain on screen. Similarly <span class="icon">Cancel</span> will discard any un-saved changes, and using <span class="mouse">Adjust</span> will leave the dialogue open.</p>

<p>The <span class="icon">Save</span> button will save the configuration to disc, so that the choices made will be remembered for future sessions (otherwise they will be forgotten when <cite>WinEd</cite> is quit). To return to the default configuration, click on <span class="icon">Default</span> (and then either <span class="icon">Save</span> or <span class="icon">OK</span> to apply any changes).</p>

<p>The dialogue is split into sections as described below.</p>

<h3>15.1. Windows</h3>


<p>The <span class="icon">Windows</span> section controls the behaviour of windows within <cite>WinEd</cite> &ndash; both dialogue boxes and the templates being edited.</p>

<h4>15.1.1. Automatic monitor</h4>


<p>If selected the monitor will automatically open and close when editable or preview windows are opened and closed, as described in the <a href="#monitor">section about the monitor</a>.</p>

<h4>15.1.2. Automatic icon picker</h4>


<p>This makes the <a href="#creatingicons">icon picker</a> open and close with editable windows in a similar way to the monitor.</p>

<h4>15.1.3. Browser tool bar</h4>


<p>This causes a tool bar to be displayed along the top of <a href="#browsers"><span class="window">Browser</span> windows</a>.</p>

<h4>15.1.4. Editor panes</h4>


<p>If this option is set, the two large dialogue boxes for editing windows and icons will have their main action buttons in panes.</p>

<h4>15.1.5. Editable window tool bar</h4>


<p>This causes a tool pane to be attached to the top left of editable windows.</p>

<h4>15.1.6. Editable window furniture</h4>


<p>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.</p>

<h3>15.2. Editing</h3>


<p>The <span class="icon">Editing</span> section contains a collection of options which control the way that editing behaves.</p>

<h4>15.2.1. Keyboard short cuts</h4>


<p>If selected, <a href="#browsers"><span class="window">Browser</span> windows</a> 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.</p>

<h4>15.2.2. Move selection without mouse</h4>


<p>If selected, selected icons in editable windows can be nudged with the cursor keys instead of the keys only nudging the mouse pointer. The icons will move by 4&nbsp;OS&nbsp;units at a time. Holding down <span class="key">Shift</span> while nudging will make the steps only 2&nbsp;OS&nbsp;units and holding down <span class="key">Ctrl</span> will make the steps only 1&nbsp;OS&nbsp;unit per keypress.</p>

<h4>15.2.3. Round icon coordinates</h4>


<p><cite>WinEd</cite> can round the window coordinates of icons to the recommended number of OS&nbsp;units, to avoid issues with redraw in different screen modes. If <span class="icon">Round icon coordinates</span> is off, then coordinates will be left unchanged.</p>

<h4>15.2.4. Confirm deletions</h4>


<p>If selected, you will be prompted with an error box before deleting any icons or windows.</p>

<h4>15.2.5. Safe icon update</h4>


<p>In its default, unticked state, the <span class="icon">Update</span> button in the <a href="#editicon">Edit Icon dialogue box</a> will also resize the icon if it is too small for its contents. If ticked, the resizing moves to the non-default <span class="icon">Adjust size</span> action button.</p>

<h3>15.3. Display</h3>


<p>The <span class="icon">Display</span> section contains options which affect the visual appearance of the editing process.</p>

<h4>15.3.1. Always show borders</h4>


<p>If selected, all editable icons will be drawn with borders, making it easier to line them up with each other without using the automated features <cite>WinEd</cite> provides.</p>

<h4>15.3.2. Hatch user-drawn windows</h4>


<p>If selected, a cross hatch pattern will be displayed in any editable window which needs the task&rsquo;s help to be redrawn.</p>

<h4 id="choices-display-sort">15.3.3. Display templates sorted</h4>


<p>If selected, the templates displayed in a <a href="#browsers"><span class="window">Browser</span> window</a> will be listed in alphabetical order. The ordering in the physical template file will not be affected.</p>

<h3>15.4. Misc</h3>


<p>Finally, the <span class="icon">Misc</span> section contains options which don&rsquo;t fit in easily anywhere else.</p>

<h4>15.4.1. Autoload sprites</h4>


<p>When a template file is loaded <cite>WinEd</cite> will load a <span class="filename">Sprites</span>, <span class="filename">Sprites22</span> or <span class="filename">Sprites11</span> file from the same directory if one exists and this option is set.</p>

<h4>15.4.2. <cite>FormEd</cite> compatible strings</h4>


<p>All strings in template files are supposed to use carriage returns (CR) as terminators. The Wimp&rsquo;s template SWIs, and most applications, will work with any control character terminator, but <cite>FormEd</cite> is a notable exception which insists on CR for most strings. <cite>WinEd</cite> now uses CR by default, but if this option is unticked, it will use only zero terminators &ndash; which may be useful if you&rsquo;re programming lazily in C. &#128578;</p>

<h4>15.4.3. Strict with panes</h4>


<p>If selected, windows with the pane flag set will have certain other flags disabled to avoid unusual behaviour in the target application.</p>

<h4>15.4.4. Save templates sorted</h4>


<p>In addition to <a href="#choices-display-sort">visually sorting templates in <span class="window">Browser</span> windows</a>, <cite>WinEd</cite> can also sort them when saving a file if this option is selected.</p>

<div class="callout warning">
<div class="heading">Warning</div>

<div class="content">
<p>Selecting this option can result in template files changing when saved, even if no other editing is carried out. It is off by default, and it is recommended to consider the potential effects before switching it on.</p>
</div></div>

<h2 id="browsers">16. Browser windows</h2>


<p><span class="window">Browser</span> window is the term for a window which displays a list of the window and 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 icons change to indicate whether the window is currently open. The windows are displayed either in alphabetical order or in the order they appear in the file, depending on the <span class="icon">Display templates sorted</span> option in the <a href="#choices"><span class="window">Choices</span> window</a>.</p>

<p>If you click <span class="mouse">Adjust</span> on a <span class="window">Browser</span> window&rsquo;s close tool <cite>WinEd</cite> will attempt to open the directory the templates were last loaded or saved in, keeping the <span class="window">Browser</span> open if you hold <span class="key">Shift</span>. Iconising a <span class="window">Browser</span> (<span class="key">Shift</span>-<span class="mouse">Select</span> on the close tool) closes any windows which &lsquo;belong&rsquo; to it, thus it can be used for a quick tidyup. De-iconising the <span class="window">Browser</span> will re-open the closed windows.</p>

<h2 id="mouse">17. Mouse operations in <span class="window">Browser</span> windows</h2>


<p>Where the location is given as &lsquo;work area&rsquo; below, it refers to clicking over a part of the window not covered by an icon. Similarly, &lsquo;icon&rsquo; means clicking over an icon; each icon corresponds to a window or dialogue box definition. If neither are specified it refers to any part of the window. Holding down <span class="key">Ctrl</span> while clicking has the effect of forcing the action to behave as if the click is over the work area, ignoring any icon.</p>

<div class="table"><table>
<tr><th>Operation</th><th>Location</th><th>Effect</th></tr>
<tr><td>Select</td><td>Icon</td><td>Exclusively select icon</td></tr>
<tr><td>Select</td><td>Work Area</td><td>Clear selection</td></tr>
<tr><td>Adjust</td><td>Icon</td><td>Toggle selection state of icon without affecting others</td></tr>
<tr><td>Double-click Select</td><td>Icon</td><td>Open window for editing, or close it if already open</td></tr>
<tr><td>Double-click Adjust</td><td>Icon</td><td>Open window for preview, or close it if already open</td></tr>
<tr><td>Drag Select</td><td>Work Area</td><td>Start dragging rubber box; when complete all icons within the box are selected</td></tr>
<tr><td>Drag Select</td><td>Icon</td><td>Start drag &amp; drop operation on current selection, saving it with a filename of <span class="filename">Selection</span>.</td></tr>
<tr><td>Drag Adjust</td><td></td><td>Start dragging rubber box; all icons inside will have their selection state toggled</td></tr>
<tr><td>Menu</td><td></td><td>Open the <a href="#browsermenu"><span class="window">Browser</span> menu</a>.</td></tr>
</table></div>

<h2 id="browsermenu">18. The <span class="window">Browser</span> menu</h2>


<p>Clicking <span class="mouse">Menu</span> over a <a href="#browsers"><span class="window">Browser</span> window</a> will open the <span class="window">Browser</span> window menu, containing the options described in this section.</p>

<h3>18.1. Create</h3>


<p>Move the pointer right to create 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.</p>

<h3>18.2. Selection</h3>


<p>The <span class="menu">Selection</span> submenu (which appears as <span class="menu">Window</span> if a single template is selected) leads to a submenu containing options which can be applied to window definitions.</p>

<p>The following actions are available from the menu.</p>

<h4>18.2.1. Copy</h4>


<p>Move right over the menu entry to copy the selected template using the supplied name. This option isn&rsquo;t available if more than one template is selected.</p>

<h4>18.2.2. Rename</h4>


<p>Move right over the menu entry to rename the selected template using the supplied name. This option isn&rsquo;t available if more than one template is selected.</p>

<h4>18.2.3. Delete</h4>


<p>Select the <span class="menu">Delete</span> option to delete the selected templates from the browser.</p>

<div class="callout warning">
<div class="heading">Warning</div>

<div class="content">
<p>The delete operation is instant, and no confirmation is requested.</p>
</div></div>

<h4>18.2.4. Edit</h4>


<p>Select the <span class="menu">Edit</span> option to <a href="#edit">open the window for editing</a>. This is equivalent to double-clicking on the window in the browser with <span class="mouse">Select</span>.</p>

<p>This option isn&rsquo;t available if more than one template is selected.</p>

<h4>18.2.5. Preview</h4>


<p>Select the <span class="menu">Preview</span> option to <a href="#preview">open the window in preview mode</a>. This is equivalent to double-clicking on the window in the browser with <span class="mouse">Adjust</span>.</p>

<p>This option isn&rsquo;t available if more than one template is selected.</p>

<h4>18.2.6. Export icon names</h4>


<p>Move the pointer right over the menu entry to <a href="#export">export the icon names</a> in one of a number of formats.</p>

<h3>18.3. Select all</h3>


<p><span class="menu">Select all</span> will add all of the window templates within the <span class="window">Browser</span> window to the current selection.</p>

<h3>18.4. Clear selection</h3>


<p>The <span class="menu">Clear selection</span> entry will clear any selected windows within the <span class="window">Browser</span>.</p>

<h3>18.5. Save</h3>


<p>The <span class="menu">Save</span> entry will allow the templates within the <span class="window">Browser</span> window to be <a href="#save">saved</a> to their template file. Sliding the pointer right will reveal a standard <span class="window">Save as</span> dialogue box, while a click will cause the file to be saved immediately if a full pathname is available.</p>

<h3>18.6. Statistics</h3>


<p>Opens a statistics window for the file in the <a href="#browsers"><span class="window">Browser</span> window</a>. This is <a href="#stats">described below</a>.</p>

<h2 id="save">19. Saving templates</h2>


<p>The contents of a <a href="#browsers"><span class="window">Browser</span> window</a> can be saved using the <span class="menu">Save</span> entry in the <a href="#browsermenu"><span class="window">Browser</span> menu</a>, clicking on the <span class="icon">Save</span> button in the <a href="#browsertool"><span class="window">Browser</span> tool bar</a>, or pressing <span class="key">F3</span>.</p>

<p>Saving is normally carried out using a standard <span class="window">Save as</span> dialogue but, if the template file already has a full pathname shown in the <span class="window">Browser</span> window title bar, clicking on the <span class="menu">Save</span> menu item or <span class="mouse">Adjust</span>-clicking on the <span class="icon">Save</span> button will save the file instantly to that location.</p>

<p>If one or more windows are selected when the <span class="window">Save as</span> dialogue opens, the <span class="icon">Selection</span> button will be available. This should be ticked 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 new file back into <cite>WinEd</cite> and resave.</p>

<h2 id="stats">20. Statistics windows</h2>


<p>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 with <span class="name">Wimp_LoadTemplate</span>; similarly Indirected shows the size of buffer needed to hold the icons&rsquo; indirected data. Note that the Buffer size is the size that will be requested by <span class="name">Wimp_LoadTemplate</span> and includes the Wimp&rsquo;s scratch buffer for indirected data.</p>

<p>Each row in the main section of the window shows the data described above for each window definition in the file.</p>

<p>The penultimate row shows the total of each column for all the windows in the file.</p>

<p>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.</p>

<h2 id="browsertool">21. The <span class="window">Browser</span> tool bar</h2>


<p>This is a row of tool icons which can optionally be displayed along the top of <a href="#browsers"><span class="window">Browser</span> windows</a>. The tools provide short cuts for the functions described above, available from the <a href="#browsermenu">Browser menu</a>. They are (from left to right):</p>

<ul>
<li>Create (opens writable submenu)</li>
<li>Select all (Select mouse button) / Clear selection (Adjust mouse button)</li>
<li>Save</li>
<li>Copy (opens writable submenu)</li>
<li>Rename (opens writable submenu)</li>
<li>Delete</li>
<li>Statistics</li>
</ul>

<h2 id="export">22. Exporting icon names</h2>


<p>The last entry on the selected window(s) submenu of the <a href="#browsermenu"><span class="window">Browser</span> menu</a> leads to a <span class="window">Save as</span> dialogue box for exporting icon names from all of the selected windows in one of several different formats.</p>

<ul>
<li><span class="icon">C Enum</span> exports a standard C <code>enum ... { ... };</code> structure, where the entries are the icon names and handles.</li>
<li><span class="icon">C Typedef</span> is similar, but exports a C <code>typedef enum { ... } ...;</code> structure instead.</li>
<li><span class="icon">C #define</span> exports a list of C preprocessor <code>#define ... </code> directives, to define constants for the icon names.</li>
<li><span class="icon">BASIC</span> exports a definition for <code>PROCiconnumbers</code>, in which variables are defined for each icon name.</li>
<li><span class="icon">Messages</span> exports a skeleton MessageTrans file, where tokens are set up for the icon names.</li>
</ul>

<p>Most of the exports are as plain text; if <span class="icon">BASIC</span> is selected, then the file is a correctly formatted BASIC program file.</p>

<p>The names used in the export are the icon names, as given using the <code>N</code> validation string command. If <span class="icon">Include window name</span> is ticked, then the names will be prefixed by the name of the template containing the identifier. Without window names, an export might look like this:</p>

<div class="codeblock"><pre>enum ProgInfo {
  Title = 1,
  Purpose = 3,
  Authors = 5,
  Version = 7
};</pre></div>

<p>With the name included, it might look like this:</p>

<div class="codeblock"><pre>enum ProgInfo {
  ProgInfo_Title = 1,
  ProgInfo_Purpose = 3,
  ProgInfo_Authors = 5,
  ProgInfo_Version = 7
};</pre></div>

<p>The case of the names can be left as it is defined in the templates by selecting <span class="icon">Unchanged</span>, or converted to <span class="icon">All upper</span> or <span class="icon">All lower</span> as required. Characters which are not valid for the target format are converted to underscores.</p>

<p>If <span class="icon">Add prefix</span> is ticked, a user-supplied prefix can be additionally be added to the start of each name. It is up to the user to ensure that the prefix is valid for the language that they are exporting to.</p>

<p>A couple of format-specific options are also available. When exporting as <span class="icon">C Enum</span> or <span class="icon">C Typedef</span>, the <span class="icon">Skip implied numbers</span> option will omit explicit assignments if they are implied by the position of the line in the enum. For example, this:</p>

<div class="codeblock"><pre>enum ProgInfo {
  OK = 0,
  Cancel = 1,
  Upper = 3,
  Lower = 4,
  ROT13 = 6
};</pre></div>

<p>would become this:</p>

<div class="codeblock"><pre>enum ProgInfo {
  OK,
  Cancel,
  Upper = 3,
  Lower,
  ROT13 = 6
};</pre></div>

<p>In <span class="icon">BASIC</span> mode, <span class="icon">Use real variables</span> will write the variable names without a trailing <code>%</code> &ndash; making them real instead of integer.</p>

<p>Note that the output of any of these options can be altered by editing <cite>WinEd</cite>&rsquo;s <span class="filename">Messages</span> file. See the chapter on <a href="#custom">customisation</a>.</p>

<h2 id="preview">23. Preview windows</h2>


<p>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 <span class="mouse">Adjust</span> on a window in a <a href="#browsers"><span class="window">Browser</span></a> or by choosing <span class="menu">Preview</span> from the <a href="#browsermenu"><span class="window">Browser</span> menu</a>.</p>

<p>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.</p>

<p>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 <span class="key">Ctrl</span>. Using <span class="mouse">Select</span> has the same effect as dragging the title bar (move window) and <span class="mouse">Adjust</span> is the same as dragging the adjust size tool (resize window).</p>

<p>It may also be necessary to see how windows fit with each other (eg. for panes) without superfluous tools.</p>

<p>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.</p>

<h2 id="previewmenu">24. The preview menu</h2>


<p>The preview menu is available when <a href="#preview">a template is being previewed</a>, by clicking <span class="mouse">Menu</span> over its window.</p>

<h3>24.1. Close</h3>


<p>Close the preview window, even if it does not have a close icon of its own.</p>

<h3>24.2. Store position</h3>


<p>Stores the current onscreen size and position of the window in the template definition.</p>

<h3>24.3. Store icon states</h3>


<p>Stores the selection states of the window&rsquo;s icons in the template definition. However, it is better practice to leave any selection to the application which finally uses the templates.</p>

<h3>24.4. Edit template</h3>


<p>Select <span class="menu">Edit template</span> to close the preview and re-open the template as <a href="#edit">an editable window</a>.</p>

<h2 id="edit">25. Editable windows</h2>


<p>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. This means that they do not appear exactly as they will when used in your program. (In particular, many of the cosmetic changes introduced in RISC&nbsp;OS Select will not be shown.) To see how your windows will really look use the preview system.</p>

<p>Many of the following sections refer to dialogue boxes; each of these is described in its own section.</p>

<h2 id="mouseedit">26. Mouse operations in editable windows</h2>


<p>These are summarised below with notes. Note also that all mouse operations in editable windows can be modified in the same way with the <span class="key">Ctrl</span> 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 <span class="key">Esc</span> when you release the mouse.</p>

<p>Note that moving and resizing icons by dragging will always round the result to a multiple of 4&nbsp;OS&nbsp;units. For more precise control when moving icons, you can use the cursor keys instead (together with the <span class="key">Ctrl</span> and <span class="key">Shift</span> modifiers. Small changes to the size of icons must be done via the <span class="window">Coordinates</span> dialogue box.</p>

<div class="table"><table>
<tr><th>Operation</th><th>Location</th><th>Effect</th></tr>
<tr><td>Select</td><td>Work Area</td><td>Clear selection</td></tr>
<tr><td>Select</td><td>Non-Selected Icon</td><td>Exclusively select icon</td></tr>
<tr><td>Menu</td><td></td><td>Open editable window menu</td></tr>
<tr><td>Adjust</td><td>Non-Selected Icon</td><td>Select icon without affecting others</td></tr>
<tr><td>Adjust</td><td>Selected Icon</td><td>Deselect icon</td></tr>
<tr><td>Drag Select</td><td>Work Area</td><td>Drag a rubber box to select icons<a href="#note-1"><sup>1</sup></a></td></tr>
<tr><td>Drag Select</td><td>Icon</td><td>Move (local) / Copy (export) icon<a href="#note-2"><sup>2</sup></a></td></tr>
<tr><td>Drag Adjust</td><td>Work Area</td><td>Drag a rubber box to invert the selection state of icons<a href="#note-1"><sup>1</sup></a></td></tr>
<tr><td>Drag Adjust</td><td>Icon</td><td>Resize icon, moving the edge nearest the pointer<a href="#note-3"><sup>3</sup></a></td></tr>
<tr><td>Drag Shift-Adjust</td><td>Icon</td><td>Resize icon, moving the corner nearest the pointer<a href="#note-3"><sup>3</sup></a></td></tr>
<tr><td>Drag Shift-Select</td><td>Icon</td><td>Copy (local)/Move (export) icon<a href="#note-2"><sup>2</sup></a></td></tr>
<tr><td>Drag Shift-Ctrl-Select</td><td></td><td>Move window as if dragging title bar</td></tr>
<tr><td>Drag Shift-Ctrl-Adjust</td><td></td><td>Resize window as if dragging adjust size tool</td></tr>
<tr><td>Double click Select</td><td>Work Area</td><td>Edit window (open dialogue)<a href="#note-4"><sup>4</sup></a></td></tr>
<tr><td>Double click Select</td><td>Icon</td><td>Edit icon(s) (open dialogue)<a href="#note-5"><sup>5</sup></a></td></tr>
<tr><td>Double click Adjust</td><td>Work Area</td><td>Edit work area (open dialogue)<a href="#note-4"><sup>4</sup></a></td></tr>
<tr><td>Double click Adjust</td><td>Icon</td><td>Minimise icon<a href="#note-6"><sup>6</sup></a></td></tr>
<tr><td>Double click Shift-Select</td><td>Work Area</td><td>Edit window title icon (open dialogue)<a href="#note-4"><sup>4</sup></a></td></tr>
</table></div>

<dl class="footnotes">
<dt id="note-1">Note 1</dt>
<dd>This is similar to the same type of drag in <a href="#browsers"><span class="window">Browser</span> windows</a>.</dd>

<dt id="note-2">Note 2</dt>
<dd><p style="margin-top: 0;">This follows the conventions of Drag &amp; Drop as outlined in the <cite>Style Guide</cite>. The unmodified drag and <span class="key">Shift</span>-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 <span class="key">Shift</span>-drag copies it, in the export case an unmodified drag copies the icon, a <span class="key">Shift</span>-drag effectively moves the icon by making a copy in the destination window and deleting the original.</p><p style="margin-bottom: 0;">If the pointer leaves the window during a drag, then the window is scrolled if possible; if the drag turns out to be an export, then the scroll bars are reset to their original positions. The <span class="key">Shift</span> key is polled at the start of the drag, not the end.</p></dd>

<dt id="note-3">Note 3</dt>
<dd>Resize drags are limited by the window&rsquo;s visible area.</dd>

<dt id="note-4">Note 4</dt>
<dd>These operations open the relevant dialogue box.</dd>

<dt id="note-5">Note 5</dt>
<dd>See <a href="#select-edit">Section 27.4. Edit...</a> below.</dd>

<dt id="note-6">Note 6</dt>
<dd>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 <a href="#resize">Resize icons dialogue box</a>.</dd>
</dl>

<h2 id="select">27. Selected icon(s) submenu</h2>


<h3>27.1. Delete</h3>


<p>Deletes the selected icon(s). Deleted icons are entirely removed from the template; any icons with higher numbers are renumbered to &ldquo;fill the gap&rdquo;. The <span class="key">Delete</span> key (in addition to <span class="key">Ctrl-K</span>) can be used to delete an icon using the keyboard.</p>

<h3>27.2. Renumber nn</h3>


<p>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.</p>

<h3>27.3. Copy</h3>


<p>This menu item leads to a submenu where you can choose to copy the current selection of icons either up, down, left or right.</p>

<h3 id="select-edit">27.4. Edit...</h3>


<p>If only one icon is selected, the Edit icon dialogue box is opened, if more than one is selected, the <a href="#editicons">Edit multiple icons dialogue</a> is opened instead.</p>

<h2 id="edittool">28. The editable window tool bar</h2>


<p>This is optionally attached to the topleft edge of editable windows and provides short cuts for the menu functions described above. The tools are (left to right, top to bottom):</p>

<ul>
<li>Edit window...</li>
<li>Edit title...</li>
<li>Work area...</li>
<li>Visible area...</li>
<li>Delete</li>
<li>Renumber (<span class="mouse">Select</span> opens dialogue box, <span class="mouse">Adjust</span> renumbers with value currently shown in menu)</li>
<li>Align...</li>
<li>Space out...</li>
<li>Resize...</li>
<li>Coords...</li>
<li>Frame...</li>
<li>Select all (<span class="mouse">Select</span> mouse button) / Clear selection (<span class="mouse">Adjust</span> mouse button)</li>
</ul>

<h2 id="editwindow">29. Edit window dialogue box</h2>


<p>Most of the option buttons in this dialogue box correspond directly to window flags documented in the <cite>Programmer&rsquo;s Reference Manual</cite> and other books. The names of the colours are abbreviated to save space. They are:</p>

<div class="table"><table>
<tr><th>Label</th><th>Meaning</th></tr>
<tr><td>Title F.</td><td>Title bar Foreground.</td></tr>
<tr><td>Title B.</td><td>Title bar Background.</td></tr>
<tr><td>Work F.</td><td>Work area Foreground.</td></tr>
<tr><td>Work B</td><td>Work area Background.</td></tr>
<tr><td>Scr. Out.</td><td>Scroll bar Outer.</td></tr>
<tr><td>Scr. In.</td><td>Scroll bar Inner.</td></tr>
<tr><td>Input Focus</td><td>Input focus (the colour the title bar changes to when the window has input focus).</td></tr>
</table></div>

<h3>29.1. Default</h3>


<p>Sets all the colours to their recommended default values. This button doesn&rsquo;t close the dialogue box.</p>

<h3>29.2. GCOL colours</h3>


<p>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. <cite>WinEd</cite> only supports colours in the usual range of 0-15 (and 255/1 for transparent). This option is unavailable if <span class="icon">24bit title colour</span> is chosen.</p>

<h2 id="goto">30. Goto icon menu option</h2>


<p>Moving the mouse to the right over the <span class="menu">Goto icon</span> menu option will allow you to enter an icon name or number. If a corresponding icon is found in the current viewer the mouse will be placed in the centre of the icon (even if it&rsquo;s not currently showing on screen).</p>

<h2 id="monitor">31. The monitor</h2>


<p>The monitor shows the following information about any window/icon under the pointer, provided it is in a template loaded in <cite>WinEd</cite>.</p>

<h3>31.1. Window</h3>


<p>The identifier of the window under the pointer. A trailing * means it is an editable window, otherwise it is a preview window.</p>

<h3>31.2. Icon no.</h3>


<p>The number of the icon under the pointer, or &ldquo;Work area&rdquo;.</p>

<h3>31.3. Icon name</h3>


<p>This displays the icon name (if present), as given by using the <code>N</code> validation option in an indirected icon&rsquo;s validation string.</p>

<h3>31.4. Position</h3>


<p>The work area coordinate of each edge of the icon.</p>

<h3>31.5. Size</h3>


<p>The size of the icon, shown as <span class="maths">width</span> &times; <span class="maths">height</span>.</p>

<p>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.</p>

<p>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.</p>

<h2 id="creatingicons">32. Creating icons: the Icon picker</h2>


<p>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.</p>

<p>Like the monitor the icon picker 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.</p>

<p>The icon picker contains examples of most of the common types of icon, but it can be customised. See the section on <a href="#custom">Customising <cite>WinEd</cite></a>.</p>

<h2 id="workarea">33. Work area dialogue box</h2>


<p>The work area coordinates are shown in formation. Note that it is usual to have the origin of the window (0) at the top, and the bottom coordinate is negative.</p>

<p>The bumper buttons cause the sizes to change in units of 4, unless the <span class="key">Shift</span> or <span class="key">Ctrl</span> modifier keys are pressed, in which case the numbers are altered in units of 2 and 1, respectively.</p>

<h3>33.1. Minimise</h3>


<p>This sets the values in the work area coordinate fields to the work area coordinates of the portion of the window currently visible. It is not recommended that the origin (<span class="maths">X0</span> &amp; <span class="maths">Y1</span>) coordinates are set to any value other than zero, hence the <span class="icon">Keep origin</span> button is provided.</p>

<h3>33.2. Keep origin</h3>


<p>This has a similar effect to the <span class="icon">Minimise</span> button, but the origin (<span class="maths">X0</span> &amp; <span class="maths">Y1</span>) coordinates are set to zero.</p>

<h3>33.3. Minimum size</h3>


<p>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 <span class="icon">Maximise</span> button sets the values to the current size of the window.</p>

<h2 id="visiblearea">34. Visible area dialogue box</h2>


<p>This allows you to specify the position, size and scroll offsets of a window as it will appear on screen when first opened. All values are usually positive, except for the vertical scroll offset (V Scroll), which should be negative.</p>

<p>The bumper buttons cause the sizes to change in units of 4, unless the <span class="key">Shift</span> or <span class="key">Ctrl</span> modifier keys are pressed, in which case the numbers are altered in units of 2 and 1, respectively.</p>

<h2 id="editicon">35. Edit icon/title dialogue box</h2>


<p>Most of the entries in this window correspond to icon flags and properties described in the <cite>Programmer&rsquo;s Reference Manual</cite> or other books.</p>

<h3>35.1. Test/sprite</h3>


<p>If the icon contains a text or sprite, enter the text or sprite name here.</p>

<h3>35.2. Validation</h3>


<p>You can enter a validation string here for indirected text icons.</p>

<h3>35.3. Max text length</h3>


<p>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 <span class="icon">Text/sprite</span> field by clicking the <span class="icon">Minimise</span> button.</p>

<h3>35.4. Outline font</h3>


<p>If set the icon uses the outline font shown in the field below; fonts can be chosen from a menu by clicking the <span class="mouse">Menu</span> 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.</p>

<p>Outline fonts do not seem to work in icons with validation strings containing the <code>L</code> command.</p>

<h3>35.5. Validate</h3>


<p>Font handles overwrite the colour fields in icon flags, therefore the colour data is held in an <code>F</code> command in the validation string. The <span class="icon">Validate</span> button reads the colours from the fields in the dialogue box and ensures the validation string contains the correct <code>F</code> command, forcing the indirected flag on if necessary.</p>

<h3>35.6. Update / Don&rsquo;t resize / Adjust size</h3>


<p>The two action buttons both update the template data with settings from the dialogue box. If the second button is <span class="icon">Don&rsquo;t resize</span>, then <span class="icon">Update</span> will also resize the icon if it is currently too small to display its data (see <span class="window">Resize icons</span> dialogue box). If the second button is <span class="icon">Adjust size</span>, which can be configured by the <span class="icon">Safe icon update</span> option in the <a href="#choices"><span class="window">Choices</span> dialogue</a>, then <span class="icon">Update</span> will only store any changed values, while <span class="icon">Adjust size</span> will also perform any resizing which is required.</p>

<h2 id="editicons">36. Edit multiple icons dialogue box</h2>


<p><cite>WinEd</cite> can apply changes to a subset of the icon flags to a selection of icons simultaneously; only those which do not affect icon data or outline fonts can be changed for a multiple selection.</p>

<p>For simple on/off flags you can choose one of the radios <span class="icon">Y</span>, <span class="icon">N</span> or <span class="icon">?</span>, meaning set the flag for all selected icons, reset it, or leave this flag alone for each icon respectively. For <span class="icon">ESG</span> and <span class="icon">Button</span> type tick the option button on the left to enable a value to be entered for all selected icons, otherwise they will not be affected.</p>

<h2 id="align">37. Align dialogue box</h2>


<p>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. If only one icon is selected it can be centred in its window.</p>

<h3>37.1. Left</h3>


<p>The icons will all share the same left (minimum x) coordinate.</p>

<h3>37.2. H centre</h3>


<p>The icons will be arranged so that half their width is each side of a notional vertical midline. This midline is calculated from the leftmost or rightmost midpoint of all the icons, depending on whether the <span class="icon">Move left</span> or <span class="icon">Move right</span> icon is selected.</p>

<h3>37.3. Right</h3>


<p>The icons will all share the same right (maximum <span class="maths">X</span>) coordinate.</p>

<h3>37.4. Top</h3>


<p>The icons will all share the same top (maximum <span class="maths">Y</span>) coordinate.</p>

<h3>37.5. V centre</h3>


<p>The icons will be arranged so that half their height is each side of a notional horizontal midline. This midline is calculated from the topmost or bottommost midpoint of all the icons, depending on whether the <span class="icon">Move down</span> or <span class="icon">Move up</span> icon is selected.</p>

<h3>37.6. Bottom</h3>


<p>The icons will all share the same bottom (minimum <span class="maths">Y</span>) coordinate.</p>

<h3>37.7. Group box &amp; label</h3>


<p>This is only applicable if exactly two icons are selected in the editable window and the lowernumbered 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&rsquo;s left edge 32&nbsp;OS&nbsp;units to the right of the left edge of the group box and its bottom edge is 24&nbsp;OS&nbsp;units below the top of the group box (ideal for labels 44&nbsp;OS&nbsp;units high).</p>

<h3>37.8. Move / Resize</h3>


<p>Icons can either be moved or resized to achieve alignment. If <span class="icon">Move</span> is chosen, icons are moved without changing their size. If <span class="icon">Resize</span> 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.</p>

<h3>37.9. Move left/down/label / Move right/up/box</h3>


<p>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 leftmost icon. In the special case of Group box &amp; label these options determine whether the label or the box is moved.</p>

<h3>37.10. Centre in window</h3>


<p>If this is selected instead of one of the above, the centre of the window is chosen as the reference point instead of one of the icons, and it only allows alignment of centres, not edges.</p>

<h2 id="space">38. Space out dialogue box</h2>


<p>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.</p>

<p>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 &lsquo;anchor&rsquo; &ndash; eg. if you choose <span class="icon">From left</span> the leftmost icon stays still and all the others are spaced out to its right.</p>

<p>If only a single icon is selected it is spaced out from the edge of the visible area corresponding to the direction radio icons.</p>

<h2 id="resize">39. Resize icons dialogue box</h2>


<p>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.</p>

<h3>39.1. Minimise</h3>


<p>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.</p>

<p>The size needed for text (taking outline fonts into account) is first calculated, adding a few pixels to each side to satisfy <cite>Style Guide</cite> conventions. Then the size needed for any sprite is calculated if possible. These two sizes are combined, taking into account the icon&rsquo;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.</p>

<p>Icons with <code>L</code> 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 &ndash; they do not work with the <code>L</code> command in RISC&nbsp;OS&nbsp;3.1 anyway.</p>

<p>Versions of <cite>WinEd</cite> from 2.12 onwards ensure that icons that use the system font are also large enough for the current RiscPC Desktop font. If the Desktop font is the System font or you are using RISC&nbsp;OS&nbsp;3.1 then 12pt Homerton Medium is used. Note that this does not apply to <code>L</code> validation, but it is unlikely that an outline font will take more room than the System font for long strings.</p>

<h3>39.2. Make same size</h3>


<p>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.</p>

<h3>39.3. Excluding borders</h3>


<p>If this option is set while making a group of icons the same size as each other, only the size of the icons inside their borders is made the same, so icons with wider borders will be larger overall. This is most useful for sets of action buttons where the default action button is the same size as the others with an additional trench around it.</p>

<h2 id="coords">40. Coordinates dialogue box</h2>


<p>This allows you to enter the position (relative to the window&rsquo;s work area) and size coordinates of an icon. The Top entry is usually negative.</p>

<p>The bumper buttons cause the sizes to change in units of 4, unless the <span class="key">Shift</span> or <span class="key">Ctrl</span> modifier keys are pressed, in which case the numbers are altered in units of 2 and 1, respectively.</p>

<h2 id="frame">41. Frame dialogue box</h2>


<p>This is for placing a frame around the selected icons. The frame can consist of the window&rsquo;s visible area or an empty bordered icon (group box) with a lower number than any of the selected icons.</p>

<p>The bumper buttons cause the sizes to change in units of 4, unless the <span class="key">Shift</span> or <span class="key">Ctrl</span> modifier keys are pressed, in which case the numbers are altered in units of 2 and 1, respectively.</p>

<h3>41.1. Gap</h3>


<p>Enter the minimum gap (OS&nbsp;units) to leave between the frame and any icons inside it. This varies depending on whether the frame is the window&rsquo;s visible area (816 looks best) or an icon with a 3D border (usually with <code>R4</code> validation, 20 or more looks better).</p>

<h3>41.2. Visible area</h3>


<p>If selected the frame is made by resizing the window&rsquo;s visible area to fit the selection. The window&rsquo;s work area must be large enough to accommodate it.</p>

<h3>41.3. Icon</h3>


<p>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.</p>

<h3>41.4. Allow for label</h3>


<p>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&nbsp;OS&nbsp;units) is left between the top of the frame and the topmost selected icon to make room for a text label.</p>

<h3>41.5. Top, Left, Right, Bottom</h3>


<p>Only the frame&rsquo;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.</p>

<h2 id="hints">42. Hints &amp; tips</h2>


<h3>42.1. Size of dialogue boxes</h3>


<p>When designing dialogue boxes and non-scrollable windows, try to make sure they will fit on screen in as many modes as possible. Mode&nbsp;22 support (768 &times; 576 OS&nbsp;units) is not strictly necessary, but you should at least fit your windows on a Mode&nbsp;27 screen (1280 &times; 960 OS&nbsp;units). The <cite>Style Guide</cite> recommends a maximum of 800 &times; 600 OS&nbsp;units for dialogue boxes.</p>

<h3>42.2. Positioning icons</h3>


<p>Icons with similar functions should be the same size as each other and aligned. When aligning icons, some of which have double borders (eg. <code>R6</code> 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 ESGs) place group boxes around them.</p>

<p>Place action icons, particularly the default action and <span class="icon">Cancel</span> buttons aligned up the side or preferably along the bottom of dialogue boxes. Position the default action button at the bottom right.</p>

<p>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 <cite>Style Guide</cite> suggests a gap of at least 8&nbsp;OS&nbsp;units between icons, but 16 or more generally looks far better.</p>

<p>Note that <cite>WinEd</cite>&rsquo;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 <span class="icon">Cancel</span> buttons in the parent window so they are also visible. Panes were used in <cite>WinEd</cite>&nbsp;1.00, but were too restrictive.</p>

<h3>42.3. Writable icons</h3>


<p>Use a validation string containing <code>Kta</code>, not <code>Ktar</code> as the <cite>Style Guide</cite> suggests. Due to a bug in RISC&nbsp;OS&nbsp;3.1 this must be the last entry in a validation string to work correctly.</p>

<h3>42.4. Outline fonts</h3>


<p>Outline fonts in icons should generally be avoided. Apart from the latest versions of RISC&nbsp;OS now being able to automatically use outline fonts in all icons there are a couple of bugs.</p>

<p>In RISC&nbsp;OS&nbsp;3.1 using an outline font in the title bar of a window causes a terrible mess if a customised title bar (eg. <cite>NewLook</cite>&rsquo;s 3D one) is used.</p>

<p>In RISC&nbsp;OS&nbsp;3.5 using an outline font in slabbing icons (<code>R5</code> and <code>R6</code> validation) causes the default desktop font to be reset or disappear or something.</p>

<p>In RISC&nbsp;OS&nbsp;3.1 at least, outline fonts seem to be incompatible with <code>L</code> validation commands.</p>

<h3>42.5. Modifying other people&rsquo;s templates</h3>


<p>Be careful when modifying other people&rsquo;s templates; always make sure you have a backup of the original file. Some programs may object to changes in their template files &ndash; eg. adding outline fonts, changing the order of windows in the file, and increasing the amount of indirected data. Never renumber any icons.</p>

<h3>42.6. Deleting icons</h3>


<p>Unlike many template editors, when deleting an icon in <cite>WinEd</cite> its definition is entirely removed from the template, subsequent icons are renumbered to &lsquo;fill the gap&rsquo;.</p>

<p>The Delete flag is best avoided: having deleted icons in your templates can cause confusion when using other template editors.</p>

<h2 id="custom">43. Customising <cite>WinEd</cite></h2>


<p>As well as the <span class="window">Choices</span> dialogue box <cite>WinEd</cite> can be customised by editing its own template file; this is the file called <span class="filename">Templates</span> within the <cite>WinEd</cite> resources directory.</p>

<p><cite>WinEd</cite> 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.</p>

<p>Some windows you may wish to customise are listed here</p>

<h3>43.1. Icon picker</h3>


<p>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.</p>

<h3>43.2. Monitor</h3>


<p>The monitor&rsquo;s initial position depends on its template.</p>

<h3>43.3. Edit window dialogue box / Edit icon dialogue box</h3>


<p>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 nonfunctional icons such as group boxes and labels, temporarily enlarge the work area and move them out of the way. Remember you can turn the command button panes off in Choices if you want to reshape the window.</p>

<h3>43.4. Tool panes</h3>


<p>You can customise these by editing the <span class="name">WinTools</span> and <span class="name">BrowTools</span> templates and/or the <span class="filename">Sprites</span> and <span class="filename">Sprites22</span> files. Note that you will have to disable the Editable window tool icons option to avoid inadvertently resizing the current <a href="#browsertool"><span class="window">Browser</span> tool bar</a> while editing it. 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.</p>

<p>Many of the default values shown in writable icons etc in the dialogue boxes are determined by the values in <cite>WinEd</cite>&rsquo;s templates.</p>

<p>If you alter <cite>WinEd</cite>&rsquo;s templates be sure to back up the original file; <cite>WinEd</cite> must be distributed with this <span class="filename">Templates</span> file.</p>

<h3>43.5. Exporting icon names</h3>


<p>The format in which icon names are exported is highly configurable by editing the <span class="filename">Messages</span> file. For example, look at the export template messages as supplied; you should find them at the bottom of the file:</p>

<div class="codeblock"><pre># C typedef enum { ... } ...; style output.

ExportTypedefStart:typedef enum {
ExportTypedefIcon:  @pf[@wn_]@in[ = @ih]
ExportTypedefSep:,
ExportTypedefEnd:} @wn_icons;</pre></div>

<p>There are five groups, whose names start <code>ExportEnum...</code>, <code>ExportTypedef...</code>, <code>ExportDefine...</code>, <code>ExportBasic...</code> and <code>ExportMessages...</code> respectively, covering the formatting for each output format.</p>

<p>The <code>...Start</code> and <code>...End</code> tokens are used at the start and end of a window block, with <code>...Icon</code> being written for each icon name to be output. For all but the last icon to be written, the <code>...Sep</code> token is added to the end of the line.</p>

<p>In addition, there are <code>...Preamble</code> and <code>...Postamble</code> tokens which are written at the start and end of the file. In BASIC, these are used to write the <code>DEF PROCiconnumbers</code> and <code>ENDPROC</code> lines.</p>

<p>Finally, <code>ExportPreamble</code> and <code>ExportPostamble</code> tokens provide content for start-of-file and end-of-file comments respectively, while and <code>ExportWindow</code> allows a comment to be written before each window&rsquo;s icons. The same tokens are used in all output formats, with appropriate comment marks around them.</p>

<p>All of the tokens are optional, and will simply be omitted from the output if not present.</p>

<p>The tokens follow the standard MessageTrans format, with the string up to and including the colon at the beginning of each line being the token used by the <cite>WinEd</cite> to look up the message. Following that is a format string, which uses a slightly different format from the standard MessageTrans one. The line will be output to the file, with the following parameters being substituted:</p>

<div class="table"><table>
<tr><th>Sequence</th><th>Purpose</th></tr>
<tr><td><code>@wn</code></td><td>The window template name</td></tr>
<tr><td><code>@in</code></td><td>The icon name</td></tr>
<tr><td><code>@ih</code></td><td>The icon handle, or number</td></tr>
<tr><td><code>@pf</code></td><td>The user-supplied line prefix</td></tr>
<tr><td><code>@dt</code></td><td>The date and time of the export operation</td></tr>
<tr><td><code>@vs</code></td><td>The appropriate BASIC variable suffix (% or nothing)</td></tr>
</table></div>

<p>Note that not all substitutions will be valid in all contexts.</p>

<p>The format string can be divided up into blocks using the <code>[</code> and <code>]</code> characters, which can be nested if required. A block, and any blocks nested inside it, will only be included if one of the substitutions contained within it is able to be applied.</p>

<div class="codeblock"><pre>@pf[@wn_]@in[ = @ih]</pre></div>

<p>In this example, the <code>@wn_</code> text will only be included if the window name (the <code>@wn</code> value) is relevant and available. This ensures that the underscore separator is also omitted if window names are not included. In a similar way, the <code> = @ih</code> will all be omitted if the icon handle isn&rsquo;t being included (if <code>Skip implied numbers</code> is taking effect). Amongst many other combinations. this line might produce <code>ProgInfo_Title = 1</code>, or <code>Title = 1</code>, or <code>Title</code>, or perhaps <code>PrefixProgInfo_Title</code> depending upon the options used for the export.</p>

<p>You need not use all the substitutions available for any message.</p>

<p>The backslash character can be used to include additional escape sequences:</p>

<div class="table"><table>
<tr><th>Sequence</th><th>Purpose</th></tr>
<tr><td><code>\n</code></td><td>Start a new line (in comments, this will add the necessary continuation characters)</td></tr>
<tr><td><code>\t</code></td><td>Insert a tab character.</td></tr>
<tr><td><code>\xXX</code></td><td>Insert the character whose code is <span class="maths">XX</span> in hex.</td></tr>
<tr><td><code>\\</code></td><td>Insert a literal \</td></tr>
<tr><td><code>\[</code></td><td>Insert a literal [</td></tr>
<tr><td><code>\]</code></td><td>Insert a literal ]</td></tr>
<tr><td><code>\@</code></td><td>Insert a literal @</td></tr>
</table></div>

<h2 id="versions">44. Version history</h2>


<p>The version history of <cite>WinEd</cite>, back as far as version 3.23, is as follows. Change logs prior to 2020 are not currently available.</p>

<h3>44.1. Version 3.27 (27 April 2024)</h3>


<div class="callout warning">
<div class="heading">Warning</div>

<div class="content">
<p>In <cite>WinEd</cite>&nbsp;3.27, the configuration file format has changed from binary to plain text, in order to enable options to be more easily added, changed and removed in the future without creating further backwards compatibility issues.</p>

<p>This version will load existing saved options from earlier versions of <cite>WinEd</cite>, but choices saved from it will not load back into earlier versions. It is therefore strongly advised to take a backup copy of the files from within the <span class="filename">Choices:WinEd</span> folder if you plan to return to an earlier version of the software.</p>
</div></div>

<ul>
<li>A new <span class="icon">Save templates sorted</span> option to store the windows in alphabetical order in the file.</li>
<li>Improvements to the template sorting algorithm used in <span class="icon">Display templates sorted</span>.</li>
<li>Improvements to the template identifier sanity checks when loading files.</li>
<li>Improvements to the sanity checks on the reserved fields in file headers, so that invalid files from older third-party editors can be loaded with user agreement.</li>
<li>The filetypes of possible application sprite files (those found by proximity to the templates file) are now checked before loading them, to avoid bad sprite file errors.</li>
<li>Choices are now saved in textual format, to simplify future changes and additions to the file contents.</li>
<li>Improvements to the way that <span class="variable">Choices$Path</span> and <span class="variable">Choices$Write</span> are used.</li>
<li>A <span class="icon">Default</span> button in the <span class="window">Choices</span> dialogue to reset the options to their defaults.</li>
<li>The <span class="icon">Round icon coordinates</span> option has returned to <span class="window">Choices</span>, and is no longer paired with <span class="icon">Display templates sorted</span>.</li>
<li>Icon dimensions in the Monitor are updated when an icon is resized using an <span class="key">Adjust</span>-double-click.</li>
<li>Website links have been updated to current download page, to avoid issues with RISC&nbsp;OS.info being offline.</li>
<li>Overhaul of the documentation, including a replacement of the text version of the manual with one matching the HTML documentation and the addition of the recent version history.</li>
</ul>

<h3>44.2. Version 3.26 (29 August 2020)</h3>


<ul>
<li>Fix a problem when loading templates whose names contain a % character, introduced in 3.20.</li>
<li>Fix problem which left a window icon in the file <a href="#browsers"><span class="window">Browser</span> window</a> when deleting an open window, introduced in 3.10.</li>
<li>Fix problems with the handling of unsaved files during an aborted Desktop Shut-Down, which prevented <cite>WinEd</cite> from subsequently being quit.</li>
<li>Disable all keypresses aside from <span class="key">Escape</span> during drag operations, to avoid unexpected side effects.</li>
<li>Check that there is a selected window in the template <a href="#browsers"><span class="window">Browser</span></a> before attempting to operate on it.</li>
<li>Improve interactive help messages throughout the application.</li>
<li>Correct the behaviour of radio icons under <span class="mouse">Adjust</span> clicks.</li>
<li>Re-implement the <span class="window">icon export</span> dialogue, resolving reported issues and adding <code>typedef</code> enum and <code>#define</code> options, optional name prefix, case conversion and invalid character substitution.</li>
</ul>

<h3>44.3. Version 3.25 (28 July 2020)</h3>


<div class="callout warning">
<div class="heading">Warning</div>

<div class="content">
<p><cite>WinEd</cite>&nbsp;3.25 adds a new configuration option. It will load existing saved options from earlier versions of <cite>WinEd</cite>, but choices saved from them will not load into earlier versions including 3.20 and 3.23. It might be advisable to take a backup copy of the files from within the <span class="filename">Choices:WinEd</span> folder if you plan to return to an earlier version of the software.</p>
</div></div>

<ul>
<li>Resolve numerous additional NULL pointer dereferences in the menu handling code.</li>
<li>Stop the overwrite check when files are saved to <span class="variable">Wimp$Scrap</span> as part of the Data Transfer Protocol.</li>
<li>Add a <span class="icon">Cancel</span> button to the <span class="window">Resize Icons</span> dialogue.</li>
<li>Replace the arrows in the <span class="window">Align Icons</span> dialogue with &ldquo;left&rdquo;, &ldquo;right&rdquo;, &ldquo;up&rdquo; and &ldquo;down&rdquo;.</li>
<li>Allow the default action in the <span class="window">Icon Edit</span> dialogue to be switched to updating the icon data without changing the icon&rsquo;s dimenstions, using a new option in the <span class="window">Choices</span> dialogue.</li>
<li>Improve window scrolling, taking into account the contents of the <a href="#browsers"><span class="window">Browser</span></a> and the statistics windows and supporting extended scroll requests when available. This includes the templates being edited, and for previews if such requests are enabled in the template.</li>
<li>Ensure that template strings are correctly zero-terminated when passed to the debug logging system.</li>
<li>Disable cursor key movement of selected icons during drag operations, to prevent the two interfering.</li>
<li>Standardise the capitalisation of validation commands in the Icon Picker.</li>
<li>Make the <a href="#browsertool"><span class="window">Browser</span> toolbar</a> fill the complete width of the <a href="#browsers"><span class="window">Browser</span> window</a> in large screen modes.</li>
<li>Correctly set the <span class="icon">Max text length</span> field in the <span class="window">Edit icon</span> dialogue box for indirected, sprite-only icons.</li>
<li>Limit ESG values to the range 0-15, in line with the changes made for Ursula.</li>
<li>Ensure that the <span class="window">Save As</span> dialogue closes after a save triggered by closing an unsaved file.</li>
</ul>

<h3>44.4. Version 3.24</h3>


<p>This version number was skipped, due to the possibility that it had been used for some limited-release test builds at some stage in the past.</p>

<h3>44.5. Version 3.23 (17 June 2020)</h3>


<ul>
<li>Resolve a significant NULL pointer dereference in the menu code, which made the application almost unusable with a High Vector ROM.</li>
</ul>

<h2 id="bug">45. Bug reports &amp; suggestions</h2>


<p>Although every effort has been made to iron out bugs, no application is completely bug free so you are advised to save your work regularly. Please report any bugs that you find to Steve Fryatt at <a href="mailto:info@stevefryatt.org.uk">info@stevefryatt.org.uk</a>.</p>

<h2 id="acknowledgements">46. Acknowledgements</h2>


<p><cite>WinEd</cite> was originally written by Tony Houghton in C (compiled by <cite>Acorn&nbsp;C</cite> Release&nbsp;5) with extensive use of <a href="http://www.riscos.info/index.php/DeskLib" class="external"><cite>DeskLib</cite></a>. This version has been compiled using the <a href="http://www.riscos.info/index.php/GCCSDK" class="external"><cite>GCCSDK</cite></a>. <cite>DeskLib</cite> is a set of Freeware C libraries written by Jason Williams and many others. All C programmers should consider this an essential replacement for <cite>RISC_OSLib</cite>.</p>

<p><cite>Dr Smith&rsquo;s C Development Toolkit</cite>, written by Julian Smith and marketed by WSS, was helpful for debugging in early versions.</p>

<p>The text editor used was <cite>Zap</cite>, an excellent PD program written by Dominic Symes with extensions by several other skilled programmers.</p>

<p>The templates were initially created with <cite>TemplEd</cite>, a PD template editor and <cite>WinEd</cite>&rsquo;s main rival. <cite>WinEd</cite> is intended to improve on it in every aspect.</p>

<p>This manual (in both its HTML and plain-text forms) has been created from a single XML source using <a href="https://github.com/steve-fryatt/xmlman" class="external"><cite>XMLMan</cite></a>.</p>
</div></div>
<div id="foot"><div id="foot-liner">
</div></div>
</body>
</html>
