RISC DISC 1

home *** CD-ROM | disk | FTP | other *** search

/ RISC DISC 1 / RISC_DISC_1.iso / pd_share / code / templed / !TemplEd / Manual < prev next >

Wrap

Text File | 1994-09-06 | 27.0 KB | 667 lines

TemplEd User Manual ------------------- 1. About TemplEd ________________ TemplEd is a template editor. With it, you can create and edit Template files, which contain definitions of the windows used by an application. It is therefore only useful for people who write programs that run in the desktop. If you want to know what can be in template definitions, and how they can be read by a program, read the information about the SWIs Wimp_CreateWindow, Wimp_CreateIcon and Wimp_LoadTemplate. This can be found in the RiscOS PRM (Programmer's Reference Manual), and on-line in Guttorm Vik's !StrongHlp application. TemplEd is FreeWare. For conditions of use, read the copyright notice at the end of this manual. 2. About this manual ____________________ If you are an experienced user, the !Help file will probably contain enough information for you to get started. You may want to skip the boring discussion of TemplEd's operation that follows. However, there are some technical details that may be of interest. These have been marked with <TD>. There is also a list of operation shortcuts and "hidden" features at the end of this manual. 3. Starting the program and loading files _________________________________________ After you have double-clicked on the application, the program installs itself on the icon bar. A double-click on a Template file also starts TemplEd, after which TemplEd loads the file. You can load a template file by: * Double-clicking on a Template file. If TemplEd is running and has not loaded any templates, it loads the file. Otherwise, a new copy of TemplEd is started. * Dropping the file on the TemplEd icon on the icon bar. TemplEd deletes the currently loaded templates, and loads the new file. If the current templates have been modified, TemplEd first asks you to confirm before deleting them. * Dropping the file in the Templates window. TemplEd adds the templates in the file to the currently loaded ones. If the file is called "Templates", then TemplEd will look for a sprite file called "Sprites" in the same directory. If there is such a file, TemplEd will assume that it contains the sprites to be used with the templates, and automatically loads the sprite file as well. Other sprite files with sprites used in the templates, can be loaded by dropping them on the icon bar icon. When you drop an application on the icon bar icon, TemplEd will load the file "Templates" in the application directory (if present). If there is a sprite file called "Sprites" in that directory, TemplEd will also load it. 4. Opening and closing a template window ________________________________________ A click with Select on the TemplEd icon on the icon bar opens the Templates window. This lists the currently loaded templates. A small window icon before the name indicates what type of window it is (scrollbars, title). A yellow background of this icon means that it is currently open. You can open a template by double-clicking on its name. If the template was already open, it is closed. The "Open" and "Close" entries in the menu serve the same purpose. 5. Selecting icons __________________ Many operation on icons can be done on a single icon but also on a selection of icons. There are several ways to select (and deselect) icons: * Click with Select to select a single icon while deselecting the others. A click on the background of the window clears the current selection. * Click with Adjust to select an icon, without changing the rest of the selection. If the icon was already selected, it is deselected. * A drag with the mouse creates a drag-box in the window area. When you release the mouse button, all icons within the box are selected. * There are "Select all" and "Clear selection" items in the menu. <TD> Like most other template editors, TemplEd creates a window for each template, and creates icons exactly as they have been defined. This means that the Wimp reacts to the mouse just as it would when a program was using the template. That's why a menu icon is hard to select: you can click on it, but if you move the pointer away from the icon, the icon is deselected again. The Wimp also interferes if you want to select several radio buttons from the same ESG. Even if you click with Adjust, the Wimp deselects the other buttons (unless their 'Allow adjust' bit is set). You can select these "difficult" icons with a drag-select. <TD> If you want to check the behaviour of icons to mouse clicks, without TemplEd reacting to the clicks, press a combination of keys (e.g. Shift + Alt) while clicking. That way you can check if the ESGs of radio buttons are set right, if option buttons are switched on and off, etc. 6. Moving and resizing icons ____________________________ To move an icon or a selection, click inside the window with Select while holding down the Shift key. An outline appears around the icon(s) that moves with the pointer until you release the mouse button. During the operation, the pointer shape is changed to a hand. To resize an icon or a selection, click on it with Shift+Adjust. A "rubber box" drag is started, allowing you to move one side. The side that is moved is the one that was nearest to the pointer when you clicked. It is also indicated by the pointer shape. Though a resize operation will usually be done on a single icon, it is possible to resize more than one icon at a time; the icons are scaled according to the size of the drag-box. An alternative way to move or resize icons is by clicking on them without using the Shift key, and keeping the mouse button pressed for about half a second. During the drag, you can move the pointer with the cursor keys. The left, right, up and down keys move the pointer 1 pixel (in the expected direction). If you press a cursor key in combination with the Shift key, the movement is 4 times as fast. Pressing the cursor keys without starting a drag first moves the selected icons. 7. The "Icon Edit" dialogue window __________________________________ Except for size, position and number, all properties of an icon can be set from the "Icon Edit" dialogue window. To open this window, click with Shift+Menu, or choose the "Icon ⇨ Edit..." entry in the menu. Icon flags can be set by clicking on the buttons, text and sprite names can be entered in the appropriate fields. Use the up and down arrow keys to move the cursor around. Some fields (e.g. button type, colours, font name) can contain a limited number of values. These can be selected either by clicking on the arrow icons to the left and right, or by clicking a mouse button while the pointer is over the field. This pops up a menu from which you can select a value. <TD> The "1:1" button for the font is the only button not connected to an icon flag. When on, it keeps X and Y size of the font equal, so you don't have to set them both. The changes to the icon only take effect if you press the "Update" icon. "Exit" closes the window, leaving the icon as it was since the last update, and "Update & Exit" combines the two. <TD> If the indirected text that you entered is longer than the "Max size" field allows, TemplEd automatically increases the maximum. It also sets the "Indirected" flag if the text or sprite name uses more than 12 characters. When you edit a selection of icons, not all fields can be modified (to be exact: only the icon flags). The unchangeable fields are shaded. When you press "Update" or "Update & Exit", the changeable fields are modified in all selected icons. In some cases, you may only want to change one field (e.g. set the button type of all icons). To do this, click Menu above the "Update" or "Update & Exit" button. A menu pops up from which you can select the flags that must be changed. 8. Moving and resizing windows ______________________________ Usually, you can move a window by dragging the title bar, and you resize it by dragging its resize icon. But some windows don't have a resize icon, and some don't even have a title bar. You could of course edit the windows, give them a title bar or resize icon, and remove these when you are done. But in TemplEd, it is also possible (and much faster) to move and resize windows directly. Use Ctrl+Select to move a window, and Ctrl+Adjust to resize it. The work area of the window can also be resized with the mouse, with Ctrl+Alt+Adjust. When you release the mouse button, the work area is set so, that it stretches to the bottom-right corner of the visible part of the window. <TD> To enable the work area to expand, it is made very large at the start of the drag. This is visible if your window has a scroll bar. At the end of the drag, the area is shrunk again to the desired size. Just as with moving and resizing icons, the cursor keys can be used during the drag to position the mouse pointer. 9. The "Window Edit" dialogue window ____________________________________ Editing the data of a window is split in two parts. Flags, colours and button type are edited in the "Window Edit" dialogue window. This window is opened when you click Ctrl+Menu over the window, The contents of the title bar are edited separately, using the "Icon Edit" window. It is accessible with a Shift+Menu click while the pointer is over the title bar. Both dialogue windows can also be opened from the menu. <TD> The "transparent" colour number 255, that has a special meaning as the title foreground colour or as the work background colour, is only selectable from the colour menu, not by clicking on the arrow icons. 10. TemplEd's menus ___________________ Most entries in the menus ought to speak for themselves. Some others may take a small explanation: 10.1 The "Window" menu Create ⇨ Leads to a submenu with a number of standard icons. Selecting one of these creates such an icon, at the position that the pointer was on when the menu was popped up. Selecting the "Create" entry itself is equal to selecting the first standard icon from the menu. You can change the set of standard icons, see the section "Customizing" at the end of this manual. <TD> The new icon will be positioned so that its bottom-left corner is at the position where the pointer was when you popped up the menu. Icon/Selection ⇨ Renumber ⇨ You can renumber single icons or selections. When a selection is renumbered, the icons are numbered from top to bottom and from left to right. <TD> It is not possible to give an icon a number that is equal to or higher than the number of icons in the template. If for instance there are 10 icons, they are always numbered from 0 to 9. You may enter a higher number but TemplEd will decrease it to 9. (In fact, what TemplEd does when renumbering is swap the definitions of two icons: the one that you want to renumber, and the one carrying the new number.) <TD> After renumbering an icon, TemplEd increases the new number by one and stores it. You can see this the next time you open the menu. This feature comes in handy when you renumber using Alt+Select (see "Shortcuts") Icon/Selection ⇨ Align ⇨ Changes the selected icons so that they are lined up. There is a choice of aligning the left-hand sides, right-hand sides, top, bottom, and the centres (in either the horizontal or vertical direction). The icons can be either moved or resized. When resized, the coordinates of the icons stay the same except for the side that must be aligned. <TD> As an anchor for aligning, the outer icon is chosen. For horizontal aligning this is the leftmost icon, for top aligning the topmost, etc. This ensures that if the icons were inside the visible area before the aligning, they will remain fully visible afterwards (except for some cases when you align the centres). Icon/Selection ⇨ Space out ⇨ Moves the selected icons so that there is a constant space between the icons. You can choose between horizontal and vertical distribution, and between setting a fixed space and using the available space between the outer icons. For example: Suppose you have four icons, positioned ----- ------- --- --- | A | | B || C | | D | ----- ------- --- --- Using a fixed space gives you something like ----- ------- --- --- | A | | B | | C | | D | ----- ------- --- --- and choosing "Use available" results in ----- ------- --- --- | A | | B | | C | | D | ----- ------- --- --- <TD> Before doing a Space out operation, TemplEd sorts the icons on their minimum coordinate. This means that the leftmost (or bottommost) icon always remains in place. It also means that if some icons have equal minimum X (or Y) coordinates, they may end up in any order. <TD> Both the "Align" and the "Space out" operations change the position of icons in only one direction. So if you do a horizontal Space out, the Y coordinates of the icons remain the same. Icon/Selection ⇨ Min. size Minimizes the size of icons, keeping their bottomleft corner at the same position. <TD> It is very complicated to calculate the minimum size correctly, especially for icons with outline fonts, 3D borders or multi-line text. The procedure used may not always give the best results. Icon/Selection ⇨ Center Centers the icon (or icon selection) in the window, relative to the area that is currently visible. Icon/Selection ⇨ Same size Sets the size of the selected icons to be equal to the topleft one. The bottomleft corner is kept at the same position. Work area ⇨ Leads to a window in which you can set the dimensions of the window work area. The "Minimize" button limits the work area to the maximum coordinates that are currently visible. The "Maximize" button sets the minimum size equal to the current window size. The "Default" button resets all values to those of a standard full-screen window. Misc ⇨ Sprite area Enables you to choose from which sprite area the sprites in the template are read. This can be either the Wimp area or a private area that is created when you drop a sprite file on the TemplEd icon. <TD> When saving templates, TemplEd always sets the sprite area to 1 (i.e. the Wimp area). If your program is using a private sprite area, it will have to re-direct the sprite area pointers after it has loaded the template. Misc ⇨ Ensure icons ⇨ From this submenu, you can let TemplEd check the position of the icons, and move them if needed. The first item in the submenu make sure that all icons are within the work area, the second ensures that they are in the currently visible part of the window. Misc ⇨ Deleted icons ⇨ Normally, when you delete an icon, it is only marked as deleted. Most of the icon data is retained, and the numbering of the other icons stays the same. If, later on, you create an icon, it may get the number of a deleted icon. Until that time, it is possible to "undelete" the icon. From this submenu, you can: * Undelete the deleted icons (e.g. if you accidentally deleted them) * Undelete them and move them outside the work area. This can be handy if you want to avoid that the icon numbers are used again when you edit other icons * Purge the deleted icons, so that there are no gaps in the numbering Note that for indirected icons, the indirected data can not be retrieved. 10.2 The icon bar menu Options... Opens a window in which you can set a number of options: * Double click starts edit When on, TemplEd reacts to double-clicks on icons, window title bar or background, by opening the appropriate Edit window. * Support 'Interface'/'AEH'/'WimpExt' module Provides limited support for one of these modules, by making the appropriate calls for redrawing icons. The modules provide a number of enhancements to the Wimp, among which icon borders with 3D look. Addresses of the people who made these modules are listed at the end of this file. <TD> Support is limited to redrawing icons, including selecting and deselecting them upon a click. Other features are not supported. * Allow duplicate template names If this option is off and a template is added with a name that already exists, the old template is deleted. Renaming a template to an existing name will also be refused. * Hatch user-redrawn templates When on, the background of windows of which the "Auto-redraw" flag is cleared, will be shown with a cross-hatch pattern. * Show icon info Enables or disables the Icon info window that shows information on the icon that the pointer is currently over. * Save icons as unselected When on, TemplEd stores all icons as unselected when you save any templates. Otherwise, the "selected" state of icons is saved with the rest of the data to the file, and when your program uses the templates, it will have to make sure that the correct icons are selected. * Delete icons moved outside If you move icons, and drop them outside a template window, they will be deleted if this option is on. When off, nothing happens to the icons. This option allows for fast deletion of icons. * Min. size: Ignore desktop font This option is only meaningful if you are working under RiscOS 3.50 or later, where you can use an outline font for the desktop. If the option is off, and TemplEd is calculating the minimum icon size, it takes the text width in the Desktop font. However, that width may not be enough for other users, who use a different font. That ruins the layout. With this option on, TemplEd takes the text width for the system (BBC) font, which is usually wider than outline fonts. * Grid Locks the position of icons that are created or modified to a grid (as in !Draw). This makes it easier to get icons lined up properly. The grid size can be set by clicking on the arrow icons. There are two grids: - Icon size grid Locks all four corners of an icon, so that its size will be a multiple of the grid size - Icon position grid Locks only the bottomleft corner of the icon; this can be handy if you want to keep icons lined up, but want to keep their sizes unchanged Normally, the Icon position grid will be at least as large as the Icon size grid. <TD> If you are working in a high-resolution screen mode, it is advisable to use at least an Icon size grid of 2x4, so that your templates look the same in medium-resolution modes (like 12 and 15) <TD> TemplEd automatically adjusts the grid size in case of a mode change; the grid size must be at least equal to the number of OS units per pixel. The "Save & Exit" button stores the current settings to a file in the application directory, then closes the window. The "Exit" button just closes the window. Statistics... Opens the statistics window, showing the amount of memory that the templates will need if you use them in a program. The amounts can be shown in decimal or hexadecimal numbers. <TD> Note that the statistics window does not change as you modify your templates. The figures are re-calculated only when the window is opened or when you click on the "Decimal" or "Hex" buttons. Custom sprites ⇨ View/Edit "Run"s the file with the custom sprites that your templates are using. This normally means that !Paint will load the file. Custom sprites ⇨ Re-load Reads the sprite file again, e.g. after you have edited it with !Paint. Custom sprites ⇨ Reset Removes the sprites from memory; the templates will use the sprites from the Wimp area. 11. Shortcuts _____________ * Opening the Icon Edit and Window Edit windows can be done from the menu, but a faster way is to click on them while pressing a key. Shift+Menu opens the Icon Edit window. Ctrl+Menu opens the Window Edit window. To edit the title bar icon, click Shift+Menu on the title bar. * The Edit windows can also be opened with a double-click with the Select button. Double-clicks on an icon, on the background of a window, or on the title bar open the appropriate Edit window. This only works if the corresponding option is on. * Inside the Icon Edit and Window Edit windows, pressing the F2, F3 and F4 keys has the same effect as clicking on the Update, Update&Exit and Exit icons, respectively. The Escape key has the usual function which is exiting without doing anything. Escape works not only in these two cases, but in all windows with writable icons, such as the Save, Space Out and Options windows. * Many operations on icons can also be done with a control-key: Ctrl-A Select all Ctrl-C Copy selection Ctrl-D Copy icons downward Ctrl-E Edit selection Ctrl-J Open "Align" box Ctrl-K Open "SpaceOut" box Ctrl-L Copy icons to left Ctrl-Q Close window (Ctrl-F2 works, too) Ctrl-R Copy icons to right Ctrl-T Edit title bar Ctrl-U Copy icons upward Ctrl-W Edit window Ctrl-X Delete selection Ctrl-Z Clear selection (This only works if the window has the input focus, of course) * Renumbering icons can also be done faster. Click Alt+Select on an icon, and the icon gets the number that is visible when you open the "Icon ⇨ Renumber" menu. After the renumbering, this number is increased by one, so you can number the icons sequentially by clicking on them one by one. A click with Alt+Adjust does the same, except that the number is decreased after the renumbering. * A fast way to delete icons is by moving them outside the template. (This only works if you have set the "Delete icons moved outside" option on.) 12. "Hidden" features _____________________ TemplEd has a number of features that may not be immediately visible, but can come in handy. (That's not counting the bugs ;-) * It is possible to copy icons to other templates; just move the icons and drop them into the other template. This makes it easy to use icons from other templates. * Extended icon info. When TemplEd starts, the Icon info window is small, showing only the name of the template and number of the icon that the mouse is over. If you click on the "toggle size" icon, it becomes full size and also shows the dimensions of the icon plus the mouse position in window coordinates. Still more icon info can be gotten from !Help, Acorn's interactive help application. Open the help window, and move the pointer over an icon. * Fine-tuning when moving and resizing icons and windows is possible with the cursor keys. The up, down, left and right keys move the pointer 1 pixel (or 4 pixels, if Shift is pressed). * Pressing Esc during dragging (icon move, resize, etc.) aborts the operation. * In the Icon Edit window, clicking Adjust on "Max Size" (the text itself, not the writable icon) minimizes the value of the "Max Size" field. * Closing the Templates window with the Adjust button opens a Filer window of the parent directory of the file you are editing. Shift+Adjust also opens the Filer window but does not close the Templates window. (This is, in fact, standard Acorn practice for editor-like applications.) 13. Customizing _______________ Apart from setting the options, you can also customize TemplEd's menu of standard icons. Load the file "Templates" in the application directory into TemplEd. The template "StdIcons" contains the definitions of the standard icons. TemplEd loads them at program startup. You can change these definitions to your liking, but bear the following in mind: * There are "name" icons that contain the text of the menu entries. They must be indirected-text icons, with their ESG set to 31. * The other icons contain the definitions. These MUST have a different value for the ESG (i.e. 0-30). TemplEd links them to the "name" icon with the number preceding them. For instance, suppose icons 0 and 3 are "name" icons. This means that icon 1 and 2 are taken as a group belonging to icon 0. When you select the text in icon 0 from the "Create icon ⇨ " submenu, these two icons will be copied to your template window. For those who like windows with 3D-look, there is an alternative set of templates and sprites. To make TemplEd use them, rename them to the default "Templates" and "Sprites", after you have given the standard "2D" files a different name. (Note: you need Risc OS version 3.10 or later to get the 3D effect.) Alternatively, run the "Use3D" Obey file in the "Extras" directory; run "Use2D" to switch back to standard templates. 14. Credits ___________ Although the edit-dialogue windows are my own idea, not all features implemented in TemplEd are. Some have been borrowed from RiscForm (the version of !FormEd by The Risc Squad), some from Jonathan Marten's excellent !DrawPlus (notably the Align and Space Out windows). Martin Ebourne made the hires sprites file (!Sprites22). The MenuUtils module which TemplEd uses was written by Alex Petrov. TemplEd has also been much improved by the testing, comments and suggestions of Stephen Burke, Martin Ebourne, Michael Ellis, Edwin Hautus, Paul Hobbs, Rupert Johnson, Merlin Hughes, Olaf Krumnow, Paul Lebeau, Ian Palmer, John Pullan, Niklas RÖjemo, John Tytgat, Julian Wright, and I'm sure I forgot some others. 15. Copyright notice ____________________ This program is FreeWare. This means that I retain the copyright. You may freely copy and distribute it, provided that it is complete with all original files, and that you do not sell it. PD libraries may charge a nominal fee for the cost of duplication, postage etc. When you use the program, you do so entirely at your own risk. You may change the program to suit your own needs. If it's a bug fix, or if you think it's an improvement, then please send the changes to me at the address below. The MenuUtils module is © Alex Petrov. 16. Addresses ------------- Here are contact addresses for software used by or supported by TemplEd Note that these are the most recent that I know, so they may be out of date. The MenuUtils module (PD): Alex Petrov Bld. 1, Flat 107 Kavkazsky boulevard, 29 Moscow 115541 RUSSIA. (E-mail: APetrov@misis.msk.su) The Interface module (PD): SoftWare Interrupt Developments. 40 Castle Ings Gardens, New Farnley, LEEDS, LS12 5EG UK. The AEH module (Shareware): Andrew Hersee The Red House Tallington Nr.STAMFORD Lincs. PE9 4RP UK. (E-mail: ahersee@warwick.ac.uk) The WimpExt module (PD): Jon Ribbens 39 Nutkins Way Chesham Bucks. HP5 2BE UK. StrongHelp (commercial, part of the StrongEd package): Stallion Software Ltd. Arundel House Arundel Road Camden Bath BA1 5JX UK. 17. Finally ___________ If you have any questions, bug reports or suggestions for improvements, you can contact me at the following address: Lijnslagerstraat 204 NL-5625BP Eindhoven The Netherlands or by e-mail: wsinda@info.win.tue.nl (valid until 15-Sep-94) Dick Alstein