
README
======

PBButtons is a program suite to support laptop specific functions and
make them available again under Linux. Basically it was developed to
support the special hotkeys of an Apple iBook, Powerbook or TiBook but
since version 0.5 the design has been changed to support all kind of
laptop or notebook. 

                     (c) 2002-2004 Matthias Grimm

With this programs 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 a PBButtons Client: GTKPBButtons.

This client for pbbuttonsd displays small popup windows each time a
message from the daemon pbbuttonsd appears. The view of each popup
could individually configured. The following windows could
pop up:

    - brightness level
      The current display brightness level would be displayed.
      
    - keyboard illumination level
      The current keyboard 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 last warnlevel indicate that the machine 
      will be shut down now to save data integrity.

    - sleep warning
      This windows shows that the computer is going to enter sleep mode.
      
    - trackpad
      This window shows the current trackpad operating mode.

    - ejecting CDROM
      This window signals that a CDROM will be ejected or why it can't.
      
    - external video is activated
      This window shows the status of the external video output as soon
      as the status has been changed by pbbuttonsd.
	  
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 programs, you need some additional parts:
1. an Laptop or Notebook supported by pbbuttonsd
2. the GTK and GLib libraries version 2.0 or later,
3. libaudiofile library > 0.1.9 and pthread library for the sound feature
4. libpopt library, a library to evaluate command line options
5. a running PBButtons daemon, named pbbuttonsd, available as a separate
   package,


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

The library should 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.

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

Gnome session management support can be activated at compile time. Call
the configure script with option --with-gnome and the necessary code will
be included in gtkpbbuttons.

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

  keyevd       from Joseph P. Garcia <jpgarcia@execpc.com>
  ikeyd        from Stefan Pfetzing <dreamind@dreamind.de>
  pmud         from Stephan Leempurg <sleemburg@jvc.nl>
  snooze       from Paul Mackerras <paulus@linuxcare.com> and
                    Stephan Leemburg <sleemburg@jvc.nl>
  trackpad     from Ben Herrenschmidt <benh@kernel.crashing.org>
  fnset        from Jimi X <jimix@watson.ibm.com>
  lmud         from Andreas Jaggi <andreas.jaggi@waterwav.ch>
  alcd         from Federico Gamio <federico@gamio.net>

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


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

The daemon 'pbbuttonsd' gets its input directly from the keyboard 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 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.

  Enjoy
    Matthias Grimm


