Pager(1.6)

NAME
Pager - the Afterstep desktop Pager module

SYNOPSIS
Pager is spawned by afterstep, so no command line invocation will work.

From within the autoexec file or as a menu option, Pager is spawned as follows:

	Module	"I"	Pager begining_desktop# ending_desktop#
	Wait		"I"	Pager

Wait can be used as shown above for transparent Eterms. This will insure that the Pager has set the root background before it starts any furthur apps (like Eterms).

or from within an afterstep menu file by 'Pager':

% cat "~/GNUstep/Library/AfterStep/start/Modules/Pager"
	Module "Pager" Pager begining_desktop# ending_desktop#
	MiniPixmap "mini-as.xpm"
To stop the Pager module, a menu item can be used:

% cat "~/GNUstep/Library/AfterStep/start/Modules/Pager_Stop"
	KillModuleByName "Stop Pager" Pager
	MiniPixmap "mini-as.xpm"

DESCRIPTION
The Pager module shows a miniature view of the Afterstep desktops which are specified in the command line. This is a useful reminder of where your active windows are. Windows in the pager are shown in the same color as their afterstep decorations. The Pager can be used to change your viewport into the current desktop, to change desktops, or to move windows around. Pressing mouse button 1 or 2 in the Pager will cause your viewport to change to the selected page of the selected desk. If you click with button 1 in the desk-label area, you will switch desks but not pages within the desk. Clicking and dragging with mouse button 2 on a miniature window in the Pager will cause that window to be move to the location where you release the mouse button, but your viewport will not change. If you drag the window out of the pager and onto your desktop, a full size image of the window will appear for you to place. There is no way to pick up a full size image of the window and move it into the Pager, however. Since some mice do not have button 2, provisions have been made to drag windows in the Pager by pressing modifier-1 (usually Alt) and dragging with button 3. When iconified, the pager will work as a fully functional current page only pager. Windows and viewports can be moved within the icon of the pager. Users will want to make sure that they have no lines similar to

	Style	"Pager"	Icon myIcon.[xpm|jpg|png]

in their feel files.

INITIALIZATION
During initialization, Pager will search for a configuration file which describes the images, locations and actions to take. The configuration file is /usr/local/share/afterstep/pager; but can be overriden by ~/GNUstep/Library/AfterStep/pager . If the Pager executable is linked to another name, ie ln -s Pager OtherPager, then another module called OtherPager can be started, with a completely different set of configurations than Pager, simply by adding *OtherPager options following the same *Pager configuration options below to the pager file. This way multiple Pager programs can be used.

KEYBOARD FOCUS CONTROL
You can direct the keyboard focus to any window on the current desktop by clicking with button 2 on its image in the pager. The window does not need to be visible, but it does need to be on the current page.

INVOCATION
Pager can be invoked from the autoexec file or from a menu item as shown in the Synopsis section above. AfterStep will search through the directories specified in the ModulePath configuration in the base.#bpp (where # is your colordepth) to attempt to locate Pager.

CONFIGURATION FILES
Pager reads the base.#bpp file and pager file when it starts up and looks for its configuration options.

CONFIGURATION OPTIONS - base.#bpp
The following two configuration options are in the base.#bpp file:

*DeskTopSize ColumnsxRows
    Defines the number of view Columns by the number of view Rows of the desk(s) in proportional units, i.e. 2x1 would show 2 views of one desk, one beside another.

*DeskTopScale number
    If the geometry is not specified, then a desktop reduction factor is used to calculate the pager's size. Things in the pager window are shown at 1/number of the actual size.

CONFIGURATION OPTIONS - pager
The following configuration options are in the pager file:

Balloons
    Turns on the balloon feature. A "balloon" is displayed showing the name of the window the pointer is resting on in the Pager. Currently only the window's icon name is shown. Note that balloons are not shown for the iconified pager.

BalloonFore color
    Specifies the color for text in the balloon window. If omitted it defaults to the foreground color for the window being described.

BalloonBack color
    Specifies the background color for the balloon window. If omitted it defaults to the background color for the window being described.

BalloonFont font-name
    Specifies a font to use for the balloon text. Defaults to fixed.

