FvwmProxy(1)							   Fvwm Modules 						      FvwmProxy(1)

NAME

       FvwmProxy - the fvwm proxy module

SYNOPSIS

       FvwmProxy is spawned by fvwm, so no command line invocation will work.

DESCRIPTION

       The  FvwmProxy  allows  the user to locate and control windows obscured by other windows by using small non-overlapping proxy windows.  The
       default capabilites include raising and lowering the proxied windows.

       Using the sample configuration, pressing Alt-Tab cycles through the windows and allows the use of assignable click actions on the  proxies.
       Releasing the Alt key deactivates the proxy windows.  By default, pressing the left or right mouse buttons on a proxy window raises or low-
       ers the associated proxied window respectively.	An additional mapping can have the proxies automatically appear by just  holding  the  Alt
       key.

       Proxy  windows  are always on top and try to center on the regular window they proxy.  A simple collision algorithm tweaks the positions of
       the proxy windows to prevent them from overlapping.

COPYRIGHTS

       The FvwmProxy program is original work by Jason Weber.

       Copyright 2002, Jason Weber. No guarantees or warranties or anything are provided or implied in any way whatsoever.  Use  this  program	at
       your own risk.

INVOCATION

       FvwmProxy  can  be  invoked by inserting the line 'Module FvwmProxy' in the .fvwm2rc file. This can be placed on a line by itself, if Fvwm-
       Proxy is to be spawned during fvwm's initialization, or can be bound to a menu or mouse button or keystroke to invoke it later.	Fvwm  will
       search directory specified in the ModulePath configuration option to attempt to locate FvwmProxy.

