sys/man/2/scribble

   1 .TH SCRIBBLE 2
   2 .SH NAME
   3 scribblealloc,
   4 recognize \- character recognition
   5 .SH SYNOPSIS
   6 .PP
   7 .EX
   8 .ta 4n +4n +4n +4n +4n +4n +4n +4n +4n +4n
   9 #include <u.h>
  10 #include <libc.h>
  11 #include <draw.h>
  12 #include <scribble.h>
  13
  14 Scribble        *scribblealloc(void);
  15 Rune            recognize(Scribble *);
  16 .EE
  17 .SH DESCRIPTION
  18 .PP
  19 The scribble library implements simple character recognition.
  20 All characters are drawn using a single stroke of the pen (mouse button 1)
  21 as on a palmtop computer.
  22 A reference card is in
  23 .BR /sys/src/libscribble/quickref.gif .
  24 .PP
  25 The library is not really intended for standalone use.  Its primary
  26 use is by the scribble graphical control (see
  27 .IR control (2)).
  28 .PP
  29 .B Scribblealloc
  30 allocates and returns an appropriately initialized
  31 .B Scribble
  32 structure:
  33 .IP
  34 .EX
  35 .ta 4n +4n +4n +4n +4n +4n +4n +4n +4n +4n
  36 #define CS_LETTERS                      0
  37 #define CS_DIGITS                       1
  38 #define CS_PUNCTUATION  2
  39
  40 struct Scribble {
  41         /* private state */
  42         Point                   *pt;
  43         int                     ppasize;
  44         Stroke     ps;
  45         Graffiti                *graf;
  46         int                     capsLock;
  47         int                     puncShift;
  48         int                     tmpShift;
  49         int                     ctrlShift;
  50         int                     curCharSet;
  51 };
  52 .EE
  53 .PP
  54 This structure encodes the points making up the stroke
  55 to be recognized, as well as the \f2character group\fP in which
  56 the stroke should be searched.
  57 .PP
  58 There are three such groups:
  59 .IR letters ,
  60 .IR digits ,
  61 and
  62 .IR punctuation .
  63 The current group is encoded in the
  64 .B curCharSet
  65 field of the
  66 .B Scribble
  67 structure.
  68 Special strokes are recognized to switch between groups.
  69 In addition, the charater recognized is influenced by
  70 .I mode
  71 parameters and modifies them.
  72 These are identified by the
  73 .BR capsLock ,
  74 .BR puncShift ,
  75 .BR tmpShift ,
  76 and
  77 .B ctrlShift
  78 fields of the
  79 .B Scribble
  80 structure.
  81 When
  82 .B puncShift
  83 is non-zero, the character is recognized in the punctuation
  84 character set.
  85 Similarly,
  86 when the character recognized is printable and
  87 .B ctrlShift
  88 is set, the associated control character is returned as if the
  89 control key were depressed,
  90 and when the character is a letter and
  91 .B capsLock
  92 or
  93 .B tmpShift
  94 is set, the upper-case version is returned.
  95 The
  96 .B puncShift
  97 and
  98 .B tmpShift
  99 flags are turned off
 100 once a character has been recognized; the others are left set.
 101 .PP
 102 The character to be recognized is encoded as an array of pen_points in the
 103 .B ps
 104 field.
 105 To allow easy drawing of the stroke as it is drawn,
 106 the
 107 .I pt
 108 and
 109 .I ppasize
 110 fields are available to the application code for storing an array
 111 of points for a call to
 112 .B poly
 113 (see
 114 .IR draw (2)).
 115 .PP
 116 .I Recognize
 117 recognizes the character provided in the
 118 .B ps
 119 field of the
 120 .B Scribble
 121 structure; it
 122 returns the rune or zero if nothing was recognized.
 123 .SH FILES
 124 .B /sys/src/libscribble/quickref.gif
 125 serves as a quick reference card.
 126 .PP
 127 .B /sys/lib/scribble/classifiers
 128 contains the stroke definitions.
 129 .SH SOURCE
 130 .B /sys/src/libscribble
 131 .PP
 132 This library is adapted from software reproduced by permission:
 133 .PP
 134 .B Graffiti.c
 135 is based on the file
 136 .B Scribble.c
 137 copyrighted
 138 by Keith Packard:
 139 .IP
 140 Copyright © 1999 Keith Packard
 141 .PP
 142 Permission to use, copy, modify, distribute, and sell this software and its
 143 documentation for any purpose is hereby granted without fee, provided that
 144 the above copyright notice appear in all copies and that both that
 145 copyright notice and this permission notice appear in supporting
 146 documentation, and that the name of Keith Packard not be used in
 147 advertising or publicity pertaining to distribution of the software without
 148 specific, written prior permission.  Keith Packard makes no
 149 representations about the suitability of this software for any purpose.  It
 150 is provided "as is" without express or implied warranty.
 151 .PP
 152 Portions of the software Copyright © 1994 by Sun Microsystems Computer Company.
 153 .PP
 154 Portions of the software Copyright © 2000 by Compaq Computer Corporation.
 155 .SH SEE ALSO
 156 .B Keyboard
 157 and
 158 .B prompter
 159 in
 160 .IR bitsyload (1),
 161 .IR draw (2),
 162 .IR control (2)