Pager(1.8)

NAME
Pager - the Afterstep desktop Pager module

SYNOPSIS
Pager [-f config_file] [-v | --version] [-h | --help] first_desktop last_desktop

Although Pager can be run from the command line, it is normally spawned by afterstep in the autoexec file, in the following manner:

	Module	"I"	Pager beginning_desktop# ending_desktop#
	Wait	"I"	Pager

In case you use Pager to switch your root backgrounds Wait can be used as shown above. This will insure that the Pager has set the root background before you start any furthur apps (like transparent aterms and Eterms).

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

% cat "~/GNUstep/Library/AfterStep/start/Modules/Pager"
	Module "Pager" Pager first_desktop last_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 accordingly to MyStyle definitions "*PagerUWindowStyle" - for unfocused windows, "*PagerFWindowStyle" - for focused windows and "*PagerSWindowStyle" - for sticky windows. If you never defined those MyStyles, Pager will default to same styles as used for actual windows. 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 Starting with version 1.7.122 Pager no longer loads background images into the memory. Module asetroot should be used to accomplish that task. But Pager will still be able to switch backgrounds as you switch between desks, after you've run asetroot to load images. Use *PagerDontDrawBg option in pager config file to TURN background switching OFF. See asetroot man page for more information.

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

in their feel files.

OPTIONS

-f config_file
    Use config_file instead of the default configuration file.

-h | --help
    Print a usage message and exit successfully.

-v | --version
    Print version information and exit successfully.

INITIALIZATION
During initialization, Pager will search for a configuration file which describes the images, locations and actions to take. This file will be the one specified by the -f option (if given). Else, the ~/GNUstep/Library/AfterStep/pager file will be used if it exists. Else, /usr/local/share/afterstep/pager will be used. 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.

MyStyle DEFINITIONS
Starting with version 1.7.60 Pager supports definition of most of it's visual parameters in look file as MyStyles. Styles can also be defined in pager config file, but main contents of the look file will override them. Include them in your pager config to make sure that you get nice looking Pager even if styles are not defined in look file. The following standard MyStyle names are used :

*PagerUWindowStyle
    (defaults to "unfocused_window_style") - unfocused window representation's style. Background pixmap and gradient can be used here.

*PagerFWindowStyle
    (defaults to "focused_window_style") - focused window representation's style. Background pixmap and gradient can be used here.

*PagerSWindowStyle
    (defaults to "sticky_window_style") - sticky window representation's style. Background pixmap and gradient can be used here.

*PagerActiveDesk
    active (selected) desk's label style. This style - defines only look of the desk's LABEL - to define how your actual desk window will look like - you should use *PagerStyle option - see below. Background pixmap, gradient and transparency can be used here.

*PagerInActiveDesk
    Same as above, only for inactive desk's label. Background pixmap, gradient and transparency can be used here.

*PagerDesknumber
    Defines Style of the desk representation in Pager's window. This was added to allow for easier theme support. This style will be overriden by *PagerStyle option in pager config file.

*PagerBalloon
    Mini-window balloon style. This definitions are dependant on Pager's name, so if you start Pager as WPager - you should change all the names, like so : "*PagerInActiveDesk" -> "*WPagerInActiveDesk" Different styles can be defined also for Desk's representations. See *PagerStyle option below. NOTE: In order to make your look themeble all MyStyles must be defined in main look file !

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. The balloon background and text are configured with the MyStyle "*PagerBalloon". See afterstep(1x) for more information on MyStyles.

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.

*PagerStickyIcon
    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.

*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

    DeskBorderColor color
        Defines color of the Desk's border. Use it to override default which is the style's foreground color

    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

    SelectionColor color
        Turns ON highliting of the current page, and specifies color of hilighting

    NoDeskLabel
        Turns OFF desk's labeling

    LabelBelowDesk
        That will place label below the desk instead of above the desk. Note: using gradients with this option will produce funky effect.

    HideInactiveLabel
        When this option is specified - Pager will use shaped extensions to make label of all inactive desks transparent.

*PagerSmallFont font-name
    Specifies a font to use to label the window names in the pager. It overrides font specified in Focused/Unfocused/Sticky window style in look file. It also displays text on background color - which can be usefull if BackPixmap is specified in window style. 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.

*PagerStyle desk style
    Sets the style to be used for the desk desk representation in the Pager. Where style can be the name of any style definition in the look file, and desk is a number coresponding to the desktop number: 0,1,2,3,N.... Use it if you want to specify a different style for Pager background other than the default; which is the scaled down *PagerDesktopImage.

    *PagerStyle desk DeskStyle1

*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

*PagerDontDrawBg
    If specified, will not display background image, use this with xearth or xfishtank, or with asetroot.

*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.

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 <dmihm@swbell.net> [Man page]

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