CONFIGURATION OPTIONS

       *FvwmProxy: Colorset n
	      Specifies the color theme for unselected proxy windows.

       *FvwmProxy: SelectColorset n
	      Specifies the color theme for the selected proxy window.

       *FvwmProxy: IconifiedColorset n
	      Specifies  the  color  theme  for proxy windows of iconified windows.  This is only meaningful in conjuction with the ProxyIconified
	      option on.

       *FvwmProxy: Font font
	      Specifies the font used for large proxy window text.  This usually contains the icon string and is nearly vertically centered in the
	      proxy.  If there is no icon string, the title bar string is used.  If this text exceeds the width of the proxy, it is cropped on the
	      right.  If no Font is specified, a default is used.

       *FvwmProxy: SmallFont font
	      Specifies the font used for the auxillary proxy window text.  This usually contains the title bar string, but is omitted	if  it	is
	      identical  to the icon string and that text was not cropped.  The text is drawn close to the bottom of the proxy and should probably
	      be the smallest legible font available.  If this text exceeds the width of the proxy, it is cropped on the left.	If no SmallFont is
	      specified, this text is never drawn.

       *FvwmProxy: Width w
	      Specifies the size in X of each proxy window. The default is 180.

       *FvwmProxy: Height h
	      Specifies the size in Y of each proxy window. The default is 60.

       *FvwmProxy: Separation d
	      Specifies the minimum distance between proxy windows when adjusting for collisions. The default is 10.

       *FvwmProxy: ShowMiniIcons bool
	      If true, proxy windows show the mini icon for the window they represent, if it has a mini icon.  The default is true.

       *FvwmProxy: EnterSelect bool
	      If  true,  a  proxy  is  automatically  selected	when the mouse is moved over the proxy, even if no mouse buttons are pressed.  The
	      default is false.

       *FvwmProxy: ProxyMove bool
	      If true, moving a proxy window will move the window it represents.  Currently, the proxied window  doesn't  recognize  snap  effects
	      during this operation. The default is false.

       *FvwmProxy: ProxyIconified bool
	      If  true,  continue  to  proxy windows when they are iconified.  In addition, consider adding click actions that Iconify on and off,
	      such as on the middlemouse button. The default is false.

       *FvwmProxy: Action mouseaction response
	      Tells FvwmProxy to do the specified response when the given action is done.  The currently  supported  mouse  actions  are:  Click1,
	      Click2,  Click3  and so on, representing mouse clicks with various buttons.  By default, the module supports 3 mouse buttons, but it
	      can be compiled to support more.	The default responses are Raise, Nop, and Lower for Click1, Click2, and Click3, respectively.

       *FvwmProxy: Action Select command
	      This selects an fvwm function to be called during a FvwmProxy Hide command for the window whose proxy was selected.  The default	is
	      WindowListFunc.	WindowListFunc	is  predefined by the fvwm install.  You can replace it, add to it, or supply an independent func-
	      tion.

       *FvwmProxy: Action Show command
	      This selects an fvwm function to be called during a FvwmProxy Show command.  The default is Nop.

       *FvwmProxy: Action Hide command
	      This selects an fvwm function to be called during a FvwmProxy Hide command.  The default is Nop.

       *FvwmProxy: Action Abort command
	      This selects an fvwm function to be called during a FvwmProxy Abort command.  The default is Nop.

       *FvwmProxy: Action Mark command
	      This selects an fvwm function to be called on a window after it is marked.  The default is Nop.

       *FvwmProxy: Action Unmark command
	      This selects an fvwm function to be called on a marked window just after another window gets the mark.  The default is Nop.

       *FvwmProxy: Action ModifierRelease modifiers command
	      This selects an fvwm function to be called while proxies are shown and the specified modifiers are all released.	The modifiers  are
	      specified using the same syntax as in the Mouse command.	The default is Nop.

       *FvwmProxy: Group groupname command pattern
	      For the given named group, adjust inclusion of the windows matching the pattern.	The groupname is a string identifier used to asso-
	      ciate windows.  The window pattern uses the same format as the Style command.  The supported commands are Include, SoftInclude,  and
	      Exclude.	Include and SoftInclude identifies a pattern to add windows to the group.  Exclude identifies pattern to counteract inclu-
	      sion pattern or auto-inclusion (see flags below).  All exclusion checks follow all inclusion checks.  Soft inclusion limits the win-
	      dows  in that pattern to only move when an non-soft window in the group moves.  Moving or resizing these windows does not affect any
	      other windows.  They are also immune to edge effects.

       *FvwmProxy: Group groupname flag
	      For the given named group, activate the given flag.  The supported flags are  AutoInclude,  AutoSoft,  and  IgnoreIDs.   All  window
	      grouping	is normally checked to only group windows that are in the same process or that have the same X11 client leader.  IgnoreIDs
	      deactivates this mechanism.  AutoInclude automatically includes any window that matches the same process or client  leader,  without
	      having to name them specifically.  AutoSoft makes all AutoInclusions soft (see inclusion description above).

       *FvwmProxy: SlotWidth w
	      This specifies the width of the icons used in slots.  The default is 16.

       *FvwmProxy: SlotHeight h
	      This specifies the height of the icons used in slots.  The default is 16.

       *FvwmProxy: SlotSpace d
	      This specifies the space between icons used in slots.  The default is 4.

       *FvwmProxy: GroupSlot n
	      This specifies the first slot that represent a colored group.  Group slots don't need icons as the are drawn by predetermined means.
	      The default is 2.

       *FvwmProxy: GroupCount n
	      This specifies the number of group slots.  The default is 6.

       *FvwmProxy: SlotStyle n style
	      For non-group slots, this defines the appears of the indicated slot.  The style format matches ButtonStyle command.  The default	is
	      nothing.

       *FvwmProxy: SlotAction n mouseaction response
	      For  non-group  slots, this defines the behavior of the indicated slot.  The mouse action and response is used the same as the Fvwm-
	      Proxy Action configuration.  The default is Nop.

       *FvwmProxy: UndoLimit n
	      This specifies the number of entries in the undo buffer.	this limits how far back you can undo.	The default is 8.

