doc/commands/ScanForWindow.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!-- $Id: ScanForWindow.xml,v 1.3 2007/06/16 12:38:46 griph Exp $ -->
   3 <!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   4   "../docbook-xml/docbookx.dtd"
   5 [
   6 <!ENTITY % myents SYSTEM "../fvwm.ent" >
   7 %myents;
   8 ]>
   9
  10
  11 <section id='ScanForWindow'>
  12 <title>ScanForWindow</title>
  13
  14 <cmdsynopsis>
  15         <command>ScanForWindow</command
  16         ><arg choice='opt'>FromPointer</arg
  17         ><arg choice='plain'
  18                 ><replaceable>dir1</replaceable
  19         ></arg
  20         ><arg choice='plain'
  21                 ><replaceable>dir2</replaceable
  22         ></arg
  23         ><arg choice='opt'
  24                 >(<replaceable>conditions</replaceable
  25         >)</arg
  26         ><arg choice='plain'
  27                 ><replaceable>command</replaceable
  28         ></arg>
  29 </cmdsynopsis>
  30
  31 <para>Performs <replaceable>command</replaceable>
  32 (typically <fvwmref cmd="Focus"/>)
  33 on a window in the given direction which satisfies all
  34 <replaceable>conditions</replaceable>.
  35 Normally, the center of the currently focused window or the
  36 context window in which the command was invoked is taken as the
  37 starting point.  Lacking such a window, or when the
  38 <fvwmopt cmd="ScanForWindow" opt="FromPointer"/>
  39 option is given, the current position of the pointer is taken as
  40 the starting point.  The direction
  41 <replaceable>dir1</replaceable>
  42 may be one of "North", "NorthEast", "East", "SouthEast", "South",
  43 "SouthWest", "West", and "NorthWest".  Which window
  44 <emphasis remap='B'>ScanForWindow</emphasis>
  45 selects depends first on the position along the primary axis given
  46 by
  47 <replaceable>dir1</replaceable>.
  48 If any windows have the exact same coordinate along the primary
  49 axis, the secondary direction is used to order the windows.  The
  50 direction <replaceable>dir2</replaceable>
  51 may be one of the same set of values as
  52 <replaceable>dir1</replaceable>.
  53 If <replaceable>dir2</replaceable>
  54 is not perfectly perpendicular to
  55 <replaceable>dir1</replaceable>,
  56 ScanForWindow returns a failure.  When using ScanForWindow
  57 repeatedly with the same arguments, it is guaranteed that all
  58 windows matching the conditions will eventually be found.  If the
  59 focus reaches a limit along the primary axis, it will wrap around
  60 to the opposite side.  Returns -1 if an invalid direction was
  61 given.
  62 See <fvwmref sect="conditionals" opt="conditions" name="Conditions"/> section for a list of conditions.</para>
  63
  64 </section>