 wmpinboard 0.8.3
------------------

 - What is wmpinboard?

     wmpinboard is a simple applet designed to be docked to Window Maker's
     dock or workspace clip.  It resembles a miniaturized pinboard which
     tiny, brightly colored notes can be "pinned" to.  Because the pinboard
     is limited to a size of less than 64x64 pixels, the notes of course
     can't be read in this view.  That's why each note can on demand be
     viewed "full size", allowing for 10x6 (-1) characters to be displayed.
     Additionally, as of v0.8, wmpinboard features drawing capabilities,
     allowing for simple, monochrome sketches to be added to notes (of course
     you can as well use this just to underline or otherwise emphasize part
     of a note's text).

 - Is a "pinboard" this small really of any use?

     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.

     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 tells more than a thousand
     words. *grin*

 - I've just run wmpinboard for the first time (or upgraded from an early
   version ;), now how does it work?

     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.
     All of this is described below...

     - PINBOARD VIEW
 
         This is wmpinboard's normal mode of operation.  A potentially
         chaotic arrangement of tiny squares on a beige-colored oblong
         is meant to resemble notes pinned to a pinboard.  Possible
         actions include:
 
           - ADD a note, by left-clicking on the board's "TO DO" label.
             This creates a new, blank, randomly colored note at a random
             position and puts wmpinboard in EDIT MODE (see below).
           - EDIT/VIEW a note, by left-clicking on a note.  This switches
             to EDIT MODE (described below).
           - MOVE a note, by dragging it using the right mouse button.
             This also raises the note in question on top of all others.
             Depending on its horizontal position, the note will be tilted
             automatically.  As a side-effect, a single brief right-click
             can be used to raise a note on top of overlapping ones without
             moving it.
 
     - 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 hand,
         you can use the occasion to edit it.  Due to its limited size, a
         note can hold up to 10 characters in 6 lines, plus a monochrome
         sketch of some kind.  Possibly actions:
 
           - ENTER text.  wmpinboard supports user-selectable fonts and
             dead keys, so you should be able to enter any characters
             that are usually accessible via your keyboard and have
             them displayed correctly.  Furthermore, the cursor can be
             moved around using the arrow keys.  Alternatively, it can be
             placed explicitly by left-clicking where you want it to be.
             Other special keys that are supported include:

               [PgUp]/[PgDn]   places the cursor on character 1/59, resp.
               [Home]/[End]    places the cursor at the start/textual end of
                               the current line
               [Del]           deletes the character currently under the text
                               cursor and shifts the remaining text on the
                               current line to the left; if the current line
                               is blank, removes it and shifts all lines
                               below upwards by one line
               [Backspace]     see [Del], but affects the character on the left
                               of the cursor
               [Ins]           toggles inserting/overwriting of existing text;
                               the current mode is indicated by a cursor
                               change (block cursor means insert mode)
               [Enter]         in insert mode, wraps the current line at the
                               cursor's position; in overwrite mode (underscore
                               cursor), merely moves the cursor to the start
                               of the next line
               [Esc]           quits EDIT MODE and returns to the PINBOARD VIEW
               [Shift]-[Left]/ cycle through all notes currently on the
                 [Right]       pinboard
               [Shift]-[Up]/   cycle through all notes that are *roughly* the
                 [Down]        same color as the current one (for this purpose,
                               colors have internally been divided into four
                               groups: green, white/yellow, reddish, blue)

           - LEAVE EDIT MODE.  This is achieved by left-clicking on the
             triangle in the lower right-hand side corner.  If the note is
             completely empty, it will be removed from the board.  In any
             case, this returns to the PINBOARD VIEW.
           - POP UP a PANEL with some further options to choose from.  This
             is done by right-clicking on the aforementioned triangle.  To
             learn what the panel is there for, see the corresponding section
             below.
           - DRAW a sketch.  This mode can be activated via the PANEL, and
             deactivated by either right-clicking somewhere on the note
             or opening the PANEL again.  While in drawing mode, the mouse
             pointer is pencil-shaped, and drawing can be done by keeping
             the left mouse button pressed and dragging the mouse, just as
             you'd expect it to be.  Sketch and text may overlap each other,
             but keyboard input is ignored while in drawing mode.
           - ERASE a sketch.  Just like DRAWing mode, this mode is entered
             via the panel, and can be quit just like the former.  In erase
             mode, the text is hidden, so you needn't guess whether a pixel
             belongs to an entered character or a drawn sketch.  Note that
             the erase cursor's point is slightly larger than the one used
             when drawing.

         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 |   The buttons bear tiny icons which are meant
             +---+---+---+---+   to suggest what they do, which isn't all
             | b | d | f | h |   that easy on a 12x12 pixels area. :^)
             +---+---+---+---+

         Here's a description of what each button does:

           (a)  This button allows one to cycle through all colors availabe
                for notes (about 20).  Clicking on it won't close the panel,
                so this can be done repeatedly.
           (b)  Same as (a), only backwards.
           (c)  This button closes the panel and returns to EDIT MODE, with
                the sketch-DRAWing feature enabled (see above).
           (d)  Closes the panel and returns to EDIT MODE, with the sketch-
                ERASing feature enabled (see above).  Don't panic if entered
                text vanishes all of a sudden when you do this: this is
                because wmpinboard intentionally hides it to eradicate the
                need for you to make wild guesses as to what's entered text
                and which pixels belong to a sketch.
           (e)  This button removes all entered text on the current note and
                places the text cursor on the very first character.  Besides,
                it closes the panel, thus returning to EDIT MODE.
           (f)  Pressing this button completely removes a drawn sketch on the
                current note and returns to EDIT MODE.
           (g)  This option removes the *entire* note from the board and
                returns to PINBOARD VIEW.
           (h)  This button merely closes the panel (and thus puts you back
                in EDIT MODE).  The same can be achieved by simply right-
                clicking in this view.

 - I don't live in an English-speaking country, so what about extended
   characters (umlauts, accents, cyrillic alphabet)?

     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 -f FONT

     where FONT is either a shortcut for a compiled-in font name (see
     `wmpinboard --help` for a list of those) or a valid, complete X font
     descriptor.  wmpinboard will remember the specified font, so it's
     actually not necessary to use this parameter more than once.  To change
     the font to use at a later time, run wmpinboard with a different font
     specification.  Note that this ONLY WORKS IF THERE ARE NO MORE NOTES ON
     THE BOARD.  It's been intentionally 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 font specified either explicitly via a command line parameter
     or implicitly via wmpinboard's data file 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.

 - How can I disable those vexing, superfluous animations?

     $ wmpinboard --light

 - Why aren't those animations smooth all of the time?  Sometimes it looks
   like they're being skipped entirely.

     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.  I don't see a way
     to avoid this effect--either this, or you turn off animations entirely.

 - When I leave wmpinboard idle in edit mode for some time, edit mode is
   terminated automatically.  Is that intended?

     Yes.  After 60 idle seconds 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 `wmpinboard --help` for this.

 - When does wmpinboard save its data?

     Notes data is saved on each of these occasions:

       - whenever edit mode is terminated
       - when you switch notes in edit mode (via [Shift]-[arrow key])
       - when a note has been moved on the board

     Notes are saved to a file called ".wmpinboarddata" in your home
     directory.

 - I've tried my best and littered the entire pinboard with quite a lot of
   notes.  Now I can't seem to be able to add another one.

     There's a compile time limit of 20 notes.  I think more notes on this
     tiny a board really don't make any sense.

 - I've explicitly configured my window manager for click-based rather than
   mouse-following focus, but wmpinboard's focus follows the mouse regardless.
   Can I change this?

     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:

       - when a new note is created (NOT when you click on an existing note--
         you'll have to explicitly click on the editing area to make it claim
         focus; this way, you can just view a note without any change to
         keyboard focus)
       - when you click somewhere on the text area in edit mode

     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.

 - Is wmpinboard compatible with AfterStep's Wharf?

     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 `wmpinboard --help`.

     Swallowing evidently works with AfterStep 1.6.10; I don't know about
     earlier versions.

 - Can I run multiple instances of wmpinboard as the same user, simultaneously?

     No, this is certainly not a good idea.  The run-time behavior may be
     unpredictable, and your "~/.wmpinboarddata" file can get corrupted.

 - Is wmpinboard Y2K compliant?

     No, unfortunately not.  Due to the high degree to which wmpinboard
     depends on calendar-related calculations, something dreadful will happen
     if it is run past the infamous year 2000 threshold; to prevent your
     system from being severely damaged, remove wmpinboard and all traces
     of its existence from your system prior to that!  You have been warned.

 - I've tried the program, yet I can't help but find it utterly useless.
   What shall I do?

     The solution is simple.  Just don't use it.

 - I've found a bug in wmpinboard.  Who shall I report it to?

     Mail to <gomar@mindless.com>.  Please also mention the version of
     wmpinboard you're using, your OS, X revision, and any additional,
     possibly relevant information when submitting a bug report.


                                                                   -- Marco

