| WMPINBOARD(1) | wmpinboard | WMPINBOARD(1) |
wmpinboard - a Window Maker dock app resembling a miniature pinboard
wmpinboard [options]
What wmpinboard is
wmpinboard is a Window Maker dock applet resembling
a miniature pinboard. It's intended to somewhat relieve heavily littered
desktops by allowing you to place reminders on a graphical on-screen
pinboard rather than producing a mess of real notes all around your keyboard
(thus being environmentally A Good Thing, too ;-) ). It supports
arbitrary 6x10 X fonts and has XLocale support, enabling you to enter
locale-dependent special characters if set up appropriately. Besides text,
you can add small monochrome sketches to your notes or simply encircle or
underline words as a means of emphasis, and alarms can be set to explicitly
remind you of things. Above all, wmpinboard is animated in redundant
ways to make it look even more attractive, and themeability provides for a
way of adapting its appearance to that of the rest of your desktop.
What wmpinboard ISN'T
Clearly, wmpinboard doesn't allow you to keep an unlimited number of notes holding arbitrary amounts of information, and that's not what it's meant to do. Just as real notes offer limited space, so do those simulated by wmpinboard. Besides, as a dock applet, it aims at being small and neat and yet useful in a way, and that's what it is, too, or considered to be by some people, anyway. If you need room for more comprehensive reminders, use another program, either additionally or exclusively. There's a variety of such out there, but their niche is different from that which wmpinboard claims.
wmpinboard's command-line options can be roughly divided
into four groups: configuration directives, run-time options, command-line
actions, and general options. Generally, wmpinboard supports
GNU-style long options (which may be abbreviated unambiguously) as well as
short ones for parameters used more commonly.
Configuration directives
This type of command-line options changes some aspect of
wmpinboard's configuration that is saved along with the data and thus
set in a more permanent way. Only one such parameter may be specified per
call, and there mustn't be another instance running.
Themes affect wmpinboard's appearance, in particular,
its pinboard, edit mode and alarm panel pixmaps, the latter's digits,
and possibly the location of the pinboard mode label area (via which
notes are created). For downloading themes, or if you're inclined to
create one yourself and need instructions, check out the program's home
page (see the section on "AUTHOR" or wmpinboard's
"`--help'" output
for the URL). The themes kit containing instructions and samples on how
to create theme files for wmpinboard that can be downloaded there
is also included with the source package of the program.
Run-time options
Command-line actions
Even though wmpinboard is by design an interactive application, there may be occasions when it comes in handy to be able to access/manipulate notes from the command line. That's why the program offers a set of command-line options allowing for basic operations of that kind. Still, it should be kept in mind that wmpinboard is primarily meant to be used interactively.
All of the options below will, if an interactive instance of wmpinboard is running in the background, cause that to save its data (and quit edit mode, if necessary), and if any changes are made by the respective option, the interactive instance will then be signalled to re-read the data file. Even though the implemented methods of inter-process communication should generally be sufficiently safe with respect to avoiding data file corruption, it's in theory possible to undermine the concept and cause damage that way--yet this won't happen unless you deliberately take pains to achieve the goal. Generally, everything should work fine as long as you don't try running multiple non-interactive instances of wmpinboard simultaneously.
Only one of the below actions can be specified per call to
wmpinboard.
Each line of output represents one note and is prefixed by the
internal number currently identifying the respective note and, if
an alarm is configured for the respective note, time and date (or
"daily").
In order to create a note with a certain color, the string can be prefixed by a color code specifying the group of colors which a random color is to be selected from (code letters are recognized case-insensitively):
%G - green
%Y - yellow/white
%R - reddish
%B - blue
Alternatively or additionally, you may specify a position code as
"%1" through "%9", defining an approximate position on
the board where the note is to be placed. Each of the nine figures
corresponds to a ninth of the board with its index assigned in accordance
with the layout of your keypad (i.e., "%1" meaning lower left,
"%9" upper right corner, and so forth).
Thus,
wmpinboard --add '%g%5test'
will place a green note saying "test" at the center of the board.
(Note: The "%" character can be escaped by a second
one if you want to add an un-prefixed string starting with a percent
character.)
General options
wmpinboard operates in basically two different modes,
namely, the pinboard view and edit mode. Furthermore, a
panel of buttons granting access to extended options can be popped up
in edit mode, which in turn allows you to display the alarm
panel to configure alarm settings for the current note.
Pinboard view
This is wmpinboard's normal mode of operation. A
potentially chaotic arrangement of tiny squares on a beige-colored oblong
(default theme) is meant to resemble notes pinned to a cork board. Possible
actions include:
By dragging a note with the left mouse button, you can move it
without changing its level with respect to other notes, i.e., without
raising it on top of all others.
Edit mode
This mode serves two purposes: on the one hand, it presents you
with a "full-size" view of a note's contents, on the other, you
can use the occasion to edit it. Due to its limited size, a note can hold up
to 10 characters on 6 lines (minus one on the last, i.e., 59 characters
altogether), plus a monochrome sketch of some kind. Possibly actions:
If you wish to paste something without word-wrapping (e.g., an URL containing a hyphen), paste it via [Ctrl]-[I] (think [i]nsert). This will paste the clipboard's raw contents at the current location of the cursor, shifting subsequent text if in insert mode (not trying to word-wrap that either).
Obvious limitations you should be aware of include:
Note: wmpinboard remembers where you left the text cursor
after you last edited a note and restores this position when you edit it the
next time.
Edit mode panel
This panel is intended to provide easy access to some options affecting edit mode or the current note in general. The panel looks like this (letters denoting the buttons for reference below):
+---+---+---+---+
⎪ a ⎪ c ⎪ e ⎪ g ⎪
+---+---+---+---+
⎪ b ⎪ d ⎪ f ⎪ h ⎪
+---+---+---+---+
The buttons bear tiny icons which are meant to suggest what they do, which isn't
all that easy on a 12x12 pixels area.
`:^)'
Here's a description of what each button does:
Alarm panel
This panel can be accessed from the edit mode panel described above. If the panel is visible while the edit mode panel is on, the alarm is set, otherwise, it's disabled.
The alarm panel consists of six distinct clickable areas. The digits to the left and right of the colon are the hour and minute which an alarm is to be set for. Below them, a date can be specified in month, day order. On the right, there are two toggle buttons (which can be either green (on) or red (off) and are mutually exclusive). The top one represents a daily alarm whereas the bottom one indicates/sets a date-specific one.
The hour, minute, month, and day of month fields can each be incremented or decremented by left- or right-clicking on them, respectively. Clicking on one of the toggle buttons configures the alarm as the respective type.
As the above description implies, there are two distinct kinds of alarms: daily and date-specific ones.
Alarms are generally executed only when in pinboard view and not moving any notes about. If you're keeping the program busy at the time an alarm would have to occur, it will be delayed until you're finished (i.e., let the program return to idle pinboard view). The same holds if an alarm occurs while another one is running.
If all prerequisites are given and an alarm becomes due, the corresponding note is displayed in edit view, and the display starts to flash on and off, along with the alarm command being executed (see the section on "OPTIONS"). To stop the blinking, click on the note. From then on, the note will be in edit mode.
For daily alarms, the entered date is ignored, and as the name suggests, they're run every day at the specified time. To deactivate such an alarm, you have to open the edit mode panel and click button (a) to make the alarm panel disappear, which turns the alarm off.
In contrast, date-specific alarms are executed only once, at the specified day and time. Since a year cannot be specified (explicitly), the alarm will be run on this date's next occurrence within a year from when the alarm was set. After that, the alarm will automatically be disabled. If a date-specific alarm becomes due while wmpinboard isn't running, it will be displayed as soon as the program is started the next time--which does not go for daily alarms.
The default mode for alarms is date-specific, and time and date are initialized with the next full hour when the alarm panel is opened the first time for a given note.
Internally, alarm times are stored in universal format, i.e., if you change the time zone after having set an alarm, the time will stay universally the same but will differ relative to the new time zone from what absolute time you originally set. This behavior is intended.
Finally, it should be mentioned that there are a few limitations with respect to command line actions (such as `--add', `--del', `-i', etc.). See the section on "RESTRICTIONS".
A: Of course the limited size imposes certain restrictions, but if you think about it, you'll agree that a real life pinboard reminds you of things by the mere existence of notes being pinned to it. In order to read what they say, you have to step close and, possibly, detach the note.
Quite similarly, wmpinboard reminds you of things by facing you with colored representations of notes on your screen. To find out what it was you intended them to remind you of, all you have to do is click on a note, which will then be displayed full size. Furthermore, the alarm feature introduced in a later version allows for even more explicit reminders and thus renders wmpinboard even more powerful in a way than any real-life cork board. `:-)'
By choosing from a variety of possible colors, you can assign particular colors to certain kinds of reminders, which may further enhance wmpinboard's usability. Moreover, you can place certain notes on certain areas of the board to emphasize their category, urgency, etc. It's up to you what to make of it.
Finally, by adding drawing capabilities, I've definitely
overcome the contents quantity barrier imposed by the maximum number of
59 characters, for as everyone knows, a picture is worth more than a
thousand words. *grin*
A: wmpinboard allows you to use an arbitrary 8bit X font, provided that its characters are of a fixed size of 6x10 (or, deprecated but possible, anything <= 7x10) pixels. The default font is "6x10" (more precisely, it's called "-misc-fixed-medium-r-normal--10-100-75-75-c-*-ISO8859-1"), an ISO8859-1 (Latin1) font which should be part of every XFree installation.
In order to make wmpinboard use another font, run it as
$ wmpinboard --font=FONT
where FONT is either a shortcut for a compiled-in font name (see the
section on "OPTIONS" for a list of those) or a valid, complete X
font descriptor. This is a configuration directive, meaning that no other
instance of wmpinboard may be running at the time. Note that this
only works if there are no more notes on the board. It's
intentionally been made impossible to change the font while there are
notes saved in wmpinboard's data file, since this might result in
garbage being displayed. Of course even a font specified via a shortcut
has to exist on your system in order to be usable.
If a configured custom font cannot be loaded or has invalid
dimensions, wmpinboard will try to revert. Note that this won't
affect the font name saved along with the data, though.
A:
$ wmpinboard --light
A: This presumably is a multitasking issue: depending
on the current system load and wmpinboard's/the X server's recent
CPU usage history, it may take a moment until the scheduling has been
adapted to the suddenly increased CPU load implied by displaying the
animation, and short as it is, it may already be finished until this has
happened, i.e., it's the X server lagging behind in updating the
program's display if wmpinboard's been idle for some time prior
to that. It may sound paradoxical, but the effect is the more likely to
show the lower the system's load is. I don't see a way to avoid this
effect--either this, or you turn off animations altogether.
A: Yes. After 60 idle seconds (that's the default; see the section on "OPTIONS") in edit mode (no mouse click and no keyboard input), edit mode is terminated automatically. If the note being edited happens to be blank, it will be discarded (or removed if an existing note is being edited).
This timeout can, however, be adjusted according to your
preferences or turned off using the
`-t' parameter. See the
section on "OPTIONS" for this.
A: Notes data is saved on each of these occasions:
Notes are saved to a file called .wmpinboarddata in your home directory (see the section on "FILES").
A: There's a compile-time limit of 20 notes. I think
more notes on this tiny a board really don't make any sense.
A: By default, wmpinboard actively claims the keyboard input focus (if it's in note edit mode) whenever the pointer is moved over the application's area. Since wmpinboard is a dock applet, i.e., a withdrawn rather than a "real" X window, it can't be assigned a focus in the same way as to the latter ones. However, running wmpinboard with the parameter `-c' will make it emulate some sort of click-based focusing. This means, it actively claims the keyboard focus only on these occasions:
Once keyboard-focused, wmpinboard will keep it until another window is explicitly focused (usually by clicking on its title bar or border). To focus wmpinboard again when it's lost focus, you'll have to click on its text area in edit mode. This click will only focus the application and not have the usual cursor-positioning effect.
This feature is to be considered experimental since I'm not sure of how much use it really is. A mouse-following focus is the recommended mode of operation.
A: No, this is not a bug. These "stains" are meant to resemble creases, caused by frequent handling of a particular note (wear & tear, you see?). In fact, they're added with a certain probability whenever you view a note by clicking on it (note that leafing through notes via [Shift]-[arrow keys] is not affected), when you clear its textual or drawn contents via the edit mode panel (very outwearing, that ;-) ), and when a note is moved. This feature can be disabled at compile time by running configure with `--disable-creases' as a parameter.
To prevent the question, no, worn-out notes cannot be ironed
to get rid of the creases. Sorry.
`:-p'
A: wmpinboard tries to autodetect whether Window Maker is running and sets itself up accordingly. If this doesn't work for you for some reason, you can explicitly make it run in either Withdrawn- or NormalState using the `-w' or `-n' flag, respectively. See the section on "OPTIONS".
Swallowing evidently works with AfterStep 1.6.10; I don't know about earlier versions. A Wharf config line you might try is this:
*Wharf wmpinboard nil MaxSwallow "wmpinboard" wmpinboard &
Besides, wmpinboard has been reported to work with Blackbox.
A: As of version 0.99.1, the recommended solution is to
upgrade whatever component of your system restricts you to a palette
mode.
A: No, this is certainly not a good idea. The run-time
behavior may be unpredictable, and your data file can get corrupted.
Therefore, any wmpinboard process that's to be run interactively
first checks whether another interactive instance is running, and if so,
refuses to run.
A: There's a Perl script doing the conversion
included with the distribution (the source one, anyway). If your package
didn't include that, feel free to mail to the author (see the section on
"AUTHOR" at the end of this documentation).
A: There's a variety of comprehensive programs for keeping notes out there, offering this functionality but being rather heavy-weight since they are linked against one GUI library or another (CoolNotes or KNotes come to mind). On the other hand, I couldn't find a WM-conforming reminder I could omnipresently stick to my desktop anywhere, so I wrote wmpinboard. I wanted it to be small, neat, easy to use, and yet useful in a way.
I hope that's about what the program is currently like. And I'd prefer to keep it like that rather than inflate it by linking against a GUI library--eventually, the note editing code would outweigh the rest of the application by a factor, and people would probably still create notes mostly shorter than 60 characters. If you restrict your memos to keywords and abbreviations, that's quite a lot.
I want wmpinboard to remain an applet in that it doesn't open up external windows and use (if just temporarily) additional desktop space. I explicitly wrote it to have something omnipresent at a fixed position on my desktop. I find it preferable to have the notes pop up in place rather than somewhere else on the screen.
Personally, I use other programs for larger notes too; wmpinboard has been designed for things smaller in size and greater in urgency, it's in no way meant to be a comprehensive knowledge base application of any kind.
Summing up, I think a dock applet should be small both
regarding its on-screen representation and the resources it uses. That's
why I don't intend to add any pop-up dialogs or similar things to
wmpinboard.
A: The solution is simple. Just don't use it.
A: Nope.
This piece of documentation doesn't cover any undocumented features.
If you stumble on any bugs, feel free to mail the author. The same goes if you encounter any problems running/using the program. Be sure to include any information you consider relevant, i.e., at a minimum, the version of wmpinboard you're using as well as your OS and X versions.
Also, further suggestions are always welcome. Please check the TODO file that's part of the distribution to see if what you're about to suggest isn't already on my "to do" list, or has been suggested earlier and was rejected for one reason or other.
wmpinboard is copyrighted (c) 1998-2000 by Marco Goetze, <gomar@mindless.com>. It is distributed under the terms of the GNU General Public License, revision 2 or any later revision thereof. Use at your own risk.
New releases of and themes for wmpinboard can be found at <http://www.tu-ilmenau.de/~gomar/stuff/wmpinboard/>, or that was true at least by the time this document was last updated.
| 0.99.3 | 3rd Berkeley Distribution |