Amiga Format CD 16

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

/ Amiga Format CD 16 / amigaformatcd16.iso / -in_the_mag- / top100_shareware / workbench / stickit2 / docs / stickit2.txt < prev next >

Wrap

Text File | 1994-08-02 | 26KB | 707 lines

StickIt2, the Amiga sticky note reminder program. Copyright (C) 1993,1994 Andy Dean. Welcome to StickIt2, the Amiga sticky note reminder program! This document applies to version 2.00, written on 1st August 1994, Copyright (C) 1993,1994 Andy Dean. Copying and distribution details ******************************** Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. No guarantee of any kind is given that the programs described in this document are 100% reliable. You are using this material at your own risk. The author *can not* be made responsible for any damage which is caused by using this program. This package is freely distributable, but still copyright by Andy Dean. This means that you can copy it freely as long as you don't ask for a more than nominal copying fee. Permission is granted to include this package in Public-Domain collections, especially in the excellent Fred Fish Amiga Disk Library (including CD ROM versions of it). The distribution file may be uploaded to Bulletin Board Systems or FTP servers. If you want to distribute this program you must use the original distribution archive StickIt-2.00.lha. This program or the source code (or parts of it) may not be included or used in commercial programs unless by written permission from the author. Requirements ************ StickIt2 will run on any Amiga equipped with AmigaDos 2.04 and above. It requires no third-party libraries, and will work with the non-scalable diskfont library (version 36) although you won't get scalable fonts then :-). What is StickIt? **************** StickIt2 is a replacement for the good ol' Post-It note. It allows you to stick notes on your screen which will be displayed every time you reboot; useful to remind you of things to do. StickIt2 was written with a job to do... to replace all the bits of paper I used to leave around to remind me to do something. I have tried to write a program to do that with the minimum of fuss and with a nice clean Workbench 2 interface. I have tried to make the program configurable enough for each user's needs, without over-doing it. I have tried to incorporate as many of the suggestions made by others in response to the earlier StickIt-1.03. An example StickIt2 setup ========================= I suggest that the truly organised StickIt2 user should drop the program into their `WBStartup' directory so that they can be reminded every time they re-boot their machine. To do this, simple drag the program's icon into the `WBStartup' directory of your boot partition. Run the program and it should warn you that there is no `StickIt2.notes' file (see Configuring to see how to change the default notefile). After clicking on `Ok', the commodities window should popup. To create a blank `StickIt2.notes' file, press `Right Amiga + S'. StickIt2 is now ready to use. You can add some notes immediately or you can close the commodities window, keeping the program in the background ready for use. To bring back the commodities window, press `Left Alt + Left Shift + S'. See Configuring, for more information on customising the program for your own use. Program features **************** StickIt version 2.00 supports the following features: * StickIt2 can have up to 100 notes in use at any time. * StickIt2's notes can be in any colour. * StickIt2's notes can use any font in any colour, size and style. Each note can have its own font. * StickIt2's notes are directly editable (like typing text into a word processor). * StickIt2's notes are resizable using a discrete hidden resize gadget. * StickIt2's notes can open on any public screen. * StickIt2 runs as a commodity. * StickIt2 uses the system clipboard. * StickIt2 can be run from either Workbench or the CLI with full tooltype support in both cases. * StickIt2 has a font sensitive GadTools interface designed with the excellent "The Designer". See Credits. * Documentation in plain ASCII and AmigaGuide formats. * StickIt version 2.00 is only 7k larger than StickIt-1.03. The limits imposed by the program are: * The note may only contain 4k of text (just over 4,000 characters). * The title bar may only contain 128 characters of text. How to use the program ********************** Starting the program is easy! To start StickIt2 from the Workbench, simply click on its icon. To start the program from the CLI, just type `StickIt2' in a shell window. The program doesn't auto-detach itself from the shell, to do this start it with `run StickIt2'. The default setup should open a couple of `welcome' notes and also pop up the commodities window. Editing the notes ***************** Unlike the last version of StickIt, the notes under StickIt2 are editable directly. To do this, just click on the text in the note and a carat(1) will appear at that position. Text entry will then be familiar to word-processor users. The cursor keys will move the carat around the text and the text around the carat can be deleted with either the DEL or BACKSPACE keys. If the user enters text such that it cannot all fit into the note, the cursor is positioned at the end of the text in the note, and the text will be entered as normal - only the user will not be able to see it. To remove the carat from the note, simply click off the note (i.e. on the Workbench backdrop) or press RETURN. Resizing a note =============== StickIt2 allows the user to resize the notes to allow more or less text to be entered than is possible in the default size note. As a standard resize gadget would be unsightly and spoil the appearance of the note, a hidden resize gadget is used in StickIt2. This resize gadget works in exactly the same way as the standard gadget and is located in the same place (bottom right) in the window. See the diagram `Resize.ilbm', located in the `Docs' directory, if you are unsure. Hiding a note ============= To hide a note from view, click on the close gadget. This doesn't actually delete the note, simply hides it from view. To re-open the note, use the commodities window (see Commodities window). Note menu options ================= Each note has a menu of commands available to it by pressing the right mouse button. There are two sub-menus - `Project' and 'Edit'. Project sub-menu ================ `Save', keyboard shortcut: `Amiga-S' ------------------------------------ This saves all the current notes' information to the notefile. See Configuring, for information on how to rename this file. The notes' position, size, font, colours etc... are saved in the file. The only thing that isn't saved in the file is the information about whether the note is currently hidden. This means that when the user re-opens the file, all notes are shown. `Commodities Panel', keyboard shortcut: `Amiga-P' ------------------------------------------------- This calls up the main commodities window where the notes properties can be changed (see Commodities window). Edit sub-menu ============= StickIt2 supports the Amiga's clipboard with the use of standard cut, copy and paste commands. `Copy', keyboard shortcut: `Amiga-C' ------------------------------------ `Copy' is used to copy all of the current note's text into the system clipboard buffer. The text in the note remains unchanged. `Cut' keyboard shortcut: `Amiga-X' ---------------------------------- `Cut' also copies all the current note's text into the system clipboard, but then deletes the text in the note. `Paste', keyboard shortcut: `Amiga-V' ------------------------------------- `Paste' copies the contents of the clipboard into the note. The pasted information can be altered slightly in order for it to be editable in the note. All RETURN and TAB characters are converted into SPACE characters, to keep the text editable within the note. It is important to remember this because if the text is then copied back into the clipboard, these RETURN and TAB characters will have been changed into SPACE characters. `Delete', keyboard shortcut: `Amiga-B' -------------------------------------- `Delete' simply deletes the current note's text. The clipboard is not used in this operation. ---------- Footnotes ---------- (1) A `carat' is just another name for a `cursor' The commodities window ********************** The commodities window is called up by either: 1. Pressing the keyboard shortcut, by default this is Left Alt + Left Shift + S. 2. Selecting `Commodities panel' from the note menus. 3. Using Commodore's `Commodities Exchange' program and pressing the `Show' gadget. The purpose of the commodities window is to alter the notes' properties (font, colour etc...). Any of the gadgets functions in the commodities window can be selected by pressing the keyboard shortcut key, indicated with the underlined letter. The commodities window is opened on the default public screen. This is not the same as the `PUBSCREEN' tooltype. The default public screen is usually Workbench, but it can be changed by one of the many freely distributable public screen utilities. The commodities window gadgets ============================== The notes list -------------- On the left of the commodities window is a list of all the current notes in memory, listed in reverse order of opening. This means that the notes at the top of the list are opened last, and therefore can overlap notes lower down the list. To open a hidden note or force a note to the front, double-click on its entry in the notes list. To select a note in the notes list, either click on the entry in the list or click on the note itself. Once a note is selected, it can be moved up or down by using the `Up' and `Down' buttons below the list. This is useful if you want to force a note to open on-top of another or behind all the others. A selected note can also be deleted permanently by clicking on the `Del' button. Creating a new note is done with the `New' button; the new note inherits the default properties chosen by the tooltypes and is placed at the top of the list. The title bar text ------------------ To change the text to be shown in the title bar of the note, the user can type into the `Title bar' text gadget. Note colours ------------ The user can select the note background colour and text colour with the `Note colours' gadgets. The cycle gadget chooses either the background colour or text colour, and the palette gadget shows the current colour. To change either of the colours, simply click on the colour in the palette gadget. Note font --------- The current note's font and size is shown next to the `Font...' button. To change it, select the `Font...' button and a standard font requester will appear. After selecting the font for the note, the choice will be shown next to the `Font...' button and the note will be redrawn with the new font. Public screen ------------- By default, all notes open on the screen specified by the `PUBSCREEN' tooltype (usually Workbench). To force the note to open on another public screen, type the screen's name in this text gadget. The public screen name is case sensitive, so the public screen name `TERM' is not the same as `Term' for example. Commodities window menu options =============================== The commodities window has a menu of commands available to it by pressing the right mouse button. There are two sub-menus - `Project' and 'Notes'. Project sub-menu ================ `Save', keyboard shortcut: `Amiga-S' ------------------------------------ This saves all the current notes' information to the notefile. See Configuring, for information on how to change rename this file. The notes' position, size, font, colours etc... are saved in the file. The only thing that isn't saved in the file is the information about whether the note is currently hidden. This means that when the user re-opens the file, all notes are shown. `About', keyboard shortcut: `Amiga-?' ------------------------------------- Brings up information about the program, including the current keyboard shortcut to bring up the commodities window. `Hide', keyboard shortcut: `Amiga-H' ------------------------------------ This will close the commodities window. If the user has changed any data they will be warned before the window closes, unless the tooltype `HIDEWARN=NO'. `Quit', keyboard shortcut: `Amiga-Q' ------------------------------------ Quits the program, removing it entirely from memory. The user will be warned if they need to save any data before the program quits. Notes sub-menu ============== `New note', keyboard shortcut: `Amiga-N' ---------------------------------------- This is the same as clicking on the `New' button; the new note inherits the default properties chosen by the tooltypes and is placed at the top of the list. `Delete note', keyboard shortcut: `Amiga-D' ------------------------------------------- This is the same as clicking on the `Del' button - the selected note is deleted permanently. `Redraw notes', keyboard shortcut: `Amiga-R' -------------------------------------------- If the user changes the order of the notes in the listview, they can see the effects by forcing StickIt2 to reopen all the notes as if it had just started up. This is useful if you intend to overlap notes on the screen. Configuring StickIt2 with the tooltypes *************************************** StickIt2 uses the Amiga tooltypes to configure the program. If StickIt2 is run from the Workbench it will read the tooltypes from the icon; if it is run from the CLI the tooltypes can be passed as arguments to the program. Upon startup, the program will read the tooltypes and this will determine how the program is to be set up. Editing the icon's tooltypes ============================ To edit the tooltypes in the StickIt2 icon, click on the icon and select `Information' from the `Icons' sub-menu on Workbench. A window should pop up with a list showing the current tooltypes. IMPORTANT: Any tooltype in brackets, `(' and `)', is commented out and ignored by the program. For example NOTEFILE=Work:StickIt2/StickIt2.notes would set the current notefile to `Work:StickIt2/StickIt2.notes', whereas (NOTEFILE=Work:StickIt2/StickIt2.notes) would be ignored and the default notefile would be used. The original distribution should have all the tooltypes commented out (except `DONOTWAIT', which is required by Workbench and not used by StickIt2 directly). To save the edited tooltypes, click on `Save' in the information window. The new tooltypes will come into effect next time StickIt2 is run. CLI tooltype arguments ====================== As was mentioned previously (see Usage) StickIt2 can also be started from the CLI or Shell. To send tooltypes to the program, you place them after the program name, for example StickIt2 "NOTEFILE=Work:StickIt2/StickIt2.notes" "CX_POPUP=NO" The tooltypes ============= `NOTEFILE', default: `NOTEFILE=StickIt2.notes' ---------------------------------------------- This is the name of the file that will contain all the note information. The default notefile is located in the same directory as the program, but the user may want to change this to `s:StickIt2.notes' for example. Unlike previous versions of StickIt, StickIt2 doesn't *need* a notefile to exist for it to work. If the user selects a notefile that doesn't exist, the program will give a warning upon startup but continue. When the user next selects `Save', this new notefile is written. The notefiles of previous versions of StickIt are not compatible with StickIt2. `NOTEHEIGHT', default: `NOTEHEIGHT=55' -------------------------------------- The height in pixels of the new notes when they are created. `NOTEWIDTH', default: `NOTEWIDTH=100' ------------------------------------- The width in pixels of the new notes when they are created. `BACKCOLOUR', default: `BACKCOLOUR=2' ------------------------------------- The colour of the background of the note. The default colour under the default Workbench setup is white, but if you are using more than a 4 colour Workbench, you are free to choose any number in your palette (I use an 8 colour Workbench and colour 7 is yellow. Therefore, I set `BACKCOLOUR=7'). It should be noted (no pun intended!) that the colours are numbered from 0 upwards. Therefore, a 4 colour Workbench has colours 0,1,2 and 3. StickIt2 now also accepts both the English and American spellings of the word `colour'; i.e. the tooltypes `BACKCOLOUR' and `BACKCOLOR' are identical. `TEXTCOLOUR', default: `TEXTCOLOUR=1' ------------------------------------- The colour of the text in the note. The default colour under the default Workbench setup is black, all the information about colour in the `BACKCOLOUR' sub-section is applicable here. `NOTEFONT', no default ---------------------- The default font to be used in the notes. There is no default given, so notes are given the default system font which is topaz 8. I suggest the use of `Janod' font given away with Commodore's AmigaGuide distribution. `Janod' is a very small but readable font, allowing you to cram lots of info into a small note. I therefore set `NOTEFONT=Janod.font' in my tooltypes. It is important to append a `.font' onto the end of the fontname, otherwise the Amiga won't open the font. `FONTSIZE', default: `FONTSIZE=8' --------------------------------- The default font size in points. `PUBSCREEN', default: `PUBSCREEN=Workbench' ------------------------------------------- This is the default public screen onto which the notes should open. The default screen is Workbench, but the user could open all the notes on a different public screen if they wish. If the chosen public screen is not currently open, the notes are opened on the default system public screen (usually Workbench). The public screen name is also case sensitive, so `PUBSCREEN=TERM' is not the same as `PUBSCREEN=Term' for example. `CLIPUNIT', default: `CLIPUNIT=0' --------------------------------- This is the default clipboard unit that the program uses for all its cuts, copys and pastes. Most programs use clipunit 0, so it is unlikely that you would ever wish to change this. `DELAY', default: `DELAY=0' --------------------------- In order to stop disk thrashing (several programs all trying to access a disk at the same time) StickIt2 can be told to wait a short while after loading before it loads in its notefile. If StickIt2 is placed in the WBStartup on your hard disk, setting `DELAY=5' will produce a delay of 5 seconds which is probably adequate. If StickIt2 is started from a floppy, a larger delay value may be needed. `EMPTYQUIT', default: `EMPTYQUIT=NO' ------------------------------------ If StickIt2 finds that there are no notes in the notefile upon startup, setting `EMPTYQUIT=YES' will make the program quit and free up its memory. The default setting keeps the program resident allowing it to be called up by pressing its hotkey (see later) or using Commodore's `Commodities Exchange' program. `HIDEWARN', default: `HIDEWARN=YES' ----------------------------------- By default, StickIt2 will warn you if you've changed any data and you try and close the commodities window. For those who wish to live dangerously, set `HIDEWARN=NO'. StickIt2 will always remind you that you've changed data if you try and quit the program. `CX_PRIORITY', default: `CX_PRIORITY=0' --------------------------------------- As StickIt2 runs as a commodity, it supports the 3 standard commodity tooltypes. `CX_PRIORITY' lets you set the program's priority compared to other running commodities. Most users will find it unnecessary to change this. `CX_POPUP', default: `CX_POPUP=YES' ----------------------------------- When StickIt2 starts, it will by default show the commodities window. To turn this off, set `CX_POPUP=NO'. `CX_POPKEY', default: `CX_POPKEY=lalt lshift s' ----------------------------------------------- The keyboard shortcut to call up the commodities window is set by `CX_POPKEY'. The default value lets you call up the commodities window by pressing Left Alt + Left Shift + S. `DONOTWAIT' ----------- This is used by Workbench if StickIt2 dropped into the WBStartup directory to run at boot-up. It simply allows the Amiga to continue with the startup even though StickIt2 doesn't return immediately. Known Bugs ********** StickIt version 2.00 has a few known bugs in the program. *None of these are remotely dangerous*, just annoying. * The carat can sometimes be drawn in the border of the note window. This is because the carat is drawn 2 pixels to the right of the actual carat position, and at the end of some lines this goes into the border. Cure: Don't worry about it. * Very small (unreadable) fonts sometimes contain characters so small that the carat doesn't move around properly. Cure: Use a bigger font (what are you doing with 3 point text anyway?). * If you paste a lot of text into a note and the text spills out of the note, the carat is not shown correctly positioned. This is because after the paste, StickIt2 calculates the new position of the carat and as this is out of the note, it doesn't try and move it there. Cure: Resize the note and make it bigger. I'm not going to spend any time removing the annoying note text and carat bugs because the text entry routines will probably need recoding if I am to add "drag a box" type editing. The current routines are not as efficient as they could be. The following are annoying, but worth noting: * Whenever a simple requester is opened (an "Okay" / "Cancel" type), the program effectively stops running until the requester is satisfied. This means that the notes stop being refreshed if they become "damaged". There is no way around this, unless I replace the requesters with windows which is far too much hastle. Note refreshing continues as normal when the font requester is open, as I make use of the ASL requester's callback hook function. * The commodities window always opens in the same place each time, even the if the user moves it before closing it. I could edit the `The Designer's code to stop this, but I don't really want to edit computer generated code. About the Author **************** My address is: Andy Dean Electronic Engineering Dept. University College London Torrington Place London WC1E 7JE England I also have an Internet Email address: `adean@eleceng.ucl.ac.uk' StickIt 2.00 was written using: - `Dice' C compiler, version 2.07.56R (see Credits). - `The Designer', version 1.3 (see Credits). and has been tested on: - Amiga A4000/EC030 + 68882 FPU, Workbench 3.0, 4Mbyte FAST RAM, 2Mbyte CHIP RAM, 130Mbyte IDE hard drive - Amiga A500, Workbench 2.04, 2Mbyte FAST RAM, 1Mbyte CHIP RAM, A590 85Mbyte SCSI hard drive, Microbotics VXL*30 accelerator card (no FAST RAM) - Amiga A1200, Workbench 3.0, 4Mbyte FAST RAM, 2Mbyte CHIP RAM, 85Mbyte IDE hard drive, Power Computing PC1204 (with 20MHz 68882 FPU) Credits ******* I'd like to thank: Matt Dillon for the excellent `Dice' C compiler. Ian O'Conner for the excellent `The Designer' window designer. All the documentation for StickIt2 was done using the freely distributable TeX and `makeinfo' distributions. Thanks to all involved, and those responsible for the conversions to the Amiga. Thanks go out to all the Amiga public domain / freeware / shareware authors for loads of excellent software. I'd also like to thank those who beta tested StickIt2. Thanks also to everyone who wrote to me about the original StickIt. I hope that StickIt2 incorporates most of your suggestions, and you feel it a worthy upgrade. Although I said in the original documentation that I had no intention of improving the program, the response from the users was so good it encouraged me to write StickIt2. If you find any bugs in StickIt2, write to me and send me as much info as possible about the bug (how to re-create it, any error messages the program may generate). Please include a detailed description of the system you are running StickIt2 on (version of Workbench, processor, memory, other commodities running etc...). As I have said before I have no intention to continue improving the program, as I have a PhD to be getting on with. However, there are a few additions that may be added in due time: * Optional, save an icon with the notefile. * Add preferences window, so that the user doesn't need to change the tooltypes in the icon by hand. * "Drag a box" editing in the notes. * A "Pop note up at a certain time" facility. * Maybe an ARexx port. Finally, if you use and enjoy this software then send me a postcard to tell me how far StickIt2 has reached. Go on, it'll only take a few minutes... Many thanks, Andy Dean