NAME

screenpager - screenwise pager for Xinerama

SYNOPSIS

screenpager [options] display on|off [test]

screenpager [options] focus [west|east]

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

screenpager [options] new | delete

screenpager [options] output screen

screenpager [options] page up|down

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

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: Turns the on-screen display on or off. Once on, it is static, and will not update itself. You can update it explicitly by issuing another display on. Use --duration to automatically turn the display off; otherwise the default duration in Config_1.pm applies.
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 default screen to act on, by compass direction west or east from the previous default.
focus --screen=screen|mouse: Sets the default screen to act on, as specified by the --screen option.
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 display on, per the display on argument.
--duration=seconds: Specifies a duration for arguments display on or display off test.
--focus: Focuses on the screen specified by the accompanying focus (or move) argument. (During a move, this means the target screen, to which the page is moved.)
--help: Outputs a brief help message and exits.
--man: Outputs the full manual page and exits.
--screen=screen|mouse: Specifies the screen to act on. Accepts an explicit screen number (0, 1,...); or the keyword 'mouse', which means 'the screen the mouse cursor is in'. Applies only to the current invocation of screenpager, unless the focus argument is invoked.
--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/.

ROUGH EDGES

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 slow to refresh. New and old displays overlap, momentarily.

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

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.