Configuring placement of Xgopher popup windows
----------------------------------------------

Every Xgopher popup window has a default position that may be changed
by the installer or user via the Xgopher resources.  This configurability
will satisfy many needs: from the person who likes popups to appear at
predictable places to the power user who always wants a popup to
appear right at the mouse pointer to minimize movement.  A public-access
kiosk running Xgopher as a single application can have all popups appear
centered on the screen, a location which will have high-attention.

The positioning algorithm is straightforeward.  First, you identify
a location on the display.  The options are 

	. at the mouse pointer
	. relative to the Xgopher main window
	. relative to the display screen

For the last two, the point may be an integer offset in pixels from the
upper left corner of the window or display, or the offset may be 
specified as a percentage of the width (height) of the window or display.

Second, you pick the horizontal and vertical justification of the 
popup relative to that point.

Using this technique you can, for example, ask that the file copy
popup (the one that requests a file name) be positioned with the
center of its right edge coinciding with the center of the right edge
of the main Xgopher panel.  The desired effect is something like this:
	
	+-----------------+
	|  Xgopher window | 
	|                 | 
	|        +........+ 
	|        |  copy  | 
	|        | popup  | 
	|        +........+ 
	|                 | 
	|                 | 
	|                 | 
	+-----------------+

The resources to do this are:

	Xgopher.copyPopup.positionFrom:		application
	Xgopher.copyPopup.xPosition:		100
	Xgopher.copyPopup.xPercent:		True
	Xgopher.copyPopup.yPosition:		50
	Xgopher.copyPopup.yPercent:		True
	Xgopher.copyPopup.horizontalJustification:	Right
	Xgopher.copyPopup.verticalJustification:	Center

Here is a summary of these 7 resources with the resource names, class
names and the legal values.

	positionFrom		(class: PositionFrom)
				can take one of these values:
		
	    . pointer		The popup will be justified against the
				current mouse pointer (cursor) location.
				(xPosition, xPercent, yPosition, and yPercent
				are unused).

	    . application	The popup will be justified against a point
				within the Xgopher window.  If xPercent is
				True, the X position of the point is
				determined as a percent of the window width
				xPosition.  If xPercent is False, then
				xPosition is a number of pixels from the
				left edge of the window.  Y is computed the
				same way using yPercent and yPosition.

	    . screen		Similar to "application", but using the
				display screen instead of the Xgopher window.

	    . widget		Similar to "application", but using another
				window or widget as the reference window.
				This is of limited utility since you cannot
				specify the reference widget from the 
				resources file.  It is however, used for
				the default position of a text save
				popup - it is relative to that text window.

	    . none		bypasses all positioning code, allowing only
				the window manager to have any placement
				control.
	
	xPosition		(class: Position)
				an integer interpreted as a number of
				pixels or as a percentage of some width
				(see positionFrom) depending on the
				value of xPercent.

	xPercent		(class: Percent)
				True or False - determines the way xPosition
				is interpreted.

	yPosition		(class: Position)
				Similar to xPosition, but for height.

	yPercent		(class: Percent)
				Similar to xPercent, but for height.

	horizontalJustification	(class: Justification)
				One of {left, center, or right}.  This is the
				horizontal alignment of the popup against the
				point determined by the other resources.

	verticalJustification	(class: Justification)
				One of {top, center, or bottom}.  This is the
				vertical alignment of the popup against the
				point determined by the other resources.


The resource name for each popup is provided below along with its
default position.  The class name for all popup positioning is "Popup".
The set of resources that determines the default position is shown.
Each can be modified to individual taste through the resource file.

The defaults are not chosen arbitrarily.  The idea is that panels
which normally require more than one item of information before proceeding
with Xgopher are popup up in a specific nearby location.
The CSO name server panel can operate asynchronously with Xgopher
is shown off to a side.  The index search, error, and information
popups appear near the pointer for quick access.  The file save
box is shown along with the associated text popup (since there may
be more than one text display visible).

Of course, these are the choices of the author; you may change them
to suit your taste.

To set the default value for any of these options for ALL popups,
use the class name "Popup" instead of the specific instance name.
For example, the following causes every popup to be shown centered
on the screen:

	Xgopher.Popup.positionFrom:	screen
	Xgopher.Popup.xPosition:	50
	Xgopher.Popup.xPercent:		True
	Xgopher.Popup.yPosition:	50
	Xgopher.Popup.yPercent:		True
	Xgopher.Popup.horizontalJustification:	Center
	Xgopher.Popup.verticalJustification:	Center


