SCRIBBLE(2)                                           SCRIBBLE(2)

     NAME
          scribblealloc, recognize - character recognition

     SYNOPSIS
          #include <u.h>
          #include <libc.h>
          #include <draw.h>
          #include <scribble.h>

          Scribble    *scribblealloc(void);
          Rune        recognize(Scribble *);

     DESCRIPTION
          The scribble library implements simple character
          recognition.  All characters are drawn using a single stroke
          of the pen (mouse button 1) as on a palmtop computer.  A
          reference card is in /sys/src/libscribble/quickref.gif.

          The library is not really intended for standalone use.  Its
          primary use is by the scribble graphical control (see
          control(2)).

          Scribblealloc allocates and returns an appropriately ini-
          tialized Scribble structure:

               #define CS_LETTERS          0
               #define CS_DIGITS           1
               #define CS_PUNCTUATION  2

               struct Scribble {
                   /* private state */
                   Point           *pt;
                   int         ppasize;
                   Stroke     ps;
                   Graffiti        *graf;
                   int         capsLock;
                   int         puncShift;
                   int         tmpShift;
                   int         ctrlShift;
                   int         curCharSet;
               };

          This structure encodes the points making up the stroke to be
          recognized, as well as the character group in which the
          stroke should be searched.

          There are three such groups: letters, digits, and
          punctuation. The current group is encoded in the curCharSet
          field of the Scribble structure.  Special strokes are recog-
          nized to switch between groups.  In addition, the charater

     SCRIBBLE(2)                                           SCRIBBLE(2)

          recognized is influenced by mode parameters and modifies
          them.  These are identified by the capsLock, puncShift,
          tmpShift, and ctrlShift fields of the Scribble structure.
          When puncShift is non-zero, the character is recognized in
          the punctuation character set.  Similarly, when the charac-
          ter recognized is printable and ctrlShift is set, the asso-
          ciated control character is returned as if the control key
          were depressed, and when the character is a letter and
          capsLock or tmpShift is set, the upper-case version is
          returned.  The puncShift and tmpShift flags are turned off
          once a character has been recognized; the others are left
          set.

          The character to be recognized is encoded as an array of
          pen_points in the ps field.  To allow easy drawing of the
          stroke as it is drawn, the pt and ppasize fields are avail-
          able to the application code for storing an array of points
          for a call to poly (see draw(2)).

          Recognize recognizes the character provided in the ps field
          of the Scribble structure; it returns the rune or zero if
          nothing was recognized.

     FILES
          /sys/src/libscribble/quickref.gif serves as a quick refer-
          ence card.

          /sys/lib/scribble/classifiers contains the stroke defini-
          tions.

     SOURCE
          /sys/src/libscribble

          This library is adapted from software reproduced by permis-
          sion:

          Graffiti.c is based on the file Scribble.c copyrighted by
          Keith Packard:

               Copyright © 1999 Keith Packard

          Permission to use, copy, modify, distribute, and sell this
          software and its documentation for any purpose is hereby
          granted without fee, provided that the above copyright
          notice appear in all copies and that both that copyright
          notice and this permission notice appear in supporting docu-
          mentation, and that the name of Keith Packard not be used in
          advertising or publicity pertaining to distribution of the
          software without specific, written prior permission.  Keith
          Packard makes no representations about the suitability of
          this software for any purpose.  It is provided "as is" with-
          out express or implied warranty.

     SCRIBBLE(2)                                           SCRIBBLE(2)

          Portions of the software Copyright © 1994 by Sun Microsys-
          tems Computer Company.

          Portions of the software Copyright © 2000 by Compaq Computer
          Corporation.

     SEE ALSO
          Keyboard and prompter in bitsyload(1), draw(2), control(2)