home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
ARM Club 3
/
TheARMClub_PDCD3.iso
/
programs
/
desktop
/
newbar
/
ReadMe
< prev
Wrap
Text File
|
1998-08-08
|
17KB
|
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/>).