ARM Club 3

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

/ ARM Club 3 / TheARMClub_PDCD3.iso / programs / patches / newbar / ReadMe < prev

Wrap

Text File | 1998-08-08 | 16.9 KB | 391 lines

IbarPatch version 1.10 (8th August 1998) ======================== 0. Contents ----------- 1. What is it? 2. Installation 3. Customisation 4. The Pinboard patcher 5. How it works 6. Bugs, problems, compatibility, and things unimplemented 7. Making your programs work well with IbarPatch 8. Compiling and understanding the source 9. Version history 10. Possible future improvements 11. Copyright 12. And finally 1. What is it? -------------- Bored with the standard, dull iconbar? Don't like the way it flickers when it's updated? Looking to reclaim a precious few OS units of your screen? Or just want to see a neat example of how to hack the Window Manager? IbarPatch may be the thing for you! IbarPatch is a replacement iconbar for RISC OS. It was written originally as a programming exercise in patching the Window Manager (which I started over a year ago, around January 1997, and have just come back to, so is also an exercise in understanding my own code). It will also patch the Pinboard to cope with a different size iconbar. Although currently its only use is to make the iconbar look different, it could be extended to allow iconbar icons to be moved to the Pinboard, for example. IharPatch has a range of configuration options to allow the iconbar's appearance be customised. Plus you get the source code, so you can modify it further yourself if you want. New versions will be available from: <http://www.argonet.co.uk/users/mseaborn/comp/programs.html> 2. Installation --------------- Before you install - - - - - - - - - Installation is simpler than the last version. If you had a previous version installed, you must uninstall it first by reversing any steps you made to install it! If you are using RISC OS 3.6 or RISC OS 3.7, make sure you have a newish version of ROMPatch installed, otherwise there may be problems. The latest version is available from <http://www.acorn.com/browser/download.html>. Installing - - - - - To install this version, simply copy the !NewBar application into your `!Boot.Choices.Boot.PreDesk' directory. If you're not using Acorn's standard boot sequence (which comes with RISC OS 3.5 onwards), just make sure that !NewBar gets run before the desktop starts. Reboot, and everything should work. If something goes wrong and the desktop won't start, you can use Shift-Break to get back into the desktop and change things. Beyond installation, no more instructions for NewBar are needed, apart from altering its options. 3. Customisation ---------------- Editing the Choices file - - - - - - - - - - - - The NewBar application has a large number of options for configuring the appearance of the iconbar. These can be changed by editing the !NewBar.Choices file: you can get to this either by selecting `Edit choices' from NewBar's menu, or by Shift-double-clicking on !NewBar and loading the Choices file inside. Once you have changed some options, you can reload them by selecting `Reload choices' from NewBar's menu, or by quitting NewBar and reloading it. NewBar's menu can be opened by clicking Menu on an empty part of its iconbar. The format of the Choices file - - - - - - - - - - - - - - - This is fairly straightforward: On each line, there is the name of an option, followed by the value assigned to it. I will not list all the available options here -- they are all listed in the provided Choices file with comments explaining each (comments start with `#' and extend to the end of the line). There is a special feature, option groups. These allow a set of options to be switched on and off in one go. For example: # An iconbar with small sprites group small-iconbar off { small-icons on icon-height 72 window-height 72 sprite-margin 10 } By changing `group small-iconbar off' to `group small-iconbar on', all the options inside the curly brackets come into effect. (Options later in the file override those that came before.) The Choices file included with NewBar contains all the default options at the beginning (ie. those that would be used anyway if the file did not specify them). After this I have put some option groups for various things. You can switch these groups on and off to see what they do, add your own groups, or modify the options at the beginning directly. 4. The Pinboard patcher ----------------------- IbarPatch includes code to patch the Pinboard module. The most important patch is to ensure that the Pinboard's background window reaches down to the top of the smaller iconbar. As a bonus, it can also change the colour of the Pinboard's background. The patcher has been tested with the versions of the Pinboard module that come with RISC OS 3.1 and 3.7. However, it will try to patch other versions by searching for the instructions to change. The patcher will be run by NewBar before the desktop starts up. What patches are made can be changed in NewBar's Choices file. If you are using a version of the Pinboard module that the patcher won't patch, contact me and I'll see what I can do. 5. How it works --------------- There are two main parts to IbarPatch: IconbarPatch -- This module intercepts Wimp SWIs using Doggysoft's WimpSWIVe module (version 0.05, which is included). Any call relating to the iconbar it queues and/or responds to with information that it knows. eg. Adding a new icon is queued (but responds with a new icon handle); and opening a menu can be altered so that menus appear in the correct place. NewBar -- This application provides the replacement iconbar. It interacts with IconbarPatch by looking at its queue and updating its iconbar appropriately. It delivers iconbar mouse clicks to icons' owners. It also tells IconbarPatch information such as where to open iconbar menus. This division of labour is intentional. Although it makes things a lot harder (because IconbarPatch has no idea of its client's data structures and can't always respond instantly), it means more than one task can handle iconbar icons. So in the future, they could be moved to the Pinboard with an Alt-drag, or something. It also means I don't have to write a module task (I can never get them to work). 6. Bugs, problems, compatibility, and things unimplemented ---------------------------------------------------------- Hint: If NewBar dies (or you quit it accidentally), it can be reloaded by pressing F12, typing `WimpTask Desktop_StartIconbar' and pressing Enter a few times. Known problems that can be fixed: * NewBar gets bitten by the bug in Wimp_TransferBlock in RISC OS 3.7. To fix this, make sure you use ROMPatch. Known problems that have not been fixed yet: * IconbarPatch may not cope properly with soft resets under RISC OS 3.1. * NewBar sometimes dies when Help is running. * NewBar doesn't yet re-open fonts on a mode change, so if the pixel sizes change, the fonts used will be the wrong size. Things that are not implemented: * TinyDirs doesn't work properly, because NewBar doesn't do different button types (such as icons that can be double-clicked). * Shift-clicks on windows' toggle-size icons. The Wimp thinks that there is no iconbar, and still opens windows at full size. * Similarly, NewBar doesn't do the new Nested Wimp's trick of putting the iconbar to the front when the pointer is kept at the bottom of the screen long enough; and it doesn't use Menu clicks at the bottom of the screen to do the same either. There are modules you can use to provide this functionality separately. IconbarPatch intercepts all iconbar-related SWIs. The essential ones are implemented fully, but some of the non-essential ones are partially implemented because certain programs (such as Alarm and ANT's Hotlist) rely on them. The SWIs intercepted are: * Wimp_CreateIcon: creation is queued. * Wimp_DeleteIcon: deletion is queued. * Wimp_CreateMenu: menu co-ordinates patched. * Wimp_GetWindowState: window state as recorded by NewBar is returned. * Wimp_GetWindowInfo: only window state info is returned. * Wimp_SetIconState: update is queued. * Wimp_GetIconState: gives info in some circumstances. * Wimp_ForceRedraw: ignored. * Wimp_WhichIcon: returns error. * Wimp_DragBox: returns error. * Wimp_SendMessage: messages are sent to icon's owning task. * Wimp_GetWindowOutline: state as recorded by NewBar is returned. * Wimp_GetPointerInfo: return data changed. * Wimp_ResizeIcon: returns error. 7. Making your programs work well with IbarPatch ------------------------------------------------ Iconbar height: Don't assume you know the height of the iconbar. NewBar sets the system variable Iconbar$Height to the height of the iconbar in OS units, so try reading this before reverting to the default Wimp height of 134 OS units. Pinboard replacements, for example, should do this. The exception is opening menus -- iconbar menus can be opened in the same way as usual, and are patched to open in the right place. Sprite areas: If your program uses its own sprite area for an iconbar sprite, make sure the size of the area is correctly filled in. SwiftJPEG fails to do this, so NewBar has to make some guesses to work around the fault. 8. Compiling and understanding the source ----------------------------------------- Prerequisites - - - - - - - Full source code is provided. To compile it, you'll need: * A C compiler (such as Acorn's C or gcc, although I haven't tried compiling it with gcc). * An Assembler (Acorn's ObjAsm, or `as' probably). * A copy of OSLib. * My library, Dreamscape. * Probably some other stuff I've forgotten as well. Optional things are: * Some sort of `make'. * Makatic 2. * Dr Smith's C Dev Toolkit helps debugging (commercial from WSS). Source components - - - - - - - - - For IconbarPatch: ibpatch.hdr -- The data structures used by the module, which are accessible by other programs (by reading its workspace address). debug.hdr -- Some debugging macros for the module. module.s -- Module header and init/finalisation code. handler.s -- Contains the routines for handling Wimp SWIs. For NewBar: This is quite modular, and the modules are (each with .c and .h files): gadget (iconbar_gadget) -- Handles display of iconbar icon gadgets. iconmgr (iconbar_manager_task) -- Communicates with the module. iconbar (thiniconbar) -- Arranges icons in a window (and scrolls it, etc.). pinpatch -- Will patch the Pinboard. hotkeys -- Creates a window for grabbing keypresses, but doesn't actually work properly (not sure why). font -- A few font-handling routines. options -- Reads the Choices file into a structure. There are some miscellaneous files: debug.h -- Debugging facilities. ibarpatch.h -- Details of the module's structures. various.h -- Prototypes for some misc functions. hacky.c -- Extracts icon and sprite data. main.c -- Starts and ends task, creates the menu. 9. Version history ------------------ <1.00 Originally written around January 1997. Not released, not numbered. 1.00 (released 9th March 1998): Over a year later, I came back to my code. Finished the program properly, tidied it up a lot and added comments. The first release version. 1.10 (released 8th August 1998): * Made a few bug fixes. Is now stable; NewBar has not died for ages, at least with the programs I use. * Have resolved to document changes properly. Added this section. * Updated PatchPinbd; should work for arbitrary Pinboard versions. * Fixed problem where iconbar was not getting resized properly. Didn't notice this before because Alarm ticks and forces a resize anyway. * Added code to read an options file (instead of recompiling options). Supports ints, floats and strings. Later added enumerations, as well as boolean and colour types (which are implemented as enumerations). * Added a few options to configure icon appearance (colours, borders). The motivation was to make it go with XEarth. Later, added support for groups of options, so styles can be enabled with the flick of a switch. * IconbarPatch can now start NewIconbar when the desktop starts (reduces installation complexity). * Did a large amount of rearranging, creating a class for icons. Also simplified icon creation: both text and sprite are now done as Wimp icons (previously text was a Button and sprite could be either). Better design in this area should reduce icon flicker (especially on Alarm). * Added the option of changing the font (and font size) of iconbar text. * Will now keep essential event data, so that if NewBar is reloaded, the icons will still be there! Also added a usage count for IconbarPatch, although not needed, because the module now doesn't have to be killed when NewBar quits. * Split main() program and iconbar object into separate files. * Now patches Wimp_ResizeIcon (just gives an error for iconbar). * Added different types of scrolling. Quite a variety, any of which might Do The Right Thing according to your tastes. * Fixed tricky bug: If the iconbar was above other windows on a mode change, those windows would become obscured by the Pinboard. Why: If a window with the `backdrop' flag set is sent to the bottom of the stack, it is actually put to the *top* of the stack of backdrop windows. On a mode change, the Pinboard opens its backdrop at the `bottom' of the stack (instead of reading the current state); on top of the iconbar and all the other windows. Now NewBar unsets the backdrop flag when the iconbar is brought to the front (this is done by poking the Wimp's workspace under old Wimp versions). This is actually what the Wimp does (since you can use a window's back icon to put it below the iconbar when the iconbar has been brought to the front). NewBar now also makes sure that, on startup, the iconbar is opened at the bottom of the stack. * Added option for iconbar to have a border (like the Wimp's one). * Implemented half-size icons. Will use the icon name prefixed by `sm' if possible (if in Wimp pool), otherwise will use the Wimp's half-size facility. * Added capability to take options via the command line. * Recoded the Pinboard patcher in C. With easier argument passing, I have made it a bit smarter. The Pinboard's background colour is also patched now. At the moment, PinPatch is linked into the NewBar !RunImage and invoked with a command line switch. This lets it share the option reading code, although space is now taken up by the patcher code when NewBar is running (not really significant though). * Added an option to arrange icons with the text to the right of sprites, instead of underneath the sprites. This lets the iconbar be even thinner, but makes it wider. It also looks a bit like Windoze 95's task bar. * Another significant rearrangement: Split off from the iconbar object all code involved in dealing with the IconbarPatch module and mouse clicks. The iconbar object now just deals with arranging icons in a window, and has been mostly rewritten to be a lot more elegant and efficient. Fixed a few bugs and problems in the process. * Moved the font handling code into its own file. * IconbarPatch module will now free its event lists when killed. * Fixed some bugs: Realised than the newer ROMPatch is needed. Seem to have fixed problem with Window_WimpToToolbox. Fixed icon rearrangement for icons on the far right (eg. XEarth). Tested again on RISC OS 3.1. 10. Possible future improvements -------------------------------- Fix bugs: * Fix font mode change omission. * Interferes with Printers on RO 3.1. * NewBar dies sometimes under Help. * Improve error handling. * Make more efficient speedwise. Add features: * Alternative background textures for iconbar. Larger changes: * Allow different tasks to handle different iconbar icons, using a filter options file to redirect them. * Write a new icon arranger, allowing icons to be placed in themed `drawers' (Matthew Bloch's idea). * Allow icons to be dragged between tasks that will handle them. * Write a Pinboard replacement that will take iconbar icons (long term, this one!). 11. Copyright ------------- IbarPatch is copyright (c) 1997/8 Mark Seaborn. You can modify and distribute it under the terms and conditions of the GNU General Public Licence version 2, or, at your option, a later version. The WimpSWIVe module is (c) Doggysoft (see <http://www.doggysoft.co.uk/>). 12. And finally --------------- If you've got any comments, you can e-mail me, Mark Seaborn, via <mseaborn@argonet.co.uk>. If that fails sometime in the future, try my forwarding address <mseaborn@bigfoot.com>. Bug reports are encouraged, but bug fixes are even more appreciated (use the source, Luke!). If you make any improvements to the source code, tell me about them, because they may well be worth putting into a future release. Lastly, you will be able to find future versions of IbarPatch at <http://www.argonet.co.uk/users/mseaborn/comp/programs.html>, and my home page can be found at <http://www.argonet.co.uk/users/mseaborn/> (there is also a forwarding address at <http://www.bigfoot.com/~mseaborn/>).