BalloonBorderWidth number
    Sets the width of the balloon window's border. Defaults to 1.

BalloonBorderColor color
    Sets the color of the balloon window's border. Defaults to black.

BalloonYOffset number
    The balloon window is positioned to be horizontally centered against the application window it is describing. The vertical position may be set as an offset. Negative offsets of -N are placed N pixels above the pager window, positive offsets of +N are placed N pixels below. Defaults to +2.

BalloonDelay number
    Specifies the period in milliseconds to delay the appearance of the balloon.

HiForeColor color
    Specifies the color for the text in the focused (hilighted) window. If omitted, the default is black.

HiBackColor color
    Specifies the background color for the focused (hilighted) window. If omitted, the default is white.

MaxBackgroundColors number
    If specified, the number of colors used for backgounds is limited to number. This feature is implemented in the library for the image format used [XPM, JPEG, PNG] and might not always yield the results one would expected.

StickyPagerIcon
    Allows the icons of iconified windows to follow you when switching desks. Without this option, the icons would stick to the desk the window was iconified in.

*PagerFore color
    Specifies the color to use to write the desktop labels, and to draw the page-grid lines.

*PagerBack color
    Specifies the background color for the window and label backgrounds.

*PagerHilightBorders
    Tells the pager to hilight the border of focused window as well as its label.

*PagerHilight color
    Specifies the hilight color of the active page (view) and desk label.

*PagerDecoration param1[,param2[,...]]
    Allows you to decorate your pager to your liking. The following parameters can be specified :

    DeskBorderWidth width
        Specifies the width of the border to be drawn around each desk

    NoPageSeparator
        Turns OFF grid separating pages

    GridColor color
        Specifies a different color than the fore color to draw grid lines. If this option is unused, then the same color specified with *PagerFore will be used for the grids.

    NoSelection
        Turns OFF highliting of the current page

*PagerFont font-name
    Specifies a font to use to label the desktops. If font-name is "none" then no desktop labels will be displayed.

*PagerSmallFont font-name
    Specifies a font to use to label the window names in the pager. If font-name is "none" then the window labels will be omitted. Window labels seem to be fairly useless for desktop scales of 32 or greater.

*PagerGeometry geometry
    Completely or partially specifies the pager windows location and geometry, in standard X11 notation. In order to maintain an undistorted aspect ratio, you might want to leave out either the width or height dimension of the geometry specification.

*PagerImage desk image
    Sets the image to be used for the desk desk representation in the Pager. Where image can be of either JPEG, XPM, or PNG format, and desk is a number coresponding to the desktop number: 0,1,2,3,N.... Use it if you want to specify a different image for Pager background other than the default; which is the upper left hand portion of the *PagerDesktopImage.

    *PagerImage desk ~/path/my.[xpm|jpg|png]

    To use the default behavior:
    *PagerImage desk ~/GNUstep/Library/AfterStep/non-configurable/desk_background

*PagerDesktopImage desk image
    Sets the image to be used for the Root Window background of desk desk. Where image must be either JPEG or XPM format, and desk is a number coresponding to the desktop number: 0,1,2,3,N.... The image will be also scaled down and used as background for the Desktop representation in the Pager window if *PagerImage is not specified. If image is not XPM or JPEG format, external image loader application will be used to display it on Root. That application is specified at compilation time.

    *PagerDesktopImage desk ~/GNUstep/Library/AfterStep/non-configurable/desk_background
    for each desk you use.

    To use the same image for all desks and improve loading time:

    *PagerDesktopImage 0 ~/GNUstep/Library/AfterStep/non-configurable/0_background
    see also *PagerFastStartup below.

*PagerXImageLoaderArgs [desk] arg1 arg2 ... argN
    This option will let you overide external image loader args specified at compilation time for desk desk, or all desks if desk is ommited. Warning: When desk is used to specify desk - it will also disable internal XPM and JPEG support for this desk!

    *PagerXImageLoaderArgs desk -fillscreen -onroot -quiet

    The default XImageLoader is xli, check that program's man page for other options to use aside from those in the above example.

