NAME

screenpager - Screenwise pager for Xinerama


SYNOPSIS

screenpager [options] display on|off test

screenpager [options] move west|east|up|down

screenpager [options] new | delete

screenpager [options] output screen

screenpager [options] page up|down

screenpager [options] reset

screenpager [--duration=seconds] [--focus] [--osd=on|off] [--screen=screen|west|east|mouse] [--wrap] [args]

screenpager --help | --man | --version


DESCRIPTION

Screenpager is a screenwise pager for X workstations running Xinerama. It works like a desktop pager, but acts at the level of screens. Instead of paging the desktop as a whole, it can page each screen independently, or move pages from screen to screen.

Control is by command. Commands are issued either from the command line; from keystroke or mouse bindings; or from scripts. Screenpager itself is a script, written in Perl.


ARGUMENTS

delete

Deletes the current screen page. Sends a close request to all of its windows. Swaps in the page below, if any, otherwise the page above.

display on|off

Deprecated in favour of --osd option.

display on|off test

Tests whether the on-screen display is on or off. Exits with status 0 for true; 1 for false. Option --duration may be used with the off test, e.g.: screenpager display off --duration=13 test returns true if the display has been off for 13 seconds, or longer.

focus west|east

Sets a new focus screen. Deprecated in favour of the --focus option.

focus --screen=screen|mouse

Sets the default screen according to the --screen option. Also deprecated.

move west|east|up|down

Moves a page: either to an adjacent screen; or up or down in the stacking order.

new

Creates a new screen page. Places it above the current page in stacking order, and swaps it in.

output screen

Outputs the active screen: either as specified in an accompanying screen option (e.g. --screen mouse); or the default in effect from the latest focus command.

page up|down

Traverses up or down through the stack of screen pages. The current page is swapped out, and the next one is displayed in its place.

reset

Clears all state. Swapped out pages are forgotten; windows in the swap desktop are left there, and ignored. Normally issued at the start of each new X session, e.g. from your .xinitrc file.


OPTIONS

--display

Turns the on-screen display on. Deprecated in favour of osd=on.

--duration=seconds

Specifies a duration for --display=on or display off test.

--focus

Focuses on the active screen. The active screen is specified by an accompanying --screen option, except during a move, when it is always taken as the target screen. It is henceforth the default screen.

--help

Outputs a brief help message and exits.

--man

Outputs the full manual page and exits.

--osd=on|off

Turns the on-screen display on or off. Once on, its content is fixed. It does not update itself. You may update it explicitly by issuing another --osd=on.

Use --duration to specify the duration. Otherwise the default in Config_1.pm applies.

--screen=screen|west|east|mouse

Specifies the screen to act on. Screen numbers are zero based. You can also specify a compass direction from the current focus screen, or the keyword 'mouse' which designates the screen the mouse is in.

Applies only to the current invocation of screenpager. Use the focus argument to make it persistant.

--version

Prints the version of screenpager and exits.

--wrap

Wraps around screen or page limits during a focus, move, or page. So, for example, paging up at the top of the stack takes you straight to the bottom page.


FILES

Configuration is sought at /etc/xdg/screenpager/Config_1.pm. User preferences are sought at the following locations, in order of precedence: $ENV{'HOME'}/.config/screenpager/Pref_0.pm and /etc/xdg/screenpager/Pref_0.pm

Uses /tmp/.screenpager.lock. Creates temporary files and directories in /tmp/.screenpager/.


CAVEATS

Does not auto-detect a new X session. You must explicitly issue a screenpager reset, e.g. in your .xinitrc file.

On-screen display is often clipped at the bottom, sometimes self-correcting itself after an unpredictable delay. This is a bug in osd_cat. Try using config option $double_osd as a workaround.

On-screen display is sometimes wrong after moving a page west or east, or deleting a page. As a workaround, instead of using the --display option (as in screenpager --display move east) try issuing a separate screenpager display on afterwards, e.g. in the invoking script. Do this after a slight delay, if necessary.

Limitations of West/East Moves

Window postions are calculated to hold the east margin of the screen constant. This will not always work well when moving to a smaller screen. Some windows may fit only partially on the new screen, others not at all; depending on size and position of windows. (As a workaround, if screens vary in size, avoid putting narrow windows near the west edge of larger screens.)

Window postioning during west/east moves is optimized for Openbox. Using a different window manager with different behaviour may result in minor positioning errors. [Code ref.: sub _fetch_wininfo.]

Any window that fails to fit within the bounds of its new screen may be arbitrarily repositioned. [Code ref.: wmctrl.]


AUTHOR

Copyright 2004-2006, 2010-2011, Michael Allan. <mike@reluk.ca>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Screenpager Software"), to deal in the Screenpager Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Screenpager Software, and to permit persons to whom the Screenpager Software is furnished to do so, subject to the following conditions:

The preceding copyright notice and this permission notice shall be included in all copies or substantial portions of the Screenpager Software.

THE SCREENPAGER SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SCREENPAGER SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SCREENPAGER SOFTWARE.