Notes:
    1. After any popup position is calculated by Xgopher, it is adjusted
       to keep the entire popup fully visible on the screen (the exception
       2s noted in note 3 below).  Popups with positionFrom=none
       will have no positioning done, so you are at the whim of the
       window manager for window placement.
    
    2. In the positioning resources, the popup will still be moved
       down and right by the amount of the window manager decorations.
       Since Xgopher ultimately specifies only the upper left corner, and
       simulates the center, right, and bottom justification, this 
       affects center and right/bottom positions, but not top and left
       alignment.  This is especially important to remember if you try
       to position a popup at, for example the bottom edge of the screen.
       In this case, part of the contents may be off the screen.  Xgopher
       has no control of this.

    3. The "top level" shells (Xgopher main panel, text popups, and the
       CSO name server popup panel) are usually placed by the window
       manager at a level above the Xgopher application ( even if you
       specify otherwise using these resources).  You may use the
       window manager resources or individual geometry resource to
       place these windows.  For example, to place the CSO name server
       panel in the upper right of the screen, you can use:

           Xgopher.csoPopup.positionFrom:  none
           Xgopher.csoShell.geometry:      -0+0

       The first disables any attempt by Xgopher to place this panel,
       leaving it entirely to the window manager.  The second line
       is a standard X geometry specification.

    4. There is a seeming naming inconsistency in the above note!  The
       "xxxPopup" names is used exclusively for the popup positioning
       resources.  The "xxxShell" names are used to emphasize that this
       is the actual shell widget itself and any shell resources apply.

       In fact, there is not a 1-1 correspondence between the "xxxPopup"
       and "xxxShell", but a many to one.  Some shells are used for more
       than one purpose (the displayed-text file save and the file copy
       for example).  The "xxxPopup" names are truly synthetic, not
       necessarily corresponding to a single Xgopher entity.


-------------------------------------------------------------------------
Default popup positions
-------------------------------------------------------------------------

The 7 values shown for each resource below are (in order):

	positionFrom, xPosition, yPosition, horizontalJustification,
		      verticalJustification, xPercent, yPercent

For each popup, the name is given, followed by the exact values
used as a default position, followed by a concise description of
what the values mean.
		

versionPopup		APPLICATION, 50, 0, CENTER, TOP, True, True
	(center, top) is at (50%, 0%) relative to the application window

singleItemPopup		APPLICATION, 0, 10, LEFT, TOP, True, True
	(left, top) is at (0%, 10%)  relative to the application window

optionsPopup		APPLICATION, 0, 10, LEFT, TOP, True, True
	(left, top) is at (0%, 10%)  relative to the application window

copyPopup		APPLICATION, 0, 10, LEFT, TOP, True, True
	(left, top) is at (0%, 10%) relative to the application window

savePopup		WIDGET, 0, 10, LEFT, TOP, True, True
	(left, top) is at (0%, 10%) relative to the associated text window
	        (Note that there is no way to specify any other window,
	        except the main application window from the resources file.)

cdPopup			WIDGET, 0, 33, LEFT, TOP, True, True
	(left, top) is at (0%, 33%) relative to the save/copy window
	        (Note that there is no way to specify any other window,
	        except the save/copy window from the resources file.)

dupFilePopup		WIDGET, 50, 90, CENTER, TOP, True, True
	(center, top) is at (50%, 90%) relative to the save/copy window
	        (Note that there is no way to specify any other window,
	        except the save/copy window from the resources file.)

csoPopup		APPLICATION, 66, 0, LEFT, TOP, True, True
	(left, top) is at (66%, 0%)  relative to the application window

statusPopup		APPLICATION, 50, 50, CENTER, CENTER, True, True
	(center, center) is at (50%, 50%) relative to the application window

indexPopup		APPLICATION, 50, 0, CENTER, TOP, True, True
	(center, top) is at (50%, 0%) relative to the application window

infoPopup		POINTER, 0, 0, LEFT, BOTTOM, True, True
	(left, bottom) is near the pointer

errorPopup		POINTER, 0, 0, LEFT, BOTTOM, True, True
	(left, bottom) is near the pointer

fatalErrorPopup		SCREEN, 50, 50, CENTER, CENTER, True, True
	Centered on the screen 

textPopup		NONE, 0, 0, LEFT, TOP, False, False
	no default position.  (The geometry resource and/or the
	window manager will place the text popup shell.)

	Note that ALL text popups will be subject to any specification
	that you provide.  There is no way to specify different
	positioning information for each text popup.
