Ta/asciidoc

Documentation/FvwmModules/FvwmAnimate.txt

@@ -0,0 +1,194 @@
+FvwmAnimate
+-----------
+
+The *FvwmAnimate* module animates iconification and de-iconification or 
+on command. There are currently 6 different animation effects.
+
+*FvwmAnimate* can only be invoked by fvwm. Command line invocation of 
+the *FvwmAnimate* module will not work.
+
+From within the .fvwm2rc file, *FvwmAnimate* is spawned as follows:
+
+------
+Module FvwmAnimate [ModuleAlias]
+------
+
+or from within an fvwm pop-up menu:
+
+------
+DestroyMenu Module-Popup
+AddToMenu   Module-Popup "Modules" Title
++ "Fvwm Animate Icons" Module FvwmAnimate ModuleAlias
+------
+
+
+INVOCATION
+~~~~~~~~~~
+*FvwmAnimate* must be invoked by the fvwm window manager. When invoked 
+with the 'OptionalName' argument, the 'ModuleAlias' is used to find 
+configuration commands, configuration files, and name the internally 
+generated menus and forms instead of "+FvwmAnimate+". 
+
+During startup, *FvwmAnimate* defines menus and forms for configuring 
+and controlling *FvwmAnimate*. The default menu name is "+MenuFvwmAnimate+" 
+and the form name is "+FormFvwmAnimate+". If the optional name is used, 
+the menu would be "+Menu<ModuleAlias>+" and the form would be "+Form<ModuleAlias>+".
+
+Assuming you already had a builtin menu called "+Module-Popup+", you could 
+use *FvwmAnimate* by configuring it like this:
+
+------
+AddToFunc "StartFunction" "I" Module FvwmAnimate
+AddToMenu "Module-Popup" "Control Animation" Popup MenuFvwmAnimate
+------
+
+
+CONFIGURATION OPTIONS
+~~~~~~~~~~~~~~~~~~~~~
+Since the pop up menu "+MenuFvwmAnimate+" allows complete control of the 
+*FvwmAnimate* module, you don't really have to know what any of the 
+configuration commands are. This section describes them anyway.
+
+*FvwmAnimate* gets configuration info from fvwm's module configuration 
+database (see *fvwm*(1), section *MODULE COMMANDS*). In addition, 
+*FvwmAnimate* reads the file $HOME/.FvwmAnimate, and accepts commands 
+from fvwm and its modules as it runs.
+
+If '+ModuleAlias+' is used to  start *FvwmAnimate*, the optional name is 
+used in all commands, messages, menus and forms generated by 
+*FvwmAnimate* and in the configuration file name. Unlike other fvwm 
+modules, there is little reason to use the optional name.
+
+*FvwmAnimate: Color 'color'::
++
+Tells *FvwmAnimate* what color to draw with. The color is XOR'ed 
+(exclusive ORed) onto the background. Depending on the display type you 
+are using, the effect this causes will vary. Especially on 8-bit displays, 
+it helps if the background is a solid color. You have to experiment with 
+this to see how it works.
++
+The default color is not really a color and can be entered as 
+"+Black^White+", or more simply "+None+". This is the same as the default 
+XOR mask used by fvwm for move and resize frames.
++
+Other colors can be specified using standard X color notation. Ie. color 
+names like "+LightBlue+", or RGB values like "+#FFFFFF+".
+
+
+*FvwmAnimate: Pixmap 'pixmap'::
++
+Tells *FvwmAnimate* to use 'pixmap' to draw with. This can be useful if 
+"+*FvwmAnimate: Color+" gives poor results.
+
+
+*FvwmAnimate: Delay 'msecs'::
++
+Tells *FvwmAnimate* how many milliseconds to sleep between frames of 
+animation.
+
+
+*FvwmAnimate: Iterations 'iterations'::
++
+Tells *FvwmAnimate* how many steps to break the animation into.
+
+
+*FvwmAnimate: Twist 'twist'::
++
+Tells *FvwmAnimate* how many revolutions to twist the iconification frame.
+
+
+*FvwmAnimate: Width 'width'::
++
+Tells *FvwmAnimate* how wide a line to draw with. The default width of 
+0 (zero) is a fast line of Width 1.
+
+
+*FvwmAnimate: Effect 'mode'::
++
+Tells *FvwmAnimate* which animation effect to use. Currently the effects 
+are: 'Frame', 'Lines', 'Flip', 'Turn', 'Zoom3D', 'Twist' 'Random', and 
+'None'. 'None' is normally set in the configuration file, in-case 
+*FvwmAnimate* is started automatically, but an individual user doesn't 
+want it running.
+
+
+*FvwmAnimate: Stop::
++
+Tells *FvwmAnimate* to stop.
+
+
+*FvwmAnimate: Save::
++
+Tells *FvwmAnimate* to save the current configuration in a file named 
+"+.FvwmAnimate+" in the users home directory. This same file is read 
+automatically by *FvwmAnimate* during startup.
+
+
+COMMANDS
+~~~~~~~~
+*FvwmAnimate* can be asked to produce an animation thru the *SendToModule* 
+command.  The format of the command is:
+
+------
+SendToModule FvwmAnimate animate sx sy sw sh dx dy dw dh
+------
+
+The second word must match the name *FvwmAnimate* is started with. The 
+8 fields after 'animate' must be numbers. The first 4 are for the source 
+(or starting) location of the animation. The last 4 are for the destination 
+of the animation. The 2 pairs of 4 numbers, represent rectangles. The 
+first 2 numbers are the x and y location of the upper right corner. The 
+next 2 numbers are the width and height. One or more spaces can separate 
+the fields in the command.
+
+Modules can use the *SendToModule* command to animate "+NoIcon+" windows, 
+or you can think up your own ways to have all kinds of fun with this 
+command.
+
+Additional available commands are: 'pause', 'play', 'push', 'pop' and 
+'reset'. These may be space separated.
+
+'pause' causes a module to not temporarily produce any animations. 'play' 
+causes a module to produce an animation again. 'push' stores the current 
+playing state for a future and 'pop' restores it. 'reset' removes all 
+stored states and sets playing on.
+
+Suppose, we don't want to wait for all 40 xterms to be animated:
+
+------
+SendToModule FvwmAnimate pause
+All (XTerm) Iconify on
+------
+
+And if we don't want to damage the current playing state, then:
+
+------
+SendToModule FvwmAnimate push pause
+All (XTerm) Iconify on
+SendToModule FvwmAnimate pop
+------
+
+
+ORIGIN
+~~~~~~
+
+*FvwmAnimate* is based on the Animate module from Afterstep 1.5pre6. 
+Porting to fvwm and lots of other changes were done by Dan Espen 
+<despen@telcordia.com>. Below are the original author and acknowledgments.
+
+
+AUTHOR
+~~~~~~
+
+Alfredo Kengi Kojima <kojima@inf.ufrgs.br>
+
+
+ACKNOWLEDGMENTS
+~~~~~~~~~~~~~~~
+
+These people have contributed to *FvwmAnimate*:
+
+Kaj Groner <kajg@mindspring.com>::
+Twisty iconification, configuration file parsing, man page.
+
+Frank Scheelen <scheelen@worldonline.nl>