*PagerFastBackground desk yes/no [tile_hsize [tile_vsize]]
    This option has only effect, when you are using non-XPM and non-JPEG files as the root background. When set to 'yes' it will store image, displayed by external viewer application, in memory, using it later on when you switch between desks. That can grately increase speed, but will also result in more memory used (apprx. 1Mb per desktop ), therefore it is not recommended on systems with a small amount of RAM. If you are using a small image tiled on your root, you will want to specify image sizes in tile_hsize and tile_vsize to reduce memory used. If you ommit any of these, the screen dimension will be used. Also, to reduce memory used, you can set this to 'yes' only for most used desks. By default *PagerFastBackground is set to No and tile size set to the screen dimentions.

*PagerAlign LabelPosition
    Sets the alignment of the labels for the desktops. Use 0 for centered, >0 for left, <0 for right alignment. If <>0 the absolute value of LabelPosition will be the distance between label text and window border.

*PagerLabel desk label
    Assigns the text label to desk desk in the pager window. Useful for assigning symbolic names to desktops, ie

*PagerRedrawBg number
    If 0, will not update background change, use this with xearth or xfishtank. Default is 1, i.e. update background.

*PagerRows rows
    Tells afterstep how many rows of desks to use when laying out the pager window. Set to 1 for horizontal Pager and define PagerColumns.

*PagerColumns columns
    Tells afterstep how many columns of desks to use when laying out the pager window. Set to 1 for vertical Pager and define PagerRows.

*PagerIconGeometry geometry
    Specifies a size (optional) and location (optional) for the pager's icon window. Since there is no easy way for Pager to determine the height of the icon's label, you will have to make an allowance for the icon label height when using negative y-coordinates in the icon location specification (used to specify a location relative to the bottom instead of the top of the screen).

*PagerStartIconic
    Causes the pager to start iconified.

*PagerFastStartup
    During startup causes Pager to inform AfterStep, that it is already started, after loading background for the first desk. The will also set global atom for background pixmap, so Eterm can use it to emulate transparency. This background will be set to the background of first desk of starting Pager. In case you have several Pagers starting up (for different desks), it's wise to start Pager for desk 0, after all other Pagers, so to get correct value for this background pixmap.

FILES

/usr/local/share/afterstep/pager
    The global configuration file for system wide defaults of all users.

$HOME/GNUstep/Library/AfterStep/pager
    This file should be copied from the /usr/local/share/afterstep/pager and edited to suit the user's specific requirements. This file, if it exists, will override the system wide default file.

/usr/local/share/afterstep/base.[8|15|16|24|32]bpp
    Contains the DeskTopSize & DeskTopScale global settings for the Pager.

$HOME/GNUstep/Library/AfterStep/base.[8|15|16|24|32]bpp
    This file should be copied from the /usr/local/share/afterstep/base.[8|15|16|24|32]bpp and edited to suit the user's specific requirements for the DeskTopSize & DeskTopScale settings of the Pager.

EXAMPLES
The pager file shipped contains many examples, refer to the FILES section above for its configuration options. To have a Pager oriented vertical on the desktop with 2 desks and 1 view for each desk:

    ...the autoexec file would contain -
	Module	"I"	Pager 0 1
	Wait		"I"	Pager

    ...the base.#bpp file would contain -
	DeskTopSize 1x1

    ...the pager file would contain (this modification) -
	*PagerRows	2
	*PagerColumns	1

To have the Pager swallowed in the Wharf on one button, with only 1 desk and 4 views:

    ...the wharf file would contain -
    *Wharf Pager - SwallowModule "Pager" Pager 0 0

    ...the base.#bpp file would contain -
	DeskTopSize 2x2

    ...the pager file would contain (this modification) -
	*PagerRows	1
	*PagerColumns	1

An example of the Pager swallowed in the Wharf as a Folder is an example within the wharf file shipped.

AUTHORS
Robert Nation
Alfredo Kojima
Guylhem Aznar
Ric Lister
Sasha Vasko
David Mihm <davemann@ionet.net> [Man page]

SEE ALSO
afterstep(1), Wharf(1), xli(1), X(1)