v05i064: Xrooms -- A Rooms implementation for X, Part14/14

[Kent Landfield]

Submitted-by: wsl.dec.com!mikey (Mike Yang)
Posting-number: Volume 5, Issue 64
Archive-name: xrooms/part14

#! /bin/sh
# This is a shell archive.  Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file".  To overwrite existing
# files, type "sh file -c".  You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g..  If this archive is complete, you
# will see the following message at the end:
#		"End of archive 14 (of 14)."
# Contents:  ./doc/xrooms.man
# Wrapped by kent at ssbell on Sun Jan 14 21:58:27 1990
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f './doc/xrooms.man' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'./doc/xrooms.man'\"
else
echo shar: Extracting \"'./doc/xrooms.man'\" \(32081 characters\)
sed "s/^X//" >'./doc/xrooms.man' <<'END_OF_FILE'
X.de BX
X.sp
X.nf
X.in +5
X.ft C
X..
X.de EX
X.ft P
X.fi
X.sp
X.in -5
X..
X.TH XROOMS 1 "Contrib" "X Version 11"
X.SH NAME
Xxrooms \- rooms for X
X.SH SYNOPSIS
X.B xrooms
X[-\fItoolkitoption\fP ...] [-option ...]
X.SH DESCRIPTION
X.sp
X\fBXrooms\fP is an implementation of rooms for X.  It organizes
Xwindows into related groups, called \(lqrooms.\(rq   A room typically
Xcontains all of the windows relating to a particular task or context; reading 
Xmail or developing a particular application, for example.  \fBXrooms\fP 
Xmanages the position and state of the windows in each room, and makes it easy 
Xfor users to switch from room to room.
X.sp
X\fBXrooms\fP is not a window manager;  it cooperates with ICCCM compliant
Xwindow managers, iconfying, de-iconifying, and reconfiguring windows whenever
Xthe user switches rooms.   Because they do not recognize the standard 
Xmechanisms for changing windows, \fBXrooms\fP may not work with some older, 
Xnon-ICCCM compliant window managers, \fBXrooms\fP accepts a number of options 
Xto use some common but non-standard methods for reconfiguring windows, and
Xcan be made to work with any window manager that allows clients to reconfigure,
Xiconify, and de-iconify themselves.   \fBXrset\fP is an application that
Xyou can use from another shell, a shell-script, or a window manager menu
Xto modify your rooms and applications.
X.sp 2
X.SH OPTIONS
X\fBXrooms\fP accepts all of the standard X Toolkit command line options as well as the following:
X.TP 8
X.B \-allrooms
XSet the default visibility for all rooms to \fIAlways\fP.
X.TP 8
X.B \-appnameatom " atom name"
XAnnotate application top level windows with a property of the specified
Xname which contains the name that \fBxrooms\fP uses for the application.
XThe default name for this property is _XROOMS_APP_NAME.
X.TP 8
X.B \-appstransient
XSet the default permanence for applications that are not specified in
Xyour .xroomsrc to \fITransient\fP (default).
X.TP 8
X.B \-appspermanent
XSet the default permanence for applications that are not specified in
Xyour .xroomsrc to \fIPermanent\fP (default).
X.TP 8
X.B \-autorooms
XSet the default visibility for all rooms to \fIWhenNonEmpty WhenActive\fP.
X.TP 8
X.B \-backup
XCreate a backup of your .xroomsrc in .xroomsrc.bak before overwriting it 
Xthe first time.
X.TP 8
X.B \-btncols
XSet the number of room buttons per row in the main window.
X.TP 8
X.B \-config " file name"
XRead configuration information from the specified file instead of the
Xfile .xroomsrc in your home directory.
X.TP 8
X.B \-debug " debugging values"
XSet debugging variables in \fBxrooms\fP if it was compiled -DDEBUG.
X.TP 8
X.B \-dfltroom " room name"
XSet the name of the default room to the specified value.
X.TP
X.B \-iconifyfirst
X.TP 8
X.B \-iconifylast
XSet the the order that applications are changed when you enter a room.
XIf you choose \fB-iconifyfirst\fP, those applications that are
Xiconic in the new room are iconified first, then applications are moved
Xas necessary;  finally, those applications that should be open in the new
Xroom are de-iconified.    If you specify \fB-iconifylast\fP, the order
Xis reversed:  first de-iconify, then move, then de-iconify.   The X server
Xgenerates many fewer events when you iconify first, so changing rooms is 
Xfaster.   Some X clients have a race condition that may cause them to exit
Xif they are iconified unexpectedly; these applications may disappear
Xif you run \fB-iconifyfirst\fP.    The default is \fB-iconifyfirst\fP; you
Xshould only change this if you notice applications dying.
X.TP 8
X.B \-ignoreappnames
XDo \fBnot\fP use the \fC_XROOMS_APP_NAME\fP property to determine the name of 
Xan application whenever the name resolution template in your .xroomsrc fails 
Xto find an application name.  When this flag is specified, \fBxrooms\fP will 
Xuse the \fCWM_NAME\fP or \fCWM_ICON_NAME\fP property depending on the setting 
Xof the \fBUseWindowNames\fP resource.   Use this flag if a previous invocation
Xof \fBxrooms\fP has stored incorrect application names for some windows.
X.TP 8
X.B \-namelookup " template name"
XUse the named template to determine application names.  \fBXrooms\fP uses the
Xtemplate named \(lqChooseAppName\(rq by default.
X.TP 8
X.B \-setupmode 
XStart in set-up mode if the user does not have a profile file.  
XThis is the default.
X.TP 8
X.B \-noconfirm
XDo not ask the user if she really wants to exit \fBxrooms\fP.  Exit
Ximmediately.
X.TP 8
X.B \-nogeometries
XDo not manage application geometries in rooms;  track only window state.
X.TP 8
X.B \-noappnameatom
XDo not annotate application top level windows with a property containing
Xthe name that \fBxrooms\fP uses for the application.
X.TP 8
X.B \-nosetupmode 
XDo not enter set-up mode automatically if the user does not have a profile
Xfile.
X.TP 8
X.B \-notransients
XDo not manage any windows with the property \fCWM_TRANSIENT_FOR\fP.
XThis is the default.  Note that \fImwm\fP considers its icon box to be 
Xa transient window.
X.TP 8
X.B \-noversion
XDo not print version identification when \fBxrooms\fP is started.  This
Xis the default.
X.TP 8
X.B \-nowarnings
XDo not print any warning messages.
X.TP 8
X.B \-nowithdrawn
XDo not manage withdrawn windows.   Treat withdrawn windows as if they
Xwere closed.    This is the default.  Note that the state of transient 
Xapplications is \fBnot\fP preserved if the application is withdrawn.
X.TP 8
X.B \-saverooms
XSave the local state of permanent applications in each room with the room
Xprofile in your .xroomsrc.
X.TP 8
X.B \-saveapps
XSave the local state of permanent applications in each room with the 
Xapplication profile in your .xroomsrc.
X.TP 8
X.B \-transients
XManage windows that have the \fCWM_TRANSIENT_FOR\fP property.   Use this
Xflag if you want \fBxrooms\fP to manage the \fImwm\fP icon box.   \fBXrooms\fP
Xruns a little more slowly if \fB-transients\fP is defined.
X.TP 8
X.B \-useappnames
XLook for the \fC_XROOMS_APP_NAME\fP property to determine the name of an 
Xapplication if the name resolution template in your .xroomsrc fails to find an
Xapplication name.  This is the default.   If an application window does not 
Xhave this property, \fBxrooms\fP will use the \fCWM_NAME\fP or 
X\fCWM_ICON_NAME\fP property depending on the setting of the 
X\fBUseWindowNames\fP resource.
X.TP 8
X.B \-useiconnames
XUse the \fCWM_ICON_NAME\fP property to determine the name of an application if
Xthe name resolution template in your .xroomsrc fails to find an
Xapplication name.  This is the default.
X.TP 8
X.B \-usewinnames
XUse the \fCWM_NAME\fP property to determine the name of an application if
Xthe name resolution template in your .xroomsrc fails to find an 
Xapplication name, and the window has no \fC_XROOMS_APP_NAME\fP.
X.TP 8
X.B \-version
X.br
XPrint a version identification string when \fBxrooms\fP starts.
X.TP 8
X.B \-warnings
XPrint warning messages.  This is the default.
X.TP 8
X.B \-withdrawn
XManage withdrawn windows.
X.sp
X\fBXrooms\fP works best with ICCCM compliant window managers (such as mwm
Xor release 4 twm).  Use the following arguments to tell \fBxrooms\fP to try 
Xsome of these non-standard methods for reconfiguring windows:
X.TP 8
X.B \-nonicccm
XUse this flag whenever you use a non-ICCCM compliant window manager.
X\fBXrooms\fP also accepts the argument \(lq\fB-icccm\fP.\(rq
X.TP 8
X.B \-fakeroot
XUse this flag if your window manager reparents all windows into a pseudo-root
Xwindow.    Note that the heuristics that \fBxrooms\fP uses to find the 
Xpseudo-root window work with dxwm, but may not work with all window 
Xmanagers.   \fBXrooms\fP also accepts the \(lq\fB-realroot\fP\(rq argument.
X.TP 8
X.B \-fakestate
XUse this flag if your window manager does not always attach the \fCWM_STATE\fP
Xproperty to application windows.   The \fB-fakestate\fP argument tells
X\fBxrooms\fP to manage all windows with a \fCWM_NAME\fP property, and to assume
Xthat all unmapped windows with \fCWM_NAME\fP and without \fCWM_STATE\fP 
Xare iconified. Note that this flag may cause unexpected behavior for any 
Xwindows an application has withdrawn.
X.TP 8
X.B \-unmapforgeom
XUse this flag to unmap and remap client windows whenever \fBxrooms\fP
Xreconfigures a window.
X.TP 8
X.B \-unmapforstate
XUse this flag to unmap and remap client windows whenever \fBxrooms\fP
Xchanges the state of a window.
X.TP 8
X.B \-dxwm
X.br
XSets \fB-nonicccm\fP, \fB-fakeroot\fP, \fB-reopenforgeom\fP, and 
X\fB-fakestate\fP.    \fBXrooms\fP cannot move windows unless you
Xspecify \fB-unmapforgeom\fP, but this has some unusual side-effects,
Xparticularly in setup mode and for transient apps.   You might want
Xto experiment, but we recommend you keep your window positions
Xconsistent across your rooms.
X.TP 8
X.sp 2
X.SH TERMINOLOGY
X.sp
XEach top-level X window is an application.   If an X client creates
Xmore than one window, \fBxrooms\fP considers each window to be a different
Xapplication.  
X.sp
XA \fIpermanent\fP application has consistent behavior across
Xinvocations of the application; i.e. if the X window that corresponds to a
Xpermanent application is closed, any subsequent window with the same 
Xapplication name will appear in the same place in all rooms as the previous
Xwindow.  The placement and state of a transient application is not affected
Xby the state of earlier windows with the same name.  \fBXrooms\fP writes 
Xprofiles for permanent applications in your .xroomsrc file, but does not 
Xrecord the profiles of transient applications.
X.sp
XAn application state describes a real or desired appearance of an 
Xapplication window.  An application state is essentially a \fIwindow state\fP
Xand an X geometry specification.
X.sp
XThe window state may be any of Normal (Open), Iconic, Withdrawn, or Inactive.
XA normal window is open and visible on the screen.   An iconic window is not 
Xvisible, but has a visible icon which represents it.  A withdrawn window 
Xexists, but is hidden and does not have an icon.  An inactive window is a
Xplaceholder for the window of a permanent application that is not currently 
Xrunning.  \fBXrooms\fP will not modify withdrawn or inactive windows.
X.sp
XA real application state always completely describes the appearance of the 
Xwindow at the current time.  A desired state corresponds to one or
Xmore rooms, and describes the appearance a window should have whenever 
Xone of those rooms is active.   Real application states must be fully
Xspecified with positive values of X and Y; desired states may have unspecified
Xparts, and negative values of X or Y.   
X.sp
XAn application has a current state, a default state, and may have 
Xa number of room states.  The current state is fully specified and always
Xmatches the state of the window. When a window changes state, \fBxrooms\fP
Xupdates the current state of the corresponding application.    Each room
Xstate corresponds to one specific room, and describes the geometry and state 
Xthe application should have whenever that room is active.  The default
Xstate describes the appearance the application should take in any room that
Xdoes not have an explicit room state.  An application is local to a room 
Xif it has a room state specific to that room.   A room is empty when
Xit has no active local applications.
X.sp
XA room is visible whenever \fBxrooms\fP displays a button for that
Xroom.   A room may be made visible or hidden explicitly, or may have some
Xcombination of several automatic visibility controls.   \fBXrooms\fP checks
Xautomatic visibility controls whenever a room is activated or an application
Xchanges state.  A room that is \fIAlways\fP visible becomes visible if hidden
Xwhenever \fBxrooms\fP checks visibility.  A rooms that is visible 
X\fIwhenActive\fP is visible as long as it is active;  if such a room is 
Xdeactivated and no other automatic visibility controls apply, the button for
Xthe room will disappear.    The button for a room that is visible 
X\fIwhenNonEmpty\fP is displayed whenever that room has at least one application
Xwith local state.   When the last local application exits, the button for the
Xroom disappears unless some other automatic visibility control applies to the
Xroom.   By default, rooms are visible when active or non-empty.  To make rooms
Xbe always visible, specify \fB-allrooms\fP on the command line when you start
X\fBxrooms\fP.
X.sp 2
X.SH "STARTING XROOMS"
X.sp
XOn startup, \fBxrooms\fP looks for the file .xroomsrc in your home directory
Xfor a profile of the rules you use to choose application names, the permanent 
Xapplications you expect, and the rooms you use.   If you start \fBxrooms\fP
Xwithout a profile file, some of the defaults specified above are changed
Xto values more appropriate for setting up your profile.  This different
Xset of defaults is called set-up mode.  You can disable the set-up
Xmode defaults by specifying \fB-nosetupmode\fP on the command line.
XYou can explicitly enter or leave set-up mode with the \(lqEnable/Disable Set-up
XMode\(rq menu item.  Set-up mode is automatically disabled whenever you save 
Xyour profile to a file.
X.sp
XThe default name of the first room that \fBxrooms\fP creates in \(lqMain.\(rq
XUse the \fB-dfltroom\fP flag to specify a different name.
X.sp
XUnder normal operation, any application for which \fBxrooms\fP does not 
Xhave a profile starts open in the room in which it first appears and 
Xiconic everywhere else.   
XThis is usually correct behavior when \fBxrooms\fP is already set up and you 
Xare starting a single new application.  When you first invoke \fBxrooms\fP, 
Xhowever, all applications first appear in the default room.   If you were to 
Xcreate another room and switch to it, all of your applications, including 
X\fBxrooms\fP, any icon boxes, clocks etc would be iconified.    In set-up
Xmode, \fBxrooms\fP tries to identify its control panel, any icon boxes, 
Xclocks, load monitors, or biffs, and initialize these applications 
Xto be open in every room.
X.sp
XBy default, applications are transient.   If your profile is already correct,
Xand you start some X client, say \(lqxfd\(rq, you don't necessarily want all 
Xfuture invocations of xfd to start up open only in the room you were in the 
Xfirst time you ran \(lqxfd\(rq.  We assume you are arranging your normal
Xworking set of windows in setup mode, so all applications are permanent.
X.sp
XThe options in the \(lqChange States\(rq menu normally expect you to
Xchoose a single application to modify.    In set-up mode, you can select
Xmultiple applications.   To cancel the crosshair cursor, and stop modifying 
Xapplication states, select the root window, or press any two mouse buttons 
Xsimultaneously.
X.sp
XOnce \fBxrooms\fP is started, you can create rooms using the menu, and
Xcustomize each room using familiar window manager commands and the
Xoptions in the \(lqChange States\(rq menu.   Once you have all rooms set 
Xup the way you like them, save your .xroomsc using the \(lqSave Profile\(rq 
Xchoice in the main menu.   Setup mode ends automatically when you save to a 
Xprofile file.
X.sp 2
X.SH "PROFILE FILES"
X.sp
X\fBXrooms\fP looks for setup information in the file \(lq.xroomsrc\(rq in 
Xyour home directory.   An \fBxrooms\fP profile file consists of three sections.
XThe sharp character `#' comments to the end of any line in your profile.
X.sp
XWe will discuss the first section of a profile file, application name 
Xprofiles, in the section \fBAPPLICATION NAMES\fP below.    
X.sp
XThe second section contains application profiles -- a description of each 
Xpermanent application you have defined.   Each profile contains the 
Xname of the application, the default state of the application, and an
Xoptional list of room states for the application.   Here are some example
Xapplication profiles:
X.BX
Xapplication "xrooms"       [ normal =325x100-305-5 ]
Xapplication "xterm-right"  [ iconic ] {
X       "Work"              [ normal =-5+35 ]
X}
Xapplication "xeyes"        [ normal =150x100+5+5 ] {
X       "Work"              [ normal =-5+5 ]
X       "Mail"              [ normal =150x100-5-5 ]
X       "News"              [ normal =+5-5 ]
X}
X.EX
XThe application named \fBxrooms\fP is open and has the same geometry in all 
Xrooms.  The application named \fBxterm-right\fP is iconic in all rooms except
X\(lqMail,\(rq and \fBxeyes\fP moves from corner to corner as you switch rooms.
XThe \fBxeyes\fP is in the top left corner of any room that is not listed 
Xexplicitly.
X.sp
XThe room profiles follow the application profiles in your .xroomsrc file.
XThe syntax of room profiles is similar to that of application profiles;
Xa room profile consists of a room name, the visibility of the room, and
Xan optional list of local applications.   Here are some example room
Xprofiles:
X.BX
Xroom "Work"           visible always {
X     "xterm-right"     [ normal =-5+30 ]
X     "xterm-left"      [ normal =+5+60 ]
X     "xeyes"           [ normal =-5+5 ]
X}
Xroom "Mail"           visible whenNonEmpty whenActive {
X     "Mail-Read"       [ normal =500x650+25+85 ]
X}
Xroom "Games"          visible whenNonEmpty  {
X     "Xtank"           [ normal =+0+0 ]
X}
Xroom "TopSecret"      hidden
X.EX
XThe Work room might contain two terminal emulators and xeyes, but 
Xsome or all of these applications might not be active at any given time.    
XThe button for this room is displayed at all times, even if none of the local
Xapplications are are active.
X.sp
XThe \(lqMail\(rq room contains a mail reader window.  The button for the
Xroom is displayed whenever you are in mail room or the mail reader is
Xactive.  
X.sp
XThe button for the \(lqGames\(rq room is visible only when \fBXtank\fP is
Xactive;  as soon as \fBXtank\fP exits, the button for the room will
Xdisappear.  If you are in the games room, xrooms will move you to your
Xdefault room.
X.sp
XThe button for the \(lqTopSecret\(rq room is never visible unless it is
Xexplicitly exposed using the \fBxrset\fP command.
X.sp
XYou might note that it is possible for room profiles and application
Xprofiles to conflict, as the profiles for \fBxterm-right\fP and \(lqWork\(rq
Xdo, above.    When \fBxrooms\fP writes a profile file, it writes local 
Xstates with either the room profiles or the application profiles.   The
X\fB-saverooms\fP and \fB-saveapps\fP options specify which set of profiles 
Xshould list the local states.   The default is to list local states in the room
Xprofiles.
X.sp 2
X.SH "APPLICATION NAMES"
X.sp
X\fBXrooms\fP assumes that application names are unique, but it is not always 
Xstraightforward to uniquely identify windows.    X defines two standard 
Xwindow name properties, \fCWM_NAME\fP and \fCWM_ICON_NAME\fP, but it is 
Xcommon for several windows to have the same icon or title bar name.
X.sp
XSome applications change their title bar or icon names to reflect changes
Xin the application.   To help you identify these applications, \fBxrooms\fP
Xprints a warning message if your .xroomsrc does not have an application
Xname profile and an application changes one of the \fCWM_NAME\fP or
X\fCWM_ICON_NAME\fP properties, and your .xroomsrc does not have an 
Xapplication name profile.  You can disable this check and warning message
Xwith the \fB-nowarnings\fP flag.  This section describes the tools that 
X\fBxrooms\fP includes to help you name applications consistently every time.
X.sp
XTo insure that application names are unique, \fBxrooms\fP appends a
X\(lq-number\(rq prefix to any application whose name clashes with
Xanother running application.   For example, the first \fBxterm\fP that
X\fBxrooms\fP encounters might be named \(lqxterm,\(rq the second
X\(lqxterm-1,\(rq and so on.    Unfortunately, there is no guarantee that
Xany subsequent invocation of \fBxrooms\fP will assign the suffixes in the
Xsame order.
X.sp
XTo help solve this ordering problem, \fBxrooms\fP attaches the
Xproperty \fC_XROOMS_APP_NAME\fP to each client window.  This property contains 
Xthe name that \fBxrooms\fP chose for the application, to each client window.   
XWhen \fBxrooms\fP starts up, it looks first for the \fC_XROOMS_APP_NAME\fP
Xproperty, then for \fCWM_ICON_NAME\fP, and finally for a \fCWM_NAME\fP 
Xproperty.   To use a different property for the application name, use the 
X\fB-appnameatom\fP option, or the \fB-noappnameatom\fP flag to attach 
Xno property.   To ignore existing \fC_XROOMS_APP_NAME\fP properties
Xwhen \fBxrooms\fP is invoked, use the \fB-ignoreappnames\fP option (this is
Xuseful if some earlier invocation of \fBxrooms\fP has decorated all of the
Xwindows with the wrong names).   
X.sp
XThe application name profile in your .xroomsrc is a better solution to the 
Xproblem of application name resolution.    The application name profile
Xis one or more templates in a small programming language that \fBxrooms\fP 
Xinterprets.   This language allows you to examine and modify window properties,
Xcompare strings to regular expressions (and extract sub-expressions), and
Xconcatenate strings.
X.sp
XEach template has a name, and you can choose the name of the
Xtemplate to use to resolve names with the \fB-namelookup\fP option on the
Xcommand line.  If you do not specify a template name, \fBxrooms\fP looks
Xfor a template named \(lqChooseAppName.\(rq
X.sp
XEach template has a name and a body of statements and expressions.  The
Xlegal types of string expressions are:
X.sp
XProperty names enclosed in angle brackets: \fC<_XROOMS_APP_NAME>\fP, for 
Xexample.  The value of a property is the string value of the named property
Xon the window whose name we are resolving.   A property that is a list of 
Xstrings is concatenated with a single space. A property of type 
X\fCWM_SIZE_HINTS\fP is converted to an X syntax geometry, and a property of
Xtype \fCWM_STATE\fP is converted to one of \(lqnormal,\(rq \(lqiconic,\(rq
X\(lqwithdrawn,\(rq or \(lqinactive.\(rq
X.sp
XString literals, surrounded by double quotes, or identifiers.   The only
Xidentifier that is defined right now is \fIcurrentroom\fP, which returns
Xthe name of the current room.
X.sp
XConcatenation:   The \(lq+\(rq operator may be used to concatenate any
Xtwo string expressions.
X.sp
XConditional expression, with syntax similar to the C conditional expression:
X.BX
X( BooleanExpr  ?  StringExpr : StringExpr )
X.EX
XThe legal boolean expressions are:
X.sp
XRegular expression comparison, where the left hand side is a regular expression;
Xthe expression returns True if the right hand side matches the expression.
X.BX
XStringExpr == StringExpr
X.EX
XAny string expression can be used in place of a boolean;  any non-NULL
Xstring evaluates to True.    The operator \(lq!\(rq may be used to negate
Xany boolean expression.
XLegal statements are:
X.BX
Xif ( BooleanExpr ) Statement [ else Statement ]
X.EX
XA fairly traditional if statement, with a twist.  If the BooleanExpr
Xwas a regular expression comparison, any sub-expressions may be included
Xin string literals in the else statement as \(lq\\1\(r1, \(lq\\2\(rq, etc.
XIf the BooleanExpr was some other string expression, the entire string
Xis accesible as \(lq\\1.\(rq   There is no string to substitute in the
Xelse clause, or if the boolean expression was a negation.  Sub-expressions
Xin the regular expression are delineated with \\( and \\).
X.BX
Xswitch ( StringExpr) {
X    case StringExpr:  Statement
X	:
X    [ default: Statement ]
X}
X.EX
XA switch statement.  Each case label is a regular expression which is
Xcompared in turn against the switch expression.    The first case that
Xmatches is executed.   Any sub-expressions in the case expression may
Xbe included in string literals of the associated statements.  Unlike C,
Xeach case terminates at its successsor.
X.BX
Xuse StringExpr
Xignore
X.EX
XIf the StringExpr for a use statement evaluates to non-NULL, the use statement 
Xreturns a value to be used as the application name and no more statements
Xare evaluated (like a C return statement).   If the StringExpr evaluates to
XNULL, the remaining statements are evaluated.  The ignore statement tells
X\fBxrooms\fP not to manage this window.
XThe lanaguage also includes a C-like block statement, and an assignment 
Xstatement: 
X.BX
X{
X   Statement 1
X   Statement 2
X     ...
X   Statment N
X}
X
X<PROPERTY> = StringExpr
XIdentifier = StringExpr
X.EX
XAssigning a string to a <PROPERTY> attaches a property of type \fCXA_STRING\fP,
Xwith the specified name to the window being examined.   Any previous contents 
Xof the property are lost.   If a template assigns a string to the identifier 
X\fIcurrentroom\fP \fBxrooms\fP will switch to a room with that name.   If
Xno such room exists, \fBxrooms\fP creates it first.
X.sp
XHere are some examples of name templates:
X.BX
X# Some programs change the name in their title
X# bar or icon.   Dxmail likes to insert folder 
X# names; this expression extracts the type of window
X# So I get "Mail-Read," "Mail-Create" and so on.
X# Likewise, the calendar puts the current time and
X# date in the icon and a file name in the title
X# bar.
Xnames "ChooseAppName" {
X    use <_XROOMS_APP_NAME>
X    switch <WM_NAME> {
X       case "iconbox":         use "iconbox"
X       case "Mail: *\\([^ 	]*\\).*":	use "Mail-\\1"
X       case ".*[Cc]alendar.*":	use "Calendar"
X    }
X    if ( <WM_TRANSIENT_FOR> )	ignore
X    if ( <_XROOMS_IGNORE_ME> )	ignore
X    use <WM_ICON_NAME>
X    use <WM_NAME>
X}
X# Here is a hack you can use to specify unique names for 
X# all of your applications.   The toolkit accepts any 
X# string after an -xrm argument.    ICCCM compliant 
X# applications report the entire command line that 
X# was used to invoke them, so...
Xname "HackInstanceName" {
X    if ( WM_COMMAND == ".*InstanceName:\\([^ ]*\\).*" )
X	use \1
X    ignore
X}
X.EX
X.sp 2
X.SH "BOLTS"
X.sp
XBolts are a feature unique to \fBxrooms\fP (we think).   Any part of an
Xapplication state may be bolted.   Normally, when the state of a window
Xchanges, \fBxrooms\fP notes the change and preserves the new state.  If
Xa part of the state is bolted, however, \fBxrooms\fP will restore that
Xpart of the state.   Exclamation points specify bolts in your .xroomsrc, or 
Xyou may use the \fBxrooms\fP menu.  To bolt the window state of an application
Xfrom a profile file, follow the window state with an exclamation point. 
XFor example if the room Work is specified like this:
X.BX
Xroom "Work"           visible always {
X     "xterm-right"     [ normal! =-5+30 ]
X     "xterm-left"      [ normal! =+5+60 ]
X     "xeyes"           [ normal =-5+5 ]
X}
X.EX
XYou cannot iconify either xterm.  If you do, \fBxrooms\fP will immediately
Xreopen them.
X.sp
XTo bolt some parts of a geometry:
X.BX
Xapplication "xeyes"        [ normal =150x100+5+5 ] {
X       "Work"              [ normal =-5+5 xy! ]
X       "Mail"              [ normal! =150x100-5-5 whxy! ]
X       "News"              [ normal =+5-5 x! ]
X}
X.EX
XIn the room \(lqWork,\(rq you can resize xeyes, but \fBxrooms\fP will keep
Xthe upper right hand corner of xeyes in the upper right hand corner of
Xthe screen.   In the Mail room, \fBxrooms\fP will undo any changes you
Xmake to xeyes.   In the News rooms, you can resize xeyes at will, and move
Xit anywhere along the left side of the screen.
X.sp
XIt's a long story.  We know this doesn't belong in rooms, but we think
Xits neat.  
X.sp 2
X.SH "COMMAND MENU"
X.sp
XClick and release the middle button anywhere in the \fBxrooms\fP control
Xpanel to invoke the main menu.   The menu will stay posted until you select
Xa menu item with the left mouse button.   To cancel a menu, select the
X\(lqClose Menu\(rq option in either menu.
X.sp
XMost of the options on the command menu are straightforward.  The entries
Xon the \(lqChange States\(rq menu modify the profiled states of individual
Xapplications.  Each entry gives you a crosshair cursor to select the 
Xapplication you want to modify.  To cancel any choice, select
Xthe root window, or press any two mouse buttons simultaneously.
XIn set-up mode, you can select more than one application.  The crosshairs
Xcursor will stay until you cancel the operation.  Be sure not to click on
Xa window unless you want to modify some part of its state.
X.sp
XThe \(lqOpen In All Rooms,\(rq \(lqOpen Here Only,\(rq \(lqBolt Geometry,\(rq
Xand \(lqUnbolt Geometry\(rq selections all affect different parts of an 
Xapplication state depending on where you click in the application window and 
Xhow you sweep the mouse after you click.   Clicking in any corner specifies
Xthe corresponding positive or negative values for X and Y.  Clicking
Xalong the edge of a window specifies only one of X or Y, as appropriate.
XSweeping across more that a third of the width of a window modifies
Xthe width part of the application state, and likewise for height.  
X.sp
XThe \(lqOpen In All Rooms\(rq selection sets the state of the selected 
Xapplication in all rooms to be open, with the currently visible geometry.  
XIt removes all local states and sets the default to the visible state.   
Xany bolts on the application state are cleared.   The \fBxrooms\fP program
Xwill store only those parts of the state that you select as described above.
XFor example, if you click and release in the upper left corner of a window 
Xwhose real geometry is \(lq=100x100+100+100\(rq and the screen is 1000 pixels
Xin each dimension, the default geometry of the application will be set 
Xto  \(lq=+100+100.\(rq   If you click and release on the lower right corner, 
X\fBxrooms\fP will use the geometry \(lq=-800-800.\(rq   If you click halfway
Xdown the left edge of the window and sweep the mouse to the lower right hand 
Xcorner before you release the button, \fBxrooms\fP will use the geometry
X\(lq=100x100+100.\(rq
X.sp
XThe \(lqOpen Local Only\(rq selection sets the default state of the selected 
Xapplication to iconic with the currently visible geometry, and the local 
Xstate to the visible state.  This command also uses the mouse press location 
Xand drag to determine which parts are set as described above.
X.sp
XThe \(lqBolt Geometry\(rq and \(lqUnbolt Geometry\(rq bolt or unbolt the parts 
Xof the application geometry specified by your mouse location and sweep.
XThe bolt operation bolts the state of x or y as it is defined in the state.
XClicking in any corner bolts both x and y; clicking along an edge selects
Xeither x or y.   If the profiled state of the application described above
Xis \(lq=+100+100\(rq, clicking along the right edge will bolt the geometry
Xas specfied, i.e. \(lq=+100+100 x!\(rq -- to bolt the right edge of the
Xapplication, you must first change the profiled state using the \(lqOpen
XLocal Only\(rq menu item or the \fBxrset\fP command.
X.sp
XThe \(lqBolt Window Open\(rq and \(lqUnbolt Window State\(rq operations 
Xaffect \fBonly\fP the window state of the specified application; they do not
Xaffect any bolts on the geometry.   Click anywhere in the application
Xto bolt or unbolt the window state.
X.sp
XThe bolt and unbolt operations affect the visible state of the application 
Xin the current room.   If the application has a state local to the current
Xroom, only that state is changed.   If the application in not local to the
Xcurrent room, the default state is updated.
X.sp
XThe \(lqMake Permanent\(rq and \(lqMake Transient\(rq affect the application
Xas a whole, not a specific state.   Click anywhere in the window to
Xchange the permanence of an application.
X.sp 2
X.SH "OTHER FEATURES"
X.sp
XThe \fBxrooms\fP program can communicate with other programs through a 
Xproperty on the root window.   Right now, it recognizes requests to change 
Xapplication state, permanence, room visibility, and to load profile 
Xinformation (the same format as your .xroomsrc).   The program \fBxrset\fP 
Xcan be used by shell-scripts and window manager menus to control the state 
Xof your rooms and applications.   Unfortunately, \fBxrset\fP is rather poorly
Xdocumented this release.  Be brave.  It's useful.  It has one heck of 
Xa usage screen.
X.sp
X\fBXrooms\fP stores the name of the current room in a property 
X\fC_XROOMS_CURRENT\fP on the root window.  A program \fBwallpaper\fP, 
Xwatches this property and invokes a command specified in your .wallpaperrc.   
XYou can use this to give each room a distinctive background.
X.sp
XThe property \fC_XROOMS_APP_NAME\fP contains a list of all visible rooms.
X.sp
X.SH "SEE ALSO"
XX(1)
X.sp 2
X.SH BUGS
X.sp
XThe \fBxrooms\fP program does not preserve the stacking order of windows
Xin a room.
X.sp 2
X.SH COPYRIGHT
XCopyright 1990, Digital Equipment Corp.
X.sp 2
X.SH AUTHORS
X.sp
XErik Fortune, Terry Weissman, Mike Yang (All DEC-UEG-WSL)
XPlease send bug reports, comments, or suggestions to:
Xxrooms at wsl.dec.com
END_OF_FILE
if test 32081 -ne `wc -c <'./doc/xrooms.man'`; then
    echo shar: \"'./doc/xrooms.man'\" unpacked with wrong size!
fi
# end of './doc/xrooms.man'
fi
echo shar: End of archive 14 \(of 14\).
cp /dev/null ark14isdone
MISSING=""
for I in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 ; do
    if test ! -f ark${I}isdone ; then
	MISSING="${MISSING} ${I}"
    fi
done
if test "${MISSING}" = "" ; then
    echo You have unpacked all 14 archives.
    rm -f ark[1-9]isdone ark[1-9][0-9]isdone
else
    echo You still need to unpack the following archives:
    echo "        " ${MISSING}
fi
##  End of shell archive.
exit 0