olvwmrc  -  Resource file for the OPEN LOOK Virtual Window
       Manager


SYNOPSIS

       $HOME/.olvwmrc


DESCRIPTION

        .olvwmrc is a file which controls advanced keybinding and
       menu  features  for  the  OPEN  LOOK Window Manager olvwm.
       Four features of olvwm are controlled by entries  in  this
       file:

       Local Variables
              which can be used in key or screen bindings

       Key Bindings
              which can map specific actions to function keys

       Screen Bindings
              which  can  control  where certain applications are
              started

       WINMENU
              entries which can control  the  behavior  of  items
              selected from the olvwm WINMENU menu.

       The syntax for each of these entries is given below.  Com-
       mon to all syntax entries is the notion  of  an  ``identi-
       fier'':   this  is  a string which somehow specifies which
       window(s) the given entry applies to.  When determining if
       a  particular  window  is affected by a particular rule in
       .olvwmrc, olvwm first checks a window's WM_NAME to see  if
       it  matches the identifier listed in the rule.  This match
       is done only for the length of the identifier, so that the
       identifier  Mail  will  match all windows which begin with
       the 4 letters Mail in their WM_NAME.   If  this  does  not
       match,  olvwm  next checks the instance and then the class
       fields of the window's WM_CLASS attribute to check  for  a
       possible  match.   If  a  match  is found for any of these
       fields, the window is affected by the given rule.  Case is
       significant in checking all matches.

       Identifiers  may contain any alpha-numeric characters; any
       other characters must be enclosed within quotes (single or
       double).   Thus,  Mail  is a valid identifier, as is "Mail
       Tool" but Mail Tool is not.  Similarly, strings which  are
       to  be  executed should be enclosed in quotes if they con-
       tain non alpha-numeric characters.  Quotes may  be  nested
       in  strings,  so  that to start a clock with the label foo
       bar,  you  would  specify   'clock  -label   "foo   bar"'.
       Finally, single quotes may be escaped with a backslash, so
       that the full WM_NAME of  DevGuide,  for  example,  should
       Variable  names  are  referenced by using %VariableName or
       %{VariableName}; %% will yield a single %.  Variable  ref-
       erences may appear as part of the definition of any key or
       screen binding.  Variable references may  also  appear  in
       assignment statements.

       In  addition to olvwm variables, environment variables may
       be used in the same contexts using the familiar  $NAME  or
       ${NAME} syntax; again, $$ will yield a single $.

       The following example illustrates the use of variables:

       #
       # Define screen size.
       #
       Xsize = '1136'
       Ysize = '798'

       WholeScreenSize = '%{Xsize}x%{Ysize}+3+3'

       #
       # Define file names.
       #
       FileName = '.olvwmrc'

       PathName = '$HOME/%FileName'


