p-----------------------------------------q | Pogo 2.2 README Table Of Contents: | b-----------------------------------------d
I. Introduction to Pogo 2.2
II. Overview of Pogo
III. Mouse Controls
IV. Keyboard Controls
V. Command-Line Switches
VI. Configuration File
VII. The Wonders Of Pogo-Remote
VIII. Errata
IX. Technical Notes
X. Legal Crap
XI. Credits
p-----------------q
| I. Introduction |
b-----------------d
Hey! Thanks for not only downloading Pogo, but taking the time to read the README. :) You'll find pretty much everything you need to know right here in this file, and if not, just check Pogo's development webpage. Currently, Pogo's development page is located at http://www.ibiblio.org/propaganda/pogo, but that may change in the near future.
I had alot of fun working on Pogo 2.2 (so far!) and I hope you have fun, too, finding new uses for it. I tried to make Pogo as flexible as possible in hopes that some of you would drop me an email someday out of the blue with some cool trick you've made your Pogo do. :)
Speaking of email, if you have any questions or bug reports for me to look at, feel free to send me an email. You'll find my contact information at the bottom of this document.
Hope to hear from you, and Happy Pogo'ing!
Cheers,
Bowie J. Poag
p--------------q
| II. Overview |
b--------------d
So...What the heck is Pogo 2.2?
"Pogo 2.2" consists of two main parts.. "Pogo", and a thing called "pogo-remote".
Pogo is a programmable application launcher. You can assign pretty much any action you want to any button. Whether its a program, a script, even a command that changes the way your Pogo looks and acts, you can do it from a launcher. Basically, all Pogo is doing behind the scenes is slapping an ampersand at the end of whatever command you specify in Pogo's config file, and launching it. It doesn't really care what it is. Simply put, if you can run it from a shell prompt, you can launch it from Pogo!
The second part of this package, "pogo-remote" is a program you can use to remotely control the appearance and behavior of your Pogo. You can use pogo-remote either as a stand-alone command, or incorporated within shell scripts. By using pogo-remote, you can make your Pogo do things like move your launchers around, launch programs, change the color of the launchers themselves, make them flash, you name it --- You can even tell Pogo to pick up and read an entirely new config file. Basically, anything you can do to Pogo by yourself, manually, you can also do remotely via pogo-remote. For example, you can write a shell script that checks your email, and flashes a particular launcher's icon X number of times depending upon how many emails you have waiting to be picked up. Actually, I included a script to do just that. :) Pogo-remote lets you (the user) do absolutely tons of cool stuff. You can take your Pogo and turn it into an MP3 player, a calculator, a jukebox, a diagnostic display, a clock, or even a complete desktop replacement. It's all a matter of fooling around with Pogo's configuration file. Be sure to have a look at the "Practical Uses Of Pogo" section of this README for more details! :)
Pogo was built from the ground up to be as fast, intuitive, and simple to use as possible. It packs alot of punch for such a small program, and the possibilities are friggin' endless as to what you can do with it. You can take your Pogo and turn it into an MP3 player, a calculator, a jukebox, a diagnostic display, a clock, or even a complete desktop replacement! It's all a matter of fooling around with Pogo's configuration file, and letting Pogo do the work for you :)
That being said, let's start off with a brief overview of how to use Pogo.
p----------------------q
| III. Mouse controls. |
b----------------------d
LEFT MOUSEBUTTON: By highlighting and clicking on a launcher (an icon)
with the left mousebutton will run the program or shell
script associated w/ that launcher. Pogo will launch
that particular program (or shell script) in the
background, and return control to you.
MIDDLE MOUSEBUTTON: By highlighting a launcher and holding down the middle
mousebutton, you to change and set a launcher's
colorization! With the button held down, move your
mouse left and right to change the color, and move it
up and down to control the brightness. Once you're
satisfied with the change, simply release the middle
mousebutton, and you're all set.
RIGHT MOUSEBUTTON: When highlighting a launcher, a single click of the
right mousebutton will strip off any colorization
you've given a particular launcher. Additionally,
to move the launcher to a different space in your
Pogo, simply highlight it, hold down the right
mousebutton, and drag it wherever you want. This is
just one way you can change the order of the launchers
in your Pogo.
MOUSEWHEEL UP/DOWN: By using the mousewheel, you can shift all of the
launchers in your Pogo. This is another way you can
change the order in which your lauchers are displayed.
SIDE MOUSEBUTTONS: Buttons 5 & 6 on your mouse (if you have them) will
allow you to switch Pogo's orientation between
Horizontal and Vertical mode, and allow you to save
out your current configuration, respectively.
p------------------------------------q
| IV. Keyboard Controls: (optional) |
b------------------------------------d
Optionally, Pogo can be controlled entirely via the keyboard, with no mouse movement whatsoever.
ENTER: Highlighting any launcher and hitting the Enter key will
make Pogo launch the program or shell-script associated
with that launcher.
ARROW KEYS: Using the arrow keys will allow you to move and rotate
the order of the launchers in your Pogo.
TAB: Hitting the Tab key will allow you to switch back and
forth between Horizontal and Vertical
window orientations.
SPACE: Saves out the current configuration to disk.
BACKSPACE: Removes the colorization of the launcher you're
currently pointing to.
C: The colorization mode. Use the arrow keys to set the
brightness and color of the launcher, and hit C again
to save your changes.
ESC: Exit Pogo!
p---------------------------q
| V. Command-line Switches: |
b---------------------------d
-s <value> Use this to specify the size of the icons. Default is 64. -v <value> Verbose mode. Default is OFF. -q <value> Display splash screen...Default is 0 (off).
-c <filename> Specify a config file other than the default (pogo.config)
p--------------------------------q
| VI. Pogo's Configuration File: |
b--------------------------------d
The top line of the config file represents the orientation and X/Y coordinates of where the window should appear. The first number represents the orientation. Set it to 0 for Horizontal, 1 for Vertical. The second two numbers are the X and Y coordinates. All the lines below the first one are for the individual launchers. They follow the basic template of:
(Unique ID) (Icon Filename) (Red) (Green) (Blue) (Program/Script To Launch)
For example:
11 pogo-mozilla.jpg 255 150 150 mozilla http://www.redhat.com
This will tell Pogo to create a new button (using pogo-mozilla.jpg), tinted red, and will bring up Red Hat's webpage. Pogo will refer to this launcher internally as launcher #11. By the way, make sure each of the entires have their own unique identifier. :) Pogo supports up to 127 launchers, but you'll probably never need more than 15-20 at the most. Just like nobody will ever need more than 640K, right? :)
p---------------------------------q
| VII. The Wonders Of Pogo-Remote |
b---------------------------------d
As I discussed earlier in this document, pogo-remote is an external program for making Pogo do stuff like making the launcher icons flash, moving them around, changing window orientation, etc... The idea is, you can write a shell script that goes off and does something, then uses pogo-remote to signal your Pogo with the results. You can use pogo-remote as a stand-alone program, or use it within a shell script. Here's a simple example of how to use pogo-remote..... With Pogo running, issue this command:
./pogo-remote -d strobeThisIcon -a 3 -b 10
This will cause Pogo to flah the #3 icon ten times. This might be handy, for example, in a script that checks for people trying to hack your box. If the script detects something fishy is going on, it can kick off that command and alert you visually.
Lets try something a bit more advanced..Suppose I wanted Pogo to flash my email icon, depending upon how many emails I have waiting to be read.. Here's what such a command would look like (and it works, too!)
---%< cut here %<----
while true; do sleep 10; ./pogo-remote -d strobeThisIcon -a 17 -b `( sleep 5 ; echo "user bpoag" ; sleep 1 ; echo "pass ***********" ; sleep 1 ; echo "stat" ; sleep 1 ) | telnet mail.comcast.net 110 | tail -n1 | awk '{print $2}'`; done
--->% cut here >%---
Understand how that command works? Every 10 seconds or so, that single command will check my email for new messages, and then flash my email launcher's icon (#17) a total of (x) number of times, where "x" is the number of emails I have waiting. Kinda cool, eh? :)
By making shell scripts, and incorporating pogo-remote into them, you can use Pogo as a status indicator for different things happening on your system.. For example, have it so that a warning icon flashes whenever the size of your system's error log changes.. Or, even more fun, have a script that moves your Mozilla launcher to the front of the line when a new version is available on the website. Way cool! Anything you can imagine, you can toss pogo-remote in there to provide visual feedback. You can even have multiple scripts running, making your Pogo light up like crazy all day! It's a riot! To see what pogo-remote looks like in action, try running the "pogo-test" script included in this package.
When pogo-remote runs, it generates a thing called a "directive". These "directives" are then seen by Pogo, and Pogo performs them. The directive is followed by a few values you provide, such as the launcher you want Pogo to manipulate, the number of times you want Pogo to do it, etc. These values are (internally, at least) referred to as the "Primary Argument", the "Secondary Argument", and the "Directive String".
Pogo 2.2 supports the following directives/arguments:
Directive Name Primary Argument Secondary Argument Directive String
colorizeThisIcon <icon number> N/A *<24-bit RGB code> decolorizeThisIcon <icon number> N/A N/A loadNewConfigFile N/A N/A <configfile> slideThisIconUp <icon number> <num of spaces> N/A slideThisIconDown <icon number> <num of spaces> N/A slideThisIconLeft <icon number> <num of spaces> N/A slideThisIconRight <icon number> <num of spaces> N/A punchThisIcon <icon number> N/A N/A slideAllIconsUp <num of spaces> N/A N/A slideAllIconsDown <num of spaces> N/A N/A slideAllIconsLeft <num of spaces> N/A N/A slideAllIconsRight <num of spaces> N/A N/A strobeThisIcon <unique ID> <strobe count> N/A switchToHorizontal N/A N/A N/A switchToVertical N/A N/A N/A startThisProgram <uniqueID> N/A N/A setIconSize <icon size> N/A N/A moveWindow <x coord> <y coord>
(* = 24-bit Hexidecimal RGB color code = 000000 thru ffffff)
You can use pogo-remote to issue any of the directives listed above. Here are a few usage examples:
pogo-remote -d punchThisIcon -a 4
pogo-remote -d strobeThisIcon -a 3 -b 10
pogo-remote -d loadNewConfigFile -c /home/foo/pogo-config.txt
The first command will "punch" launcher #4, or make it look like the button is being pressed in. It won't actually launch the program associated with that launcher, however.. Thats the purpose of the 'startThisProgram' directive. :)
The second command will make launcher #3 flash 10 times.
The third command will make Pogo load in a completely new config file, and redraw the window using the new launchers. This is useful if you want the user to be given a new list of launchers to choose from after picking one. Kinda cool, eh? You can effectively make a page-by-page menu system out of Pogo! You can have as many pages as you want. All you have to do is You can have one launcher use pogo-remote to bring up a new config file, and then have another launcher in THAT config file programmed to bring up ANOTHER one, and so on, and so on, until you come to a config file that has a launcher in it that brings up the original config file. Endless possibilities, baby. :)
p--------------q
| VIII. Errata |
b--------------d
There are NO bugs...that i'm aware of. :) I hate them with a passion, and tend to hold off on releasing my code until I can be reasonably certain my code is watertight and bulletproof. Even if it takes days to surface.
However, i'm pretty sure that despite my best efforts, bugs will arise. If you find one, contact me at:
Email: bpoag@comcast.net
...With a good explanation of the bug, and instructions on how to go about replicating it, if possible.
If you spot anything that looks out of the ordinary in terms of performance degradation, memory bloat, or full-blown crashes, please do let me know. Part of what makes open-source work is collaboration. Well, collaboration, and alot of beer. :) Lucky for you, I have plenty of beer, and I'll be happy to make the improvements if you guys let me know what to improve. :)
For the latest information on any bugfixes that may be released in the future, keep an eye on Pogo's development webpage at:
http://www.ibiblio.org/propaganda/pogo
p---------------------q
| IX. Technical Notes |
b---------------------d
Pogo-remote uses a combination token/signalling system to notify Pogo of new directives that need to be processed.
When pogo-remote runs, it first checks to see if Pogo is actually running. It does this by checking for the existence of a lockfile, /tmp/.pogo-lock.
When pogo-remote is told by the user to issue a directive, it picks a random number between 1 and 10. It drops this directive into /tmp, calling it (for example) .pogo-directive.7 ....Meanwhile, Pogo, when idle, looks around in /tmp for .pogo-directive.3, .pogo-directive.9, .pogo-directive.1, etc, until it finally hits on one that actually exists--- .pogo-directive.7. This process is remarkably fast, and utilizes practically nothing in terms of CPU time. The directives aren't even being written to disk -- Theyre cached by the system, and never have a chance to be sync'ed out, since they only exist for a fraction of a second.
p----------------r
| X. Legal crap |
b----------------d
In accordance with the GPL, the source for pogo is available upon request, for a nominal fee to cover media and shipping costs.*
- = The source code will be provided to you as a series of large, neon-lit marquee letters shipped individually in wooden packing crates. Currently, the world's supply of neon gas limits our ability to ship large quantities of source code. The current expected wait time is 32 years, plus or minus 6 months, depending upon the condition of labor relations in countries with substantial noble gas exports.
For more information, please inject crystal meth directly into your eyeballs, and light yourself on fire while listening to the following song:
xmms http://www.ibiblio.org/propaganda/pogo/easteregg.mp3
Just kidding. ;)
Seriously, though... As with all open-source software, there are bound to be yet-undiscovered bugs, vulnerabilites and what-not.. This program comes without warranty. However, Pogo is free, and is distributed under the GNU General Public License. Have fun!
Cheers,
Bowie J. Poag <bpoag@comcast.net>
Sep 1, 2003.
p-------------------q
| XI. Thanks Be To: |
b-------------------d
Jonathan Walther <krooger@debian.org>
- for wm_hinting patch, and a stern lecture on the merits of ICCCM.
Ashley Winters <awinters@users.sourceforge.net>
- for the RGB hex triplet extractor code.
Rus Hughes <russel.hughes@ntlworld.com>
- for helping test some of the visual feedback scripts.