COMMANDS

       SendToModule FvwmProxy Show
	      Activate proxy windows for all windows on the current desk that do not use the WindowListSkip option.  If the desk is switched,  new
	      proxies are automatically generated.

       SendToModule FvwmProxy Hide
	      Deactivate  all  proxy  windows.	If a proxy is selected (such as with the Next and Prev commands), the Select Action is call on the
	      window that the proxy represents.  The default action includes raising the window and warping the mouse to a position over that win-
	      dow.

       SendToModule FvwmProxy ShowToggle
	      If shown, hide.  If hidden, show.

       SendToModule FvwmProxy Abort
	      Deactivate all proxy windows.  This differs from the Hide command in that no action is taken on any selected window.

       SendToModule FvwmProxy Circulate command
	      Tell  FvwmProxy to run a conditional command and mark the result.  The imbedded command SendToModule FvwmProxy Mark is automatically
	      appended after the optional condition, so supplying your own imbedded command will probably fail.  An example argument to  Circulate
	      is  ScanForWindow East South (CurrentPage).  If the proxies aren't already shown (such as with the Show command), any Circulate com-
	      mand will automatically show the proxies.

       SendToModule FvwmProxy Next (obsolete)
	      If a proxy window is selected, the next proxy is selected.  Windows with the WindowListSkip option are  ignored.	 The  proxies  are
	      sorted  left to right during the Show command.  If no proxy is currently selected, but a proxy on this desk was selected on a recent
	      show, that proxy is selected.  If no proxy on this desk was recently selected, the leftmost proxy is used.  This	nearly	duplicates
	      the functionality of Circulate ScanForWindow East South (CurrentPage).

       SendToModule FvwmProxy Prev (obsolete)
	      If a proxy window is selected, the previous proxy is selected.  The starting point is the same as with the Next command, except that
	      the choice with no recent selection is the rightmost proxy.  This nearly duplicates the  functionality  of  Circulate  ScanForWindow
	      West North (CurrentPage).

       SendToModule FvwmProxy SoftToggle
	      Toggle  the  soft group inclusion setting for the selected window.  This setting is the same that can be activated using the SoftIn-
	      clude and AutoSoft commands inside the FvwmProxy Group configuration.

       SendToModule FvwmProxy IsolateToggle
	      Toggle the isolation setting for the selected window's group.  Isolated groups only allow one member to not be iconified at a  time.
	      The members are also coerced to the same position and size, constrained by their size increment.

       SendToModule FvwmProxy PrevIsolated
	      If  focused  on a member of a isolating group, deiconify the member higher on list.  If no member is higher, deiconify the last mem-
	      ber.

       SendToModule FvwmProxy NextIsolated
	      If focused on a member of a isolating group, deiconify the member lower on list.	If no member is higher, deiconify the  first  mem-
	      ber.

       SendToModule FvwmProxy Undo
	      Attempt to undo the last window move and/or resize.

       SendToModule FvwmProxy Redo
	      Attempt to redo the most recent Undo.  If another move or resize occurs since the previous undo, the redo buffer will be cleared.