Key/Action Bindings

       olvwm  can  be  made to perform a series of actions when a
       specific key is pressed.  The  key  can  be  any  valid  X
       keysym name and may be specified by itself or with any one
       or more of the following modifiers:  Shift, Control,  Alt,
       Meta,  Hyper,  Super,  Shift  Lock, or Caps Lock, in which
       case the key must be pressed with the given modifiers.

       The functionality for a key  specified  in  a  binding  in
       .olvwmrc  takes  precedence  over any other functions that
       key might perform. Thus, if you bind  the  L5  key  to  an
       action in .olvwmrc, you will not be able to use the L5 key
       to bring windows to the front; if you bind the R8 key, you
       will  not  be  able to scroll up on the desktop using that
       key.  Since the unmodified versions of 29 of the  possible
       35  standard  function  keys on a type-4 keyboard (L1-L10,
       F1-F10, and R1-R15) already have a meaning  within  olvwm,
       it  is  recommended that at least one modifier be used for
       keys in this manner so as not to conflict with  other  key
       meanings.

       There  are  thirteen valid actions which can be associated
       with a key:

       Warp   This action  requires  a  single  identifier.   The

       Close  This action requires a list  of  identifiers  sepa-
              rated by commas.  Each non-iconified window will be
              matched against this list and those which match any
              identifier in the list will be closed.

       Raise  This  action  requires  a list of identifiers sepa-
              rated by  commas.   Each  window  will  be  matched
              against this list and those which match any identi-
              fier in the list will be raised.  Windows  will  be
              raised  youngest  first, so that the oldest windows
              in the list will end up on top.

       Lower  This action requires a list  of  identifiers  sepa-
              rated  by  commas.   Each  window  will  be matched
              against this list and those which match any identi-
              fier  in the list will be lowered.  Windows will be
              lowered youngest first, so that the oldest  windows
              in the list will end up on the bottom.

       RaiseLower
              This  action  requires  a list of identifiers sepa-
              rated by  commas.   Each  window  will  be  matched
              against this list and those which match any identi-
              fier in the list will be raised to the top  of  the
              stack  if they are partially obscured or lowered to
              the bottom of the stack if they are on top.

       Execute
              This action requires a list of  commands  separated
              by  commas.   Each  command  will be executed via a
              Bourne-shell in the same manner as  commands  given
              in  the  olvwm menu file [except that multiple com-
              mands may be listed in this case.]

       Goto   This action requires a  single  integer  parameter,
              which  is  the  logical screen to which the desktop
              should warp when the given key(s) are pressed.

       Quit   This action requires a list  of  identifiers  sepa-
              rated  by  commas.   Each  window  will  be matched
              against this list and those which match any identi-
              fier in the list will be killed.

       Geometry
              This  action  requires  a  single  identifier.  The
              identifier must be a valid X  geometry  string  but
              may  be partially specified (may only specify posi-
              tion or size).  This geometry will  be  applied  to
              the  current window.  If there is no current window
              this action will have no effect.

              toggled.  Similarly, if the parameter is a list  of
              window  names then those window's sticky attributes
              will be toggled.  The values on and off can be used
              to  explicitly  set  the  current  window's  sticky
              attribute.

       SetSize
              This action requires a single parameter which  must
              be one of the following: OLVWM_USE_SELECTION, full,
              save, store, restore, toggle, or a list  of  window
              names.   If the parameter is OLVWM_USE_SELECTION or
              toggle, either the window's current  geometry  will
              be  saved  and its size will be set to full size or
              its saved geometry will be restored,  depending  on
              the  window's  current  state.   Similarly,  if the
              parameter is a list of window names then  the  same
              action  will  be  performed for those windows.  The
              parameter save can be used to preserve the  current
              window's geometry such that a restore size (or tog-
              gle) will restore the windows  position  and  size.
              Note that save will only store the windows geometry
              if it has not already been  saved.   The  parameter
              store will always save a windows geometry (possibly
              overwriting the  currently  saved  geometry).   The
              restore  parameter  will simply restore the current
              window's saved geometry (if it has one).

       Focus  This action requires a single parameter which  must
              be either save or restore.  The save parameter will
              cause the window with focus to be  remembered  such
              that a restore will restore focus to that window.

       These  actions  may  appear  in any order and will be per-
       formed in the reverse of the  order  specified.   Commands
       may  be  listed multiple times; this is useful in case you
       want a different stacking  order  than  that  obtained  by
       using  a  single raise command.  To do this, list separate
       raise commands for each window and put the  raise  command
       for the window you want to be on top first.

       The full syntax for a Key/Action binding is

              KeyName { Actions }

       A Key Name is a valid key (L1-L10, F1-F10, or R1-R15) fol-
       lowed by plus signs and the modifiers desired.

       For example, given the following entry:

       L2 + Shift {
           Warp: "OpenWindows Developer\'s Guide"
           Execute: '$OPENWINHOME/bin/xview/clock -label "foo bar"',


Screen Bindings

       olvwm can arrange to begin any application relative  to  a
       particular  logical  screen.   A ``logical screen'' is the
       area on the virtual desktop which maps to the size of your
       monitor;  in  the  VDM, each logical screen is outlined in
       dashed lines (unless  you've  turned  this  feature  off).
       Screens  are  numbered  by row starting with 1.  Note that
       the position of a logical screen will  vary  depending  on
       the  size  of  a desktop:  in the default (2x3) configura-
       tion, screen 4 is in the bottom left-hand  corner  of  the
       VDM  but  in  a  smaller (2x2) configuration, it is in the
       bottom right-hand corner.

       The syntax for specifying a screen binding is

              Screen # { Identifiers }

       where # is the logical number of the  screen  and  Identi-
       fiers  is a list of comma-separated window identifiers for
       windows which should always start on  that  screen.   Note
       that  it  is always possible to move the window to another
       screen later.

       For example, the following entry will ensure that the win-
       dows started by Sun's AnswerBook (windows with names Navi-
       gator and Viewer) will always start on screen 6:

       Screen 6 { Navigator, Viewer }



WINMENU Actions

       When a window is selected in the WINMENU menu, olvwm  will
       perform  certain  actions.   The  possible actions are the
       same as those listed above for Key  Actions,  except  that
       the mouse position will not change on a warp.  By default,
       windows behave as if a warp, raise,  and  open  were  per-
       formed on the selected window.

       To effect a different action list for a particular window,
       you can specify

              Identifier { Actions }

       Each of these is a MenuGroup; one or  more  of  these  can
       appear in the following syntax:

              WINMENU { MenuGroups }

       For example, here is a possible entry:

       WINMENU {
       warp to your Mail Tool instead of your file  manager,  and
       your file manager, if closed, will be opened.  [This isn't
       that contrived an example: pretend your  file  manager  is
       sticky  and  your mail tool isn't, and you anticipate that
       you'll need to drag between the two.]

       If you select an xterm from your WINMENU, absolutely noth-
       ing will happen.  This implements a No-Op for that window.

       If you select the VDM from your WINMENU, it will be opened
       and the properties application will be started.

       Note  that  this  Identifier  list can contain the special
       entry OLVWM_USE_SELECTION  which,  as  you  might  expect,
       operates on the single window corresponding to the one you
       selected.  A subtle distinction exists  here:   given  the
       MenuGroup

              xterm { Raise:  xterm }

       then  ALL xterms will be raised when any xterm is selected
       via the WINMENU.  However, the entry

              xterm { Raise:  OLVWM_USE_SELECTION }

       will  raise  only  the  xterm  corresponding  to  the  one
       selected via the WINMENU.


RESOURCES AND KEY BINDINGS

       There  are  a  few  resources  which are particular to the
       operation of olvwmrc.


       VirtualReRead (boolean)
              When this resource is True, olvwm will re-read  the
              .olvwmrc  file  whenever it receives a Function Key
              event.  This will happen whenever a function key is
              pressed  in the VDM or on the root window, or when-
              ever a function key grabbed by  olvwm  is  pressed.
              Default value:  True


       NoVirtualKey (list of windows)
              This  resource  disables the virtual keys set up in
              .olvwmrc for a particular window.  The list of win-
              dows  follows  the  same  syntax  as other resource
              lists like MinimalDecor and VirtualSticky.  When  a
              window  in  this  list  has the input focus and the
              user executes a key sequence which is mentioned  in
              .olvwmrc,  that  key sequence will be passed to the
              application  rather  than  initiating  the  olvwmrc
              action.   Note  that this disabling applies only to
              keyboards) will be disabled for the  given  window.
              Default value:  None


       NoVirtualRKey (list of windows)
              This  resource  is  like NoVirtualKey, but only the
              keys R1 to R15 will be disabled for the given  win-
              dow.  Default value:  None


SEE ALSO

       olvwm(1), olwm(1)


NOTES

       Please  see  the LEGAL_NOTICES file for full disclosure of
       copyright information and olvwm(1) for acknowledgments.


BUGS

       The multiple interfaces  for  NoVirtualKeys  is  something
       only a Wall Street trader could appreciate.

MachTen                  30 November 1992                       7