modules/FvwmEvent/FvwmEvent.1.in

   1 .\" t
   2 .\" @(#)@PACKAGE@-@VERSION@ @RELDATELONG@
   3 .TH FvwmEvent 1 "@RELDATELONG@ (@VERSION@)" Fvwm "Fvwm Modules"
   4 .UC
   5 .SH NAME
   6 \fIFvwmEvent\fP \- the fvwm event module
   7 .SH SYNOPSIS
   8 \fIFvwmEvent\fP is a more versatile replacement for \fIFvwmAudio\fP.
   9 It can in general be used to hook any \fIfvwm\fP function or program to any
  10 window manager event. E.g: Delete unwanted Netscape Pop ups or
  11 application error pop ups as they appear, play sounds, log events to a
  12 file and the like. Be creative, you'll find a use for it.
  13
  14 \fIFvwmEvent\fP is spawned by \fIfvwm\fP, so no command line invocation will
  15 work.  From within the \fI.fvwm2rc\fP file, \fIFvwmEvent\fP is spawned as
  16 follows:
  17 .nf
  18 .sp
  19 Module FvwmEvent
  20 .sp
  21 .fi
  22 or from within an \fIfvwm\fP pop-up menu:
  23 .nf
  24 .sp
  25 DestroyMenu Module-Popup
  26 AddToMenu Module-Popup "Modules" Title
  27 + "Event"        Module FvwmEvent
  28 + "Auto"         Module FvwmAuto 200
  29 + "Buttons"      Module FvwmButtons
  30 + "Console"      Module FvwmConsole
  31 + "Ident"        Module FvwmIdent
  32 + "Banner"       Module FvwmBanner
  33 + "Pager"        Module FvwmPager 0 3
  34 .sp
  35 .fi
  36 .SH DESCRIPTION
  37 The \fIFvwmEvent\fP module communicates with the \fIfvwm\fP window manager
  38 to bind \fIactions\fP to window manager \fIevents\fP.  Different actions
  39 may be assigned to distinct window manager events.
  40
  41 \fIFvwmEvent\fP can be used to bind sound files to events like
  42 \fIFvwmAudio\fP (RiP) did. It can be used for logging event traces to
  43 a log file, while debugging \fIfvwm\fP.
  44
  45 \fIFvwmEvent\fP can also have builtin support for the rplay library.
  46 (heritage of FvwmAudio)
  47
  48 .SH INVOCATION
  49 The invocation method was shown in the synopsis section. No command
  50 line invocation is possible. \fIFvwmEvent\fP must be invoked by the
  51 \fIfvwm\fP window manager. \fIFvwmEvent\fP accepts a single
  52 argument:
  53
  54 .IP \-audio
  55 Enables FvwmAudio compatibility mode.
  56
  57 .IP alias
  58 Makes FvwmEvent use \fIalias\fP as its name. This affects which lines
  59 from the user's configuration file are used.
  60
  61 Invoking FvwmEvent as \fIFvwmAudio\fP (either by using an alias or
  62 creating a symlink) enables FvwmAudio compatibility mode.
  63
  64 .sp
  65
  66 .SH CONFIGURATION OPTIONS
  67 \fIFvwmEvent\fP gets config info from \fBfvwm\fP's module configuration
  68 database (see
  69 .IR fvwm (1),
  70 section
  71 .BR "MODULE COMMANDS" ),
  72 and looks for certain configuration options:
  73
  74 .IP "*FvwmEvent: Cmd \fIcommand\fP"
  75 This determines the \fIfvwm\fP function that is to be called with the
  76 event parameters. You might want to do one of the following (details below):
  77 .nf
  78 .sp
  79         # play sounds
  80         *FvwmEvent: Cmd \fIbuiltin-rplay\fP
  81
  82         # execute distinct fvwm functions
  83         *FvwmEvent: Cmd
  84
  85         # execute distinct external programs
  86         *FvwmEvent: Cmd exec
  87 .sp
  88 .fi
  89 This version of \fIFvwmEvent\fP has builtin \fIrplay\fP support which does not
  90 need to invoke an external audio player to play sounds.  The rplay
  91 support is enabled when \fIFvwmEvent\fP is compiled with \fIHAVE_RPLAY\fP
  92 defined and when \fIFvwmEvent: Cmd\fP is set to \fIbuiltin-rplay\fP. See
  93 remarks below if \fIFvwmEvent\fP is invoked in FvwmAudio compatibility mode.
  94
  95 For example:
  96 .nf
  97 .sp
  98         *FvwmEvent: Cmd \fIbuiltin-rplay\fP
  99         *FvwmEvent: add_window drip.au
 100 .sp
 101 .fi
 102 rplay can be obtained via anonymous ftp at
 103 .nf
 104 .sp
 105         <URL:ftp://ftp.sdsu.edu/pub/rplay> or
 106         <URL:ftp://ftp.x.org/contrib/Event/audio/rplay>
 107 .sp
 108 .fi
 109 \fIFvwmEvent\fP also has support for any other external program.
 110 e.g: the rsynth 'say' command:
 111 .nf
 112 .sp
 113         *FvwmEvent: Cmd "Exec /rsynth/say"
 114         *FvwmEvent: destroy_window "window closed"
 115 .sp
 116 .fi
 117 You can also use \fIfvwm\fP's builtin \fIEcho\fP command as
 118 \fIFvwmEvent: Cmd\fP to obtain debug output for \fIfvwm\fP events quietly.
 119 I used this setup to debug FvwmAuto:
 120 .nf
 121 .sp
 122         *FvwmEvent: Cmd \fIEcho\fP
 123         *FvwmEvent: focus_change "focus change"
 124         *FvwmEvent: raise_window "raise window"
 125 .sp
 126 .fi
 127 You can even call different shell commands for each event just by setting
 128 .nf
 129 .sp
 130         *FvwmEvent: Cmd exec
 131         *FvwmEvent: add_window 'killname "APPL ERROR"'
 132 .sp
 133 .fi
 134 .IP "*FvwmEvent: PassId"
 135 Specifies that the event action will have an ID parameter added to the end
 136 of the command line. Most events will have the windowID of the window that the
 137 event refers to, new_desk will have the new desk number. The windowID is a
 138 hexadecimal string preceded by 0x, desk numbers are decimal.
 139
 140 .IP "*FvwmEvent: \fIwindow-manager-event action-or-filename\fP"
 141 Binds particular actions to window manager events.
 142
 143 e.g. for audio-events:
 144 .nf
 145 .sp
 146         *FvwmEvent: startup TaDa.au
 147         *FvwmEvent: shutdown Elvis_Left.au
 148         *FvwmEvent: unknown doh.au
 149
 150         *FvwmEvent: new_page beam_trek.au
 151         *FvwmEvent: new_desk beam_trek.au
 152         *FvwmEvent: old_add_window drip.au
 153         *FvwmEvent: raise_window swoosh.au
 154         *FvwmEvent: lower_window swoosh.au
 155         *FvwmEvent: old_configure_window hammer.au
 156         *FvwmEvent: focus_change boing.au
 157         *FvwmEvent: enter_window boing.au
 158         *FvwmEvent: leave_window boing.au
 159         *FvwmEvent: destroy_window explosion.au
 160         *FvwmEvent: iconify ploop.au
 161         *FvwmEvent: deiconify ploop.au
 162         *FvwmEvent: window_name huh.au
 163         *FvwmEvent: icon_name beep.au
 164         *FvwmEvent: visible_icon_name beep.au
 165         *FvwmEvent: res_class beep.au
 166         *FvwmEvent: res_name beep.au
 167         *FvwmEvent: end_windowlist twang.au
 168
 169         *FvwmEvent: icon_location beep.au
 170         *FvwmEvent: map beep.au
 171         *FvwmEvent: error beep.au
 172         *FvwmEvent: config_info beep.au
 173         *FvwmEvent: end_config_info beep.au
 174         *FvwmEvent: icon_file beep.au
 175         *FvwmEvent: default_icon beep.au
 176         *FvwmEvent: string plapper.au
 177         *FvwmEvent: mini_icon beep.au
 178         *FvwmEvent: windowshade beep.au
 179         *FvwmEvent: dewindowshade beep.au
 180
 181         *FvwmEvent: visible_name beep.au
 182         *FvwmEvent: sendconfig beep.au
 183         *FvwmEvent: restack beep.au
 184         *FvwmEvent: add_window beep.au
 185         *FvwmEvent: configure_window beep.au
 186
 187         *FvwmEvent: visible_icon_name beep.au
 188         *FvwmEvent: enter_window beep.au
 189         *FvwmEvent: leave_window beep.au
 190         *FvwmEvent: property_change beep.au
 191 .sp
 192 .fi
 193 The window related event handlers are executed within a window
 194 context.  Previously PassId was used for this purpose, but now using
 195 PassId is not needed.
 196
 197 Note: The enter_window event is generated when the pointer enters
 198 a window.  With the -passid option, that window's id is passed to
 199 fvwm.  An enter_window event is generated too when the pointer
 200 leaves a window and moves into the root window.  In this case, the
 201 id passed is 0.
 202
 203 Note: When the shutdown event arrives, FvwmEvent may be killed
 204 before it can trigger the associated action.
 205 .sp
 206 .fi
 207 Provided \fIfvwm\fP supports it (not yet), there's an additional event to
 208 replace all \fIfvwm\fP beeps with a sound:
 209 .nf
 210 .sp
 211         *FvwmEvent: beep beep.au
 212 .sp
 213 .fi
 214 The toggle_paging event will be supported, as soon, as it's
 215 resurrected by \fIfvwm\fP:
 216 .nf
 217 .sp
 218         *FvwmEvent: toggle_paging fwop.au
 219 .sp
 220 .fi
 221 .IP "*FvwmEvent: Delay \fI5\fP"
 222 Specifies that an event-action will only be executed if it occurs at
 223 least 5 seconds after the previous event.  Events that occur during
 224 the delay period are ignored.  This option is useful if you don't want
 225 several sounds playing at the same time.  The default delay is 0 which
 226 disables the Event delay.
 227
 228 .IP "*FvwmEvent: StartDelay \fIdelay\fP"
 229 Specifies that an event-action will only be executed if it occurs at
 230 least \fIdelay\fP seconds after the startup event. Events that occur during
 231 the delay period are ignored.  This option is useful when \fIfvwm\fP
 232 starts and restarts using an audio player.  The default delay is 0.
 233
 234 .SH RPLAY OPTIONS
 235 The following options are only valid with builtin rplay support.
 236 i.e: when \fIFvwmEvent\fP was compiled with \fIHAVE_RPLAY\fP defined.
 237 They are used only if \fIFvwmEvent: Cmd\fP is set
 238 to \fIbuiltin-rplay\fP.
 239
 240
 241 .IP "*FvwmEvent: RplayHost \fIhostname\fP"
 242 Specifies what host the rplay sounds will play on.  The \fIhostname\fP
 243 can also be an environment variable such as $HOSTDISPLAY.
 244
 245 .IP "*FvwmEvent: RplayPriority \fI0\fP"
 246 Specifies what priority will be assigned to the rplay sounds when they
 247 are played.
 248
 249 .IP "*FvwmEvent: RplayVolume \fI127\fP"
 250 Specifies what volume will be assigned to the sounds when they are
 251 played.
 252
 253 .SH FvwmAudio Compatibility Mode
 254
 255 When invoked in FvwmAudio compatibility mode (see above), FvwmEvent
 256 accepts the following options to provide backwards compatibility
 257 for FvwmAudio:
 258
 259 .IP "*FvwmEvent: PlayCmd \fIcommand\fP"
 260 This is equivalent to using *FvwmEvent: Cmd to Exec commands. This
 261 determines the independent audio player program that will actually
 262 play the sounds. If the play command is set to \fIbuiltin-rplay\fP
 263 then the builtin rplay support will be used.
 264
 265 .IP "*FvwmAudio: Dir \fIdirectory\fP"
 266 Specifies the directory to look for the audio files.  This option is
 267 ignored when rplay is used.
 268
 269 .SH BUGS
 270 It's REALLY noisy when \fIfvwm\fP starts and restarts using an audio player.
 271 You can use FvwmEvent: StartDelay to fix this problem.
 272
 273 .SH COPYRIGHTS
 274 This module has evolved of \fIFvwmAudio\fP, which in term is heavily based
 275 on a similar Fvwm module called \fIFvwmSound\fP by Mark
 276 Boyns. \fIFvwmAudio\fP simply took Mark's original program and
 277 extended it to make it generic enough to work with any audio
 278 player. Due to different requests to do specific things on specific events,
 279 \fIFvwmEvent\fP took this one step further and now calls any
 280 \fIfvwm\fP function, or builtin-rplay. If \fIfvwm\fP's Exec function
 281 is used, any external program can be called with any parameter.
 282
 283 The concept for interfacing this module to the Window Manager, is
 284 original work by Robert Nation.
 285
 286 Copyright 1998 Albrecht Kadlec.
 287 Copyright 1994, Mark Boyns and Mark Scott.  No guarantees or
 288 warranties or anything are provided or implied in any way whatsoever.
 289 Use this program at your own risk.  Permission to use and modify this
 290 program for any purpose is given, as long as the copyright is kept intact.
 291
 292
 293 .sp
 294 .SH AUTHORS
 295 .nf
 296 1994  FvwmSound  Mark Boyns       (\fIboyns@sdsu.edu\fP)
 297 1994  FvwmAudio  Mark Scott       (\fImscott@mcd.mot.com\fP)
 298 1996  FvwmAudio  Albrecht Kadlec
 299 1998  FvwmEvent  Albrecht Kadlec  (\fIalbrecht@auto.tuwien.ac.at\fP)