Documentation/FvwmModules/FvwmAuto.txt

@@ -0,0 +1,139 @@
+FvwmAuto
+--------
+
+The *FvwmAuto* module is most often used to automatically raise focused 
+windows.
+
+*FvwmAuto* can only be invoked by fvwm. Command line invocation of the 
+*FvwmAuto* will not work.
+
+
+INVOCATION
+~~~~~~~~~~
+
+The correct syntax is:
+
+------
+Module FvwmAuto Timeout [-passid] [-menter|-menterleave|-mfocus] [EnterCommand [LeaveCommand]]
+------
+
+Example:
+
+------
+AddToMenu Modules
++ "Auto Raise (300 ms)"  Module FvwmAuto 300
++ "Auto Raise/Lower"     Module FvwmAuto 300 "Silent Raise" "Silent Lower"
+------
+
+The 'Timeout' argument is required. It specifies how long a window must 
+retain the keyboard input focus before the command is executed. The delay 
+is measured in milliseconds, and any integer greater than zero is valid.
+
+If the literal option '-passid' is given, the window id of the window 
+just entered or left is appended to the command that is sent to fvwm. 
+This can be used with the WindowId command  of fvwm.
+
+The options '-menter', '-menterleave' and '-mfocus' influence the actions 
+*FvwmAuto* reacts to. No more than one of the options can be chosen. In 
+'-mfocus' mode, *FvwmAuto* raises the window that has the focus. In 
+'-menter' mode, *FvwmAuto* raises the window under the pointer when the 
+pointer enters a window. The 'LeaveCommand' is executed on the window 
+that was below the pointer before it entered the new window. When the 
+pointer leaves a window and enters the root window, the 'EnterCommand' 
+is executed too, but without a window to operate on. In '-menterleave' 
+mode, *FvwmAuto* works just like in '-menter' mode, but the 'LeaveCommand' 
+is also executed if the pointer moves out of a window but does not enter 
+a new window. The latter two modes of operation are useful with windows 
+that do not accept the focus.
+
+[NOTE]
+'-menterleave' mode can interfere with popup windows of some applications. 
+One example is the zoom menu of Ghostview. Please do not complain about 
+this to us - it is a bug in Ghostview.
+
+'EnterCommand' and 'LeaveCommand' are optional. 'EnterCommand' is executed 
+Timeout milliseconds after a window gets the input focus, 'LeaveCommand' 
+is executed Timeout milliseconds after the window has lost focus. Note 
+that you always should use the \'+Silent+' keyword before the command 
+itself. *FvwmAuto* prepends "+Silent+" to the command string on its own 
+if yor forget this. Without this prefix fvwm would ask you for a window 
+to act on if the window has died before the command sent by *FvwmAuto* 
+has been processed by fvwm.  This can for example happen with popup menus.
+
+"Silent Raise" is the default for 'EnterCommand', but any fvwm function 
+is allowed. I would not use "+Close+" or "+Destroy+" with a low timeout, 
+though. The 'LeaveCommand' can be handy for a tidy desktop.
+
+Experiment with:
+------
+Module FvwmAuto 0 Nop "Silent Lower"
+Module FvwmAuto 0 Nop "Silent Iconify"
+------
+
+An example for auto raising windows with ClickToFocus:
+------
+Style * ClickToFocus
+FvwmAuto 0 -menter "Silent Raise"
+------
+
+An example for auto raising and lowering only some windows:
+
+To start FvwmAuto:
+------
+FvwmAuto 0 -passid -menter \
+"Silent selective_raiselower raise" \
+"Silent selective_raiselower lower"
+------
+
+And put this in your .fvwm2rc:
+------
+AddToFunc selective_raiselower
++ I WindowId $1 (FvwmIconMan) $0
++ I WindowId $1 (FvwmButtons) $0
++ I WindowId $1 (xclock) $0
+------
+
+More complex example (three FvwmAuto's are running):
+------
+DestroyFunc RestoreIconified
+AddToFunc   RestoreIconified
++ I Current (Iconic) Iconify false
+
+DestroyFunc RegisterFocus
+AddToFunc   RegisterFocus
++ I Exec date +"%T $n focused" >>/tmp/focus-stats.txt
+
+DestroyFunc RegisterUnfocus
+AddToFunc   RegisterUnfocus
++ I Exec date +"%T $n unfocused" >>/tmp/focus-stats.txt
+
+KillModule FvwmAuto
+Module FvwmAuto 250 Raise Nop
+Module FvwmAuto 800 RestoreIconified Nop
+Module FvwmAuto   0 RegisterFocus RegisterUnfocus
+------
+
+
+NOTES
+~~~~~
+
+There is a special Raise/Lower support in *FvwmAuto*. It was added to 
+improve Raise/Lower callbacks, since most of *FvwmAuto* usages is 
+auto-raising or auto-lowering. This improvement includes locking  on  
++M_RAISE_WINDOW+ and +M_LOWER_WINDOW+ packets and not raising/lowering 
+explicitly raised windows. The special Raise/Lower support is enabled 
+only when either 'EnterCommand' or 'LeaveCommand' contain substring 
+"+Raise+" or "+Lower+". You can use this fact to enable/disable any special 
+support by renaming these commands, if *FvwmAuto* does not automatically 
+do want you expect it to do.
+
+Using *FvwmAuto* in conjunction with 'EdgeCommand' can be even more 
+powerful. There is a short example in the fvwm man page.
+
+
+AUTHOR
+~~~~~~
+
+*FvwmAuto* just appeared one day, nobody knows how.
+
+*FvwmAuto* was simply rewritten 09/96, nobody knows by whom.