SAMPLE CONFIGURATION

       The following are excerpts from a .fvwm2rc file which describe FvwmProxy initialization commands:

	   Key Tab A M SendToModule FvwmProxy Circulate 
	       ScanForWindow East South (CurrentPage)
	   Key Tab A SM SendToModule FvwmProxy Circulate 
	       ScanForWindow West North (CurrentPage)

	   *FvwmProxy: Action ModifierRelease M SendToModule FvwmProxy Hide

       But Meta-Shift-Tab can be awkward, so Meta-Q may be a better alternative.

	   Key Q A M SendToModule FvwmProxy Circulate 
	       ScanForWindow West North (CurrentPage)

       You  might  consider adding !Sticky to the (CurrentPage) conditional if you use Sticky for low-interactivity programs, like load meters and
       music players.

       To have the proxies immediately pop up when you hold the Alt key, add

	   Key Meta_L A N SendToModule FvwmProxy Show

       If that's too intrusive, you can assign Alt-Esc to switch the proxies on and off by adding

	   Key Escape A M SendToModule FvwmProxy ShowToggle

       Some platforms have problems where general Alt key combinations becoming otherwise dysfunctional after defining these  mappings.   If  this
       happens, it might be difficult to take full advantage of this module.

       To have the mouse jump to the center instead of the upper left corner, try adding

	   AddToFunc WindowListFunc
	   + I WarpToWindow 50 50

       or just make your own list function from scratch, for example

	   DestroyFunc WindowListFunc
	   AddToFunc WindowListFunc
	   + I WindowId $[w.id] Raise
	   + I WindowId $[w.id] WarpToWindow 50 50

       Note  that  the	default  configuration	does not activate any Next/Prev operations for Alt-Tab since that sequence is, by default, used by
       another module.	Adding appropriate key mappings to your .fvwm2rc will switch this responsibility to FvwmProxy.

       If you use ProxyIconified, you might consider adding Iconify actions.

	   AddToFunc WindowListFunc
	   + I WindowId $[w.id] Iconify Off

	   AddToFunc Raise-and-Deiconify
	   + I WindowId $[w.id] Raise
	   + I WindowId $[w.id] Iconify Off

	   *FvwmProxy: Action Click1 Raise-and-Deiconify
	   *FvwmProxy: Action Click2 Iconify

       You can set up some basic slots fairly easily.

       *FvwmProxy: GroupSlot 2
       *FvwmProxy: GroupCount 5

       *FvwmProxy: SlotStyle 1 MiniIcon
       *FvwmProxy: SlotStyle 7 Pixmap "squeeze.xpm"
       *FvwmProxy: SlotStyle 8 Pixmap "mini-up.xpm"
       *FvwmProxy: SlotStyle 9 Pixmap "mini-bball.xpm"
       *FvwmProxy: SlotStyle 10 Pixmap "mini-cross.xpm"

       *FvwmProxy: SlotAction 1 Click1 Popup WindowMenu
       *FvwmProxy: SlotAction 7 Click1 SendToModule FvwmProxy IsolateToggle
       *FvwmProxy: SlotAction 8 Click1 SendToModule FvwmProxy SoftToggle
       *FvwmProxy: SlotAction 9 Click1 Iconify
       *FvwmProxy: SlotAction 10 Click1 Delete

       In this example, WindowMenu is something you would have to define.  If your proxy width is too small, some slots can get cut off.

       Undo and redo can be easily mapped to any keys.

       Key Z A 3 SendToModule FvwmProxy Undo
       Key R A 3 SendToModule FvwmProxy Redo

       You can rotate through an isolated group using any keys.  For example, meta cursor-up and cursor-down could traverse the group.

       Key Up A 3 SendToModule FvwmProxy PrevIsolated
       Key Down A 3 SendToModule FvwmProxy NextIsolated

       A somewhat impractical example of a group definition using GIMP is as follows:

       *FvwmProxy: Group "GIMP" Include "The GIMP"
       *FvwmProxy: Group "GIMP" Include "Module Manager"
       *FvwmProxy: Group "GIMP" SoftInclude "Unit Editor"
       *FvwmProxy: Group "GIMP" AutoInclude
       *FvwmProxy: Group "GIMP" AutoSoft
       *FvwmProxy: Group "GIMP" Exclude "Preferences"

       This sets up a hard attachment between the windows "The GIMP" and "Module Manager".  The "Unit Editor" is  also	in  the  group,  but  only
       responds  to movement of one of the hard inclusions.  Any window in the same process or with the same client leader is also associated, but
       they default to soft inclusion, except "Preferences" which is explicitly excluded.  Note that in this case, the explicit soft inclusion	of
       "Unit  Editor" is redundant with the combination of AutoInclude and AutoSoft.  However, if AutoSoft was not specified, the explicit SoftIn-
       clude would distinguish that pattern from the otherwise hard inclusion under just AutoInclude.

AUTHOR

       Jason Weber

3rd Berkeley Distribution					7 May 208 (2.5.26)						      FvwmProxy(1)