
                               KHotKeys README


 WARNING !
 This is a prerelease version ( that's why it's called pre1 :) ), and
 as such it's buggy, poorly documented and there are still features
 that are not implemented yet. It's aimed mainly at users who used
 to use the KDE1.x versions of KHotKeys ( or are smart enough to learn
 something complicated without having good docs for it :) ). You've been
 warned.
  
  
  The 2.x version of KHotKeys is a complete rewrite from scratch, and
 the name KHotKeys is actually rather misleading by now ( and it has never
 been really correct if I understand what the difference between a hotkey
 and a keyboard shortcut is ... well, whatever ... ).
  KHotKeys2.x should be capable of doing everything the 1.x versions could do,
 and much more, of course. In short, KHotKeys is a utility that allows you
 to bind actions to triggers and conditions. The most common case is where
 action means launching some command/application/URL, the trigger is some
 key combination pressed and condition is some window being
 ( not ) active/existing. There are ( or will be ) more types of actions,
 triggers and conditions.
 
 INSTALLATION :
 
  The recommended KDE version is KDE2.2 ( unreleased yet at this time :-> ),
 KDE2.2beta1 should be fine. I haven't tested it with any older versions,
 so I don't know if it will work with them or not ( that's why it's called
 pre1, remember ? ).
  During installation, the files will replace the ones that are part
 of the simple version in kdebase. Shortcuts assigned using KMenuEdit
 should still work, and the config file will be converted to the new format.
 However, you should backup all files before removing them ( including
 the config file ), so you will be able to go back in case there will be
 a serious problem with this version. The files you should remove
 and backup before installing the new version are :
 - $KDEDIR/bin/khotkeys
 - $KDEDIR/lib/libkcm_khotkeys.la
 - $KDEDIR/lib/libkcm_khotkeys.so
 - $KDEDIR/lib/kde2/libkcm_khotkeys.la
 - $KDEDIR/lib/kde2/libkcm_khotkeys.so
 - $KDEDIR/lib/khotkeys.la
 - $KDEDIR/lib/khotkeys.so
 - $KDEDIR/lib/libkhotkeys.la
 - $KDEDIR/lib/libkhotkeys.so
 - $KDEDIR/share/autostart/khotkeys.desktop
 - $KDEHOME/share/config/khotkeysrc
 Not all these files exist, depending on your KDE and OS version. It's simply
 all files having 'khotkeys' in their name.
  Ok, now the standard install ( ./configure && make && make install ), and
 now you can start you KDE.
 
 CONFIGURATION :
 
  The configuration module is started using K-Menu/Settings/System/KHotKeys .
 If you have used the 1.x version ( you have, haven't you ? ), it will look
 familiar. On the left, there's a list of all actions, they may be put
 in groups. On the right, there are several tabs with details for
 currently selected action, or an info tab when no action is selected ( no,
 don't bother, the 'Global settings...' button doesn't do anything useful
 yet, besides going down and up ).
  The first tab ( 'General' ) lets you to select the type of the action.
 The types available now are :
     - Generic - any actions
     - Command/URL to execute
     - K-Menu entry to execute
     - DCOP call - will perform a DCOP call
     - Keyboard input - will simulate keyboard input
  The second tab is usually the 'Triggers' tab, here you can specify a list
 of triggers that will start this action, if conditions for it will be met.
 The types available now are :
     - Single shortcut trigger - a keyboard combination is pressed
     - Window trigger - a window appears, becomes active, ...
  The next tab is settings for the action. ( Just in case you haven't noticed
 yet, I'm apparently not very good at inventing good fitting names. 'Action'
 in KHotKeys means either a whole action, e.g. 'run a new Konsole when
 Ctrl+Alt+T is pressed and the active window is not a Konsole', or it can
 mean just the resulting action, i.e. only 'run a new Konsole'. Live with it
 or suggest better names ).
  - Command/URL tab settings - enter the command or URL to execute ( no,
    the 'Browse' doesn't do anything useful yet ). The 'Don't execute but
    switch to window if window exists' checkbox and the window definition
    below, if turned on, cause KHotKeys first to search for a matching
    window and if it's found, it will be activated and no command/URL
    will be executed
  - K-Menu entry tab settings - just like the Command/URL tab, only enter
    a .desktop file from the K-Menu to execute (e.g. 'System/konsole.desktop')
  - DCOP call tab settings - enter the application, object, DCOP method and
    arguments (e.g. 'kdesktop', 'KBackgroundIface',
    'setWallpaper(QString,int)' and '"/some/pic.jpg" 1')
  - Keyboard input tab settings - enter the keyboard input you want to be
    simulated ( no, sorry, the 'Edit' button doesn't really work yet ).
    The "keypresses" are separated by a colon ( ':' ) and are written
    in the form the are seen e.g. in the keybindings dialog ( e.g. to enter
    a colon, you have to type 'Shift+;' ). The 'send to specific window'
    checkbox and the window definition allow you to specify that the input
    shouldn't be sent to the currently active window but to a window that
    matches the definition. Note that certain things, like triggering
    Ctrl+F1 for going to the first desktop, don't work yet.
  The last tab is 'Windows'. If there are any windows specified, the action
 will be active only if the currently active window matches at least one
 of the window definitions. 
  Windows are specified using window definitions, the only type now available
 is a simple window definition. You can specify a window title, class, command
 and type ( again, the 'Autodetect...' button doesn't work yet ). Title is
 easy, to get the window class and command, run 'xprop' in Konsole and click
 on a window; then search for WM_CLASS and WM_COMMAND.
 
 EXAMPLES :
 
 Ok, some examples :
 -  Start konsole by pressing Ctrl+Alt+T :
    - the easier way - use KMenuEdit :)
    - create a new action, name it 'Konsole', select 'Command/URL to execute'
      as action type; go to 'Triggers' tab, click 'New...', select
      'Single shortcut trigger', select Ctrl+Alt+T; go to
      'Command/URL settings' tab, type 'konsole' in the lineedit. Now click
      'Apply' in the configuration module, press Ctrl+Alt+T and a new Konsole
      should appear whenever you do that.
 - Change wallpaper by pressing Ctrl+Alt+W :
    - create a new action, select 'DCOP call', create a Ctrl+Alt+W trigger, go
      to the 'DCOP call settings' tab and enter 'kdesktop' as application,
      'KBackgroundIface' as object, 'changeWallpaper' as function and nothing
      in arguments ( this assumes you have the multiple wallpapers mode ).
      For setting one specific wallpaper, enter 'setWallpaper(QString,int)'
      as the function instead and enter a string and a number as the arguments
      ( strings must be quoted if they contain spaces ), so enter e.g.
      '/tmp/a.jpg 1' .
 - Remap key 'Ctrl+W' to 'Ctrl+F4' in Qt Designer
    - Emacs users and other beings prefering Ctrl+A and such combinations
      to pressing 'End' etc., watch this : Create a new action, select
      'Keyboard input', create a Ctrl+W trigger, now go to
      'Keyboard input settings' tab, and type 'Ctrl+F4'. This would remap
      the key in all aplications, so now it's needed to limit it only
      to Qt Designer. Running xprop and clicking on designer window
      will show that it's WM_CLASS contains string 'Qt Designer'. Go to
      'Windows' tab, click 'New...' and select 'Simple window', change
      the combobox next to 'Window class' to 'contains' and type
      'Qt Designer' to the lineedit below. Ok, done. BTW, this is a way
      how to make non-KDE apps "follow" KDE keybindings settings, I bet
      Qt Designer uses Ctrl+F4 for 'Close' because that a MS Windows standard.
      And BTW, don't use 'Close' in Qt designer, start a new one for every
      .ui file. I think it doesn't clean all tables after closing a file.
    - The same way you can now e.g. remap Ctrl+A to End, make Ctrl+Alt+U
      "type" word 'unsigned' in KDevelop, or even control xmms ( do just
      like described above, don't specify any window in the 'Windows' tab,
      but check 'Send to specific window' in the 'Keyboard input settings'
      tab, and create a 'Window simple' definition where 'Window class' 'is'
      'XMMS_Player xmms'. The input to simulate should be simply 'C' to pause,
      'B' to go to next file, etc. ( try it first directly in xmms ).
  
 KHotKeys Copyright 1999-2001 Lubos Lunak <l.lunak@kde.org>
 Distributed under the terms of the GNU General Public License version 2.
  
# $Id: README,v 1.7 2001/07/08 14:21:46 seli Exp $
