
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 Client: GTKPBButtons.

This client for pbbuttonsd displays small GTK popup windows each time a
message from the daemon pbbuttonsd appeares. The following windows could
pop up:

    - brightness level
      The current display brightness level would be displayed.
      
    - volume level
      The current volume level would be displayed
      
    - mute
      The window shows if the speakers were muted.
      
    - battery warning
      This window shows that battery is running low and how long it would
      last until shutdown.

The window appears after someone has pressed one of the special keys or an
event message has been received. After roundabout two seconds without any
changes, the popup window vanishes again.


REQUIREMENTS
============
To use this programe, you need some additional parts:
1. an Apple Book. This program makes not much sense on other machines,
2. the GTK and GLib libraries,
3. a runnning PBButtons daemon, named pbbuttonsd, available as a separate
   package,


COMPILE & INSTALL
=================
To compile this client the library libpbbipc.a is nessecary. This library
is part of the daemon package pbbuttonsd and is available as static library
only. This may be changed in the future.

If you use precompiled packages you could skip this paragraph except you
want to develop your own PBButton's client.

There are two ways to access the library:
1. It could be installed in a common lib directory which the linker already
   knows about. The header file must also be placed in usual places. This
   will all done automatically during the daemon's normal installation
   process. If you have got an precompiled package of the daemon pbbuttonsd,
   please check if the package includes the library.
   
2. The source directory of gtkpbbuttons could be placed in the same
   directory as the servers source directory. In this case the compiler
   and linker will find the library and the header file in the server's
   directory. The server and the library have to be compiled first.  

For the other details about compiling and installing of GTKPBButtons please
see INSTALL.


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 the PBButtons suite:

  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.
			       
The client contained in this package gives the user a visual feedback of the
daemons background work and displays those events to the user that the daemon
believes the user should know about. It won't run without a running daemon. 

Some parameters are configurable via the command line. Please read the man page
for details.

ALSA
====
The awacs sound driver from the stable ALSA sound drivers (0.5.12a) seems to
have a problem with its reset routine. Each time the sound output is closed
or sync'ed, a crackle could be heard. This is only a cosmetically problem, but
it makes using the sound feature with this alsa sound driver unpleasant.


  Enjoy
    Matthias Grimm
