
README
======

PBButtons is a programm suite to handle the special hotkeys of an Apple
iBook, Powerbook or TiBook.

              (c) 2002 Matthias Grimm <joker@cymes.de>

With this programms the keys for the display brightness, the volume of
speaker and headphone, the mute key and the eject key will do their job
as expected.

This package contains the PBButtons server: pbbuttonsd

The server work as a daemon that do all the work. It runs in background
and is preferable started at boot time. Multiple clients could register
themselves to get messages about events from the server.

Currently the following events cause a message broadcast to clients:
    - The display brightness is changed by the user,
    - the speaker volume is changed by the user,
    - the speakers are muted/unmuted by the user and
    - the battery is running out of energy (not OHARE PowerBooks).

It is up to the clients what they do with this messages.


REQUIREMENTS
============
To use this programe, you need some additional parts:
1. An Apple Book. This program makes not much sense on other machines,
2. Kernel 2.4 (versions above 2.4.18-rc2-benh should be preferred) with
   the new event handler support or a Kernel 2.2 with backport (untested),
3. OSS Sounddriver or ALSA with runnung OSS emulation,
4. to eject a CDROM the tool 'eject' from Jeff Tranter <tranter@pobox.com>
   would be needed,
5. for older kernel versions than 2.4.18-rc2-benh an additional kernel patch
   is nessecary to get all features working. The patch 'pbbuttons.patch' is
   available on the same Web-Site as PBButtons. Without this patch only the
   volume control functions will popup those nice little windows. The
   display brightness is controlled directly by the kernel.


INSTALL
=======
To compile and install pbbuttonsd please see INSTALL.

Tn former versions of PBButtons there was a script included to check the
environment. With the new client/server model it isn't nessecary anymore,
but it is still included to support those who wants to run the PBButtons
daemon as normal user. The following description explains what this script
is able to do.

PBButtons uses some system devices and directories to work properly and
if a normal user wanted to use it, it would need therfore some extra
permissions. To check the system what exactly have to be done, the script
'setupenv.sh' was included. This script checks all nessecary devices and
directories and the permissions of them and prints a detailed report
what was ok and what has to be changed.

If this script was started as superuser root, it would ask if it should do
all nessecary modifications for you. If it was started as normal user, it
would only print the report.

The automatic mode of the script only realize a very simple concept of
access management. It would simply set read or read/write permissions for
'all user' to the concerning devices and directories if not already set.
Higher sophisticated solutions with access right management via groups
have to be installed by yourself. Please read appropriate manuals to get
help for this task.


LEGAL NOTICE
============

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version
2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; see the file COPYING.  If not, write to
the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.


CREDITS
=======

This program wouldn't exists if not some people wrote other programs
from which I learned how special things worked. I can't name all of
them so I picked those out, whose programs I could call the 'parents'
of PBButtons:

  keyevd       from Joseph P. Garcia <jpgarcia@execpc.com>
  ikeyd        from Stefan Pfetzing <dreamind@dreamind.de>

Also thanks to all unknown developers, who make my little program
possible.


HOW IT WORKS
============

The daemon 'pbbuttonsd' gets its input directly from the keboard event handler.
Consequently the keys are always active. It doesn't matter if X11 is in front
or if you are working on a console or which X11 window has the focus. You
can always use the hotkeys and get the appropriate reaction.

The following matrix shows all program functions:

Brightness keys  up	       The display brightness inreases by one.
                 shift up      The display brightness switches to MAXLEVEL.
		 down          The display brightness decreases by
		               one until it is switched completely off.
		 shift down    The display brightness switches to MINLEVEL
		               without switching the backlight completely off.
				  
Volume keys      This keys modify the speaker and the headphone volume together.
                 Also both stereo channels will be set to the same volume. For
		 a more detailed control a mixer program is nessecary.
		 This is the same manner as the Mac OS will do it. 
		 
                 up            Increases the volume by two.
		 shift up      Increases the volume by ten.
		 down          Decreases the volume by two.
		 shift down    Decreases the volume by ten.

Mute key         pressed once  The volume level of the speaker and headphone
                               will be set to zero.
			       
		 pressed again The old volume levels will be set again. This
		               also would happen, if one of the volume keys
			       was pressed during mute mode. 

Eject key        pressed       The external porgram 'eject' will be executed
                               and this will eject the CD.
			       
A lot of parameters are configurable via the command line. Please read the
man page for details.

  Enjoy
    Matthias Grimm
