Doc/libstdwin.tex

   1 \chapter{STDWIN ONLY}
   2
   3 \section{Built-in Module \sectcode{stdwin}}
   4 \bimodindex{stdwin}
   5
   6 This module defines several new object types and functions that
   7 provide access to the functionality of the Standard Window System
   8 Interface, STDWIN [CWI report CR-R8817].
   9 It is available on systems to which STDWIN has been ported (which is
  10 most systems).
  11 It is only available if the \code{DISPLAY} environment variable is set
  12 or an explicit \samp{-display \var{displayname}} argument is passed to
  13 the interpreter.
  14
  15 Functions have names that usually resemble their C STDWIN counterparts
  16 with the initial `w' dropped.
  17 Points are represented by pairs of integers; rectangles
  18 by pairs of points.
  19 For a complete description of STDWIN please refer to the documentation
  20 of STDWIN for C programmers (aforementioned CWI report).
  21
  22 \subsection{Functions Defined in Module \sectcode{stdwin}}
  23
  24 The following functions are defined in the \code{stdwin} module:
  25
  26 \renewcommand{\indexsubitem}{(in module stdwin)}
  27 \begin{funcdesc}{open}{title}
  28 Open a new window whose initial title is given by the string argument.
  29 Return a window object; window object methods are described below.%
  30 \footnote{The Python version of STDWIN does not support draw procedures; all
  31         drawing requests are reported as draw events.}
  32 \end{funcdesc}
  33
  34 \begin{funcdesc}{getevent}{}
  35 Wait for and return the next event.
  36 An event is returned as a triple: the first element is the event
  37 type, a small integer; the second element is the window object to which
  38 the event applies, or
  39 \code{None}
  40 if it applies to no window in particular;
  41 the third element is type-dependent.
  42 Names for event types and command codes are defined in the standard
  43 module
  44 \code{stdwinevent}.
  45 \end{funcdesc}
  46
  47 \begin{funcdesc}{pollevent}{}
  48 Return the next event, if one is immediately available.
  49 If no event is available, return \code{()}.
  50 \end{funcdesc}
  51
  52 \begin{funcdesc}{getactive}{}
  53 Return the window that is currently active, or \code{None} if no
  54 window is currently active.  (This can be emulated by monitoring
  55 WE_ACTIVATE and WE_DEACTIVATE events.)
  56 \end{funcdesc}
  57
  58 \begin{funcdesc}{listfontnames}{pattern}
  59 Return the list of font names in the system that match the pattern (a
  60 string).  The pattern should normally be \code{'*'}; returns all
  61 available fonts.  If the underlying window system is X11, other
  62 patterns follow the standard X11 font selection syntax (as used e.g.
  63 in resource definitions), i.e. the wildcard character \code{'*'}
  64 matches any sequence of characters (including none) and \code{'?'}
  65 matches any single character.
  66 \end{funcdesc}
  67
  68 \begin{funcdesc}{setdefscrollbars}{hflag\, vflag}
  69 Set the flags controlling whether subsequently opened windows will
  70 have horizontal and/or vertical scroll bars.
  71 \end{funcdesc}
  72
  73 \begin{funcdesc}{setdefwinpos}{h\, v}
  74 Set the default window position for windows opened subsequently.
  75 \end{funcdesc}
  76
  77 \begin{funcdesc}{setdefwinsize}{width\, height}
  78 Set the default window size for windows opened subsequently.
  79 \end{funcdesc}
  80
  81 \begin{funcdesc}{getdefscrollbars}{}
  82 Return the flags controlling whether subsequently opened windows will
  83 have horizontal and/or vertical scroll bars.
  84 \end{funcdesc}
  85
  86 \begin{funcdesc}{getdefwinpos}{}
  87 Return the default window position for windows opened subsequently.
  88 \end{funcdesc}
  89
  90 \begin{funcdesc}{getdefwinsize}{}
  91 Return the default window size for windows opened subsequently.
  92 \end{funcdesc}
  93
  94 \begin{funcdesc}{getscrsize}{}
  95 Return the screen size in pixels.
  96 \end{funcdesc}
  97
  98 \begin{funcdesc}{getscrmm}{}
  99 Return the screen size in millimeters.
 100 \end{funcdesc}
 101
 102 \begin{funcdesc}{fetchcolor}{colorname}
 103 Return the pixel value corresponding to the given color name.
 104 Return the default foreground color for unknown color names.
 105 Hint: the following code tests whether you are on a machine that
 106 supports more than two colors:
 107 \bcode\begin{verbatim}
 108 if stdwin.fetchcolor('black') <> \
 109           stdwin.fetchcolor('red') <> \
 110           stdwin.fetchcolor('white'):
 111     print 'color machine'
 112 else:
 113     print 'monochrome machine'
 114 \end{verbatim}\ecode
 115 \end{funcdesc}
 116
 117 \begin{funcdesc}{setfgcolor}{pixel}
 118 Set the default foreground color.
 119 This will become the default foreground color of windows opened
 120 subsequently, including dialogs.
 121 \end{funcdesc}
 122
 123 \begin{funcdesc}{setbgcolor}{pixel}
 124 Set the default background color.
 125 This will become the default background color of windows opened
 126 subsequently, including dialogs.
 127 \end{funcdesc}
 128
 129 \begin{funcdesc}{getfgcolor}{}
 130 Return the pixel value of the current default foreground color.
 131 \end{funcdesc}
 132
 133 \begin{funcdesc}{getbgcolor}{}
 134 Return the pixel value of the current default background color.
 135 \end{funcdesc}
 136
 137 \begin{funcdesc}{setfont}{fontname}
 138 Set the current default font.
 139 This will become the default font for windows opened subsequently,
 140 and is also used by the text measuring functions \code{textwidth},
 141 \code{textbreak}, \code{lineheight} and \code{baseline} below.
 142 This accepts two more optional parameters, size and style:
 143 Size is the font size (in `points').
 144 Style is a single character specifying the style, as follows:
 145 \code{'b'} = bold,
 146 \code{'i'} = italic,
 147 \code{'o'} = bold + italic,
 148 \code{'u'} = underline;
 149 default style is roman.
 150 Size and style are ignored under X11 but used on the Macintosh.
 151 (Sorry for all this complexity --- a more uniform interface is being designed.)
 152 \end{funcdesc}
 153
 154 \begin{funcdesc}{menucreate}{title}
 155 Create a menu object referring to a global menu (a menu that appears in
 156 all windows).
 157 Methods of menu objects are described below.
 158 Note: normally, menus are created locally; see the window method
 159 \code{menucreate} below.
 160 \strong{Warning:} the menu only appears in a window as long as the object
 161 returned by this call exists.
 162 \end{funcdesc}
 163
 164 \begin{funcdesc}{newbitmap}{width\, height}
 165 Create a new bitmap object of the given dimensions.
 166 Methods of bitmap objects are described below.
 167 \end{funcdesc}
 168
 169 \begin{funcdesc}{fleep}{}
 170 Cause a beep or bell (or perhaps a `visual bell' or flash, hence the
 171 name).
 172 \end{funcdesc}
 173
 174 \begin{funcdesc}{message}{string}
 175 Display a dialog box containing the string.
 176 The user must click OK before the function returns.
 177 \end{funcdesc}
 178
 179 \begin{funcdesc}{askync}{prompt\, default}
 180 Display a dialog that prompts the user to answer a question with yes or
 181 no.
 182 Return 0 for no, 1 for yes.
 183 If the user hits the Return key, the default (which must be 0 or 1) is
 184 returned.
 185 If the user cancels the dialog, the
 186 \code{KeyboardInterrupt}
 187 exception is raised.
 188 \end{funcdesc}
 189
 190 \begin{funcdesc}{askstr}{prompt\, default}
 191 Display a dialog that prompts the user for a string.
 192 If the user hits the Return key, the default string is returned.
 193 If the user cancels the dialog, the
 194 \code{KeyboardInterrupt}
 195 exception is raised.
 196 \end{funcdesc}
 197
 198 \begin{funcdesc}{askfile}{prompt\, default\, new}
 199 Ask the user to specify a filename.
 200 If
 201 \var{new}
 202 is zero it must be an existing file; otherwise, it must be a new file.
 203 If the user cancels the dialog, the
 204 \code{KeyboardInterrupt}
 205 exception is raised.
 206 \end{funcdesc}
 207
 208 \begin{funcdesc}{setcutbuffer}{i\, string}
 209 Store the string in the system's cut buffer number
 210 \var{i},
 211 where it can be found (for pasting) by other applications.
 212 On X11, there are 8 cut buffers (numbered 0..7).
 213 Cut buffer number 0 is the `clipboard' on the Macintosh.
 214 \end{funcdesc}
 215
 216 \begin{funcdesc}{getcutbuffer}{i}
 217 Return the contents of the system's cut buffer number
 218 \var{i}.
 219 \end{funcdesc}
 220
 221 \begin{funcdesc}{rotatecutbuffers}{n}
 222 On X11, rotate the 8 cut buffers by
 223 \var{n}.
 224 Ignored on the Macintosh.
 225 \end{funcdesc}
 226
 227 \begin{funcdesc}{getselection}{i}
 228 Return X11 selection number
 229 \var{i.}
 230 Selections are not cut buffers.
 231 Selection numbers are defined in module
 232 \code{stdwinevents}.
 233 Selection \code{WS_PRIMARY} is the
 234 \dfn{primary}
 235 selection (used by
 236 xterm,
 237 for instance);
 238 selection \code{WS_SECONDARY} is the
 239 \dfn{secondary}
 240 selection; selection \code{WS_CLIPBOARD} is the
 241 \dfn{clipboard}
 242 selection (used by
 243 xclipboard).
 244 On the Macintosh, this always returns an empty string.
 245 \end{funcdesc}
 246
 247 \begin{funcdesc}{resetselection}{i}
 248 Reset selection number
 249 \var{i},
 250 if this process owns it.
 251 (See window method
 252 \code{setselection()}).
 253 \end{funcdesc}
 254
 255 \begin{funcdesc}{baseline}{}
 256 Return the baseline of the current font (defined by STDWIN as the
 257 vertical distance between the baseline and the top of the
 258 characters).
 259 \end{funcdesc}
 260
 261 \begin{funcdesc}{lineheight}{}
 262 Return the total line height of the current font.
 263 \end{funcdesc}
 264
 265 \begin{funcdesc}{textbreak}{str\, width}
 266 Return the number of characters of the string that fit into a space of
 267 \var{width}
 268 bits wide when drawn in the curent font.
 269 \end{funcdesc}
 270
 271 \begin{funcdesc}{textwidth}{str}
 272 Return the width in bits of the string when drawn in the current font.
 273 \end{funcdesc}
 274
 275 \begin{funcdesc}{connectionnumber}{}
 276 \funcline{fileno}{}
 277 (X11 under \UNIX{} only) Return the ``connection number'' used by the
 278 underlying X11 implementation.  (This is normally the file number of
 279 the socket.)  Both functions return the same value;
 280 \code{connectionnumber()} is named after the corresponding function in
 281 X11 and STDWIN, while \code{fileno()} makes it possible to use the
 282 \code{stdwin} module as a ``file'' object parameter to
 283 \code{select.select()}.  Note that if \code{select()} implies that
 284 input is possible on \code{stdwin}, this does not guarantee that an
 285 event is ready --- it may be some internal communication going on
 286 between the X server and the client library.  Thus, you should call
 287 \code{stdwin.pollevent()} until it returns \code{None} to check for
 288 events if you don't want your program to block.  Because of internal
 289 buffering in X11, it is also possible that \code{stdwin.pollevent()}
 290 returns an event while \code{select()} does not find \code{stdwin} to
 291 be ready, so you should read any pending events with
 292 \code{stdwin.pollevent()} until it returns \code{None} before entering
 293 a blocking \code{select()} call.
 294 \ttindex{select}
 295 \end{funcdesc}
 296
 297 \subsection{Window Object Methods}
 298
 299 Window objects are created by \code{stdwin.open()}.  They are closed
 300 by their \code{close()} method or when they are garbage-collected.
 301 Window objects have the following methods:
 302
 303 \renewcommand{\indexsubitem}{(window method)}
 304
 305 \begin{funcdesc}{begindrawing}{}
 306 Return a drawing object, whose methods (described below) allow drawing
 307 in the window.
 308 \end{funcdesc}
 309
 310 \begin{funcdesc}{change}{rect}
 311 Invalidate the given rectangle; this may cause a draw event.
 312 \end{funcdesc}
 313
 314 \begin{funcdesc}{gettitle}{}
 315 Returns the window's title string.
 316 \end{funcdesc}
 317
 318 \begin{funcdesc}{getdocsize}{}
 319 \begin{sloppypar}
 320 Return a pair of integers giving the size of the document as set by
 321 \code{setdocsize()}.
 322 \end{sloppypar}
 323 \end{funcdesc}
 324
 325 \begin{funcdesc}{getorigin}{}
 326 Return a pair of integers giving the origin of the window with respect
 327 to the document.
 328 \end{funcdesc}
 329
 330 \begin{funcdesc}{gettitle}{}
 331 Return the window's title string.
 332 \end{funcdesc}
 333
 334 \begin{funcdesc}{getwinsize}{}
 335 Return a pair of integers giving the size of the window.
 336 \end{funcdesc}
 337
 338 \begin{funcdesc}{getwinpos}{}
 339 Return a pair of integers giving the position of the window's upper
 340 left corner (relative to the upper left corner of the screen).
 341 \end{funcdesc}
 342
 343 \begin{funcdesc}{menucreate}{title}
 344 Create a menu object referring to a local menu (a menu that appears
 345 only in this window).
 346 Methods of menu objects are described below.
 347 {\bf Warning:} the menu only appears as long as the object
 348 returned by this call exists.
 349 \end{funcdesc}
 350
 351 \begin{funcdesc}{scroll}{rect\, point}
 352 Scroll the given rectangle by the vector given by the point.
 353 \end{funcdesc}
 354
 355 \begin{funcdesc}{setdocsize}{point}
 356 Set the size of the drawing document.
 357 \end{funcdesc}
 358
 359 \begin{funcdesc}{setorigin}{point}
 360 Move the origin of the window (its upper left corner)
 361 to the given point in the document.
 362 \end{funcdesc}
 363
 364 \begin{funcdesc}{setselection}{i\, str}
 365 Attempt to set X11 selection number
 366 \var{i}
 367 to the string
 368 \var{str}.
 369 (See stdwin method
 370 \code{getselection()}
 371 for the meaning of
 372 \var{i}.)
 373 Return true if it succeeds.
 374 If  succeeds, the window ``owns'' the selection until
 375 (a) another application takes ownership of the selection; or
 376 (b) the window is deleted; or
 377 (c) the application clears ownership by calling
 378 \code{stdwin.resetselection(\var{i})}.
 379 When another application takes ownership of the selection, a
 380 \code{WE_LOST_SEL}
 381 event is received for no particular window and with the selection number
 382 as detail.
 383 Ignored on the Macintosh.
 384 \end{funcdesc}
 385
 386 \begin{funcdesc}{settimer}{dsecs}
 387 Schedule a timer event for the window in
 388 \code{\var{dsecs}/10}
 389 seconds.
 390 \end{funcdesc}
 391
 392 \begin{funcdesc}{settitle}{title}
 393 Set the window's title string.
 394 \end{funcdesc}
 395
 396 \begin{funcdesc}{setwincursor}{name}
 397 \begin{sloppypar}
 398 Set the window cursor to a cursor of the given name.
 399 It raises the
 400 \code{RuntimeError}
 401 exception if no cursor of the given name exists.
 402 Suitable names include
 403 \code{'ibeam'},
 404 \code{'arrow'},
 405 \code{'cross'},
 406 \code{'watch'}
 407 and
 408 \code{'plus'}.
 409 On X11, there are many more (see
 410 \file{<X11/cursorfont.h>}).
 411 \end{sloppypar}
 412 \end{funcdesc}
 413
 414 \begin{funcdesc}{setwinpos}{h\, v}
 415 Set the the position of the window's upper left corner (relative to
 416 the upper left corner of the screen).
 417 \end{funcdesc}
 418
 419 \begin{funcdesc}{setwinsize}{width\, height}
 420 Set the window's size.
 421 \end{funcdesc}
 422
 423 \begin{funcdesc}{show}{rect}
 424 Try to ensure that the given rectangle of the document is visible in
 425 the window.
 426 \end{funcdesc}
 427
 428 \begin{funcdesc}{textcreate}{rect}
 429 Create a text-edit object in the document at the given rectangle.
 430 Methods of text-edit objects are described below.
 431 \end{funcdesc}
 432
 433 \begin{funcdesc}{setactive}{}
 434 Attempt to make this window the active window.  If successful, this
 435 will generate a WE_ACTIVATE event (and a WE_DEACTIVATE event in case
 436 another window in this application became inactive).
 437 \end{funcdesc}
 438
 439 \begin{funcdesc}{close}{}
 440 Discard the window object.  It should not be used again.
 441 \end{funcdesc}
 442
 443 \subsection{Drawing Object Methods}
 444
 445 Drawing objects are created exclusively by the window method
 446 \code{begindrawing()}.
 447 Only one drawing object can exist at any given time; the drawing object
 448 must be deleted to finish drawing.
 449 No drawing object may exist when
 450 \code{stdwin.getevent()}
 451 is called.
 452 Drawing objects have the following methods:
 453
 454 \renewcommand{\indexsubitem}{(drawing method)}
 455
 456 \begin{funcdesc}{box}{rect}
 457 Draw a box just inside a rectangle.
 458 \end{funcdesc}
 459
 460 \begin{funcdesc}{circle}{center\, radius}
 461 Draw a circle with given center point and radius.
 462 \end{funcdesc}
 463
 464 \begin{funcdesc}{elarc}{center\, \(rh\, rv\)\, \(a1\, a2\)}
 465 Draw an elliptical arc with given center point.
 466 \code{(\var{rh}, \var{rv})}
 467 gives the half sizes of the horizontal and vertical radii.
 468 \code{(\var{a1}, \var{a2})}
 469 gives the angles (in degrees) of the begin and end points.
 470 0 degrees is at 3 o'clock, 90 degrees is at 12 o'clock.
 471 \end{funcdesc}
 472
 473 \begin{funcdesc}{erase}{rect}
 474 Erase a rectangle.
 475 \end{funcdesc}
 476
 477 \begin{funcdesc}{fillcircle}{center\, radius}
 478 Draw a filled circle with given center point and radius.
 479 \end{funcdesc}
 480
 481 \begin{funcdesc}{fillelarc}{center\, \(rh\, rv\)\, \(a1\, a2\)}
 482 Draw a filled elliptical arc; arguments as for \code{elarc}.
 483 \end{funcdesc}
 484
 485 \begin{funcdesc}{fillpoly}{points}
 486 Draw a filled polygon given by a list (or tuple) of points.
 487 \end{funcdesc}
 488
 489 \begin{funcdesc}{invert}{rect}
 490 Invert a rectangle.
 491 \end{funcdesc}
 492
 493 \begin{funcdesc}{line}{p1\, p2}
 494 Draw a line from point
 495 \var{p1}
 496 to
 497 \var{p2}.
 498 \end{funcdesc}
 499
 500 \begin{funcdesc}{paint}{rect}
 501 Fill a rectangle.
 502 \end{funcdesc}
 503
 504 \begin{funcdesc}{poly}{points}
 505 Draw the lines connecting the given list (or tuple) of points.
 506 \end{funcdesc}
 507
 508 \begin{funcdesc}{shade}{rect\, percent}
 509 Fill a rectangle with a shading pattern that is about
 510 \var{percent}
 511 percent filled.
 512 \end{funcdesc}
 513
 514 \begin{funcdesc}{text}{p\, str}
 515 Draw a string starting at point p (the point specifies the
 516 top left coordinate of the string).
 517 \end{funcdesc}
 518
 519 \begin{funcdesc}{xorcircle}{center\, radius}
 520 \funcline{xorelarc}{center\, \(rh\, rv\)\, \(a1\, a2\)}
 521 \funcline{xorline}{p1\, p2}
 522 \funcline{xorpoly}{points}
 523 Draw a circle, an elliptical arc, a line or a polygon, respectively,
 524 in XOR mode.
 525 \end{funcdesc}
 526
 527 \begin{funcdesc}{setfgcolor}{}
 528 \funcline{setbgcolor}{}
 529 \funcline{getfgcolor}{}
 530 \funcline{getbgcolor}{}
 531 These functions are similar to the corresponding functions described
 532 above for the
 533 \code{stdwin}
 534 module, but affect or return the colors currently used for drawing
 535 instead of the global default colors.
 536 When a drawing object is created, its colors are set to the window's
 537 default colors, which are in turn initialized from the global default
 538 colors when the window is created.
 539 \end{funcdesc}
 540
 541 \begin{funcdesc}{setfont}{}
 542 \funcline{baseline}{}
 543 \funcline{lineheight}{}
 544 \funcline{textbreak}{}
 545 \funcline{textwidth}{}
 546 These functions are similar to the corresponding functions described
 547 above for the
 548 \code{stdwin}
 549 module, but affect or use the current drawing font instead of
 550 the global default font.
 551 When a drawing object is created, its font is set to the window's
 552 default font, which is in turn initialized from the global default
 553 font when the window is created.
 554 \end{funcdesc}
 555
 556 \begin{funcdesc}{bitmap}{point\, bitmap\, mask}
 557 Draw the \var{bitmap} with its top left corner at \var{point}.
 558 If the optional \var{mask} argument is present, it should be either
 559 the same object as \var{bitmap}, to draw only those bits that are set
 560 in the bitmap, in the foreground color, or \code{None}, to draw all
 561 bits (ones are drawn in the foreground color, zeros in the background
 562 color).
 563 \end{funcdesc}
 564
 565 \begin{funcdesc}{cliprect}{rect}
 566 Set the ``clipping region'' to a rectangle.
 567 The clipping region limits the effect of all drawing operations, until
 568 it is changed again or until the drawing object is closed.  When a
 569 drawing object is created the clipping region is set to the entire
 570 window.  When an object to be drawn falls partly outside the clipping
 571 region, the set of pixels drawn is the intersection of the clipping
 572 region and the set of pixels that would be drawn by the same operation
 573 in the absence of a clipping region.
 574 \end{funcdesc}
 575
 576 \begin{funcdesc}{noclip}{}
 577 Reset the clipping region to the entire window.
 578 \end{funcdesc}
 579
 580 \begin{funcdesc}{close}{}
 581 \funcline{enddrawing}{}
 582 Discard the drawing object.  It should not be used again.
 583 \end{funcdesc}
 584
 585 \subsection{Menu Object Methods}
 586
 587 A menu object represents a menu.
 588 The menu is destroyed when the menu object is deleted.
 589 The following methods are defined:
 590
 591 \renewcommand{\indexsubitem}{(menu method)}
 592
 593 \begin{funcdesc}{additem}{text\, shortcut}
 594 Add a menu item with given text.
 595 The shortcut must be a string of length 1, or omitted (to specify no
 596 shortcut).
 597 \end{funcdesc}
 598
 599 \begin{funcdesc}{setitem}{i\, text}
 600 Set the text of item number
 601 \var{i}.
 602 \end{funcdesc}
 603
 604 \begin{funcdesc}{enable}{i\, flag}
 605 Enable or disables item
 606 \var{i}.
 607 \end{funcdesc}
 608
 609 \begin{funcdesc}{check}{i\, flag}
 610 Set or clear the
 611 \dfn{check mark}
 612 for item
 613 \var{i}.
 614 \end{funcdesc}
 615
 616 \begin{funcdesc}{close}{}
 617 Discard the menu object.  It should not be used again.
 618 \end{funcdesc}
 619
 620 \subsection{Bitmap Object Methods}
 621
 622 A bitmap represents a rectangular array of bits.
 623 The top left bit has coordinate (0, 0).
 624 A bitmap can be drawn with the \code{bitmap} method of a drawing object.
 625 The following methods are defined:
 626
 627 \renewcommand{\indexsubitem}{(bitmap method)}
 628
 629 \begin{funcdesc}{getsize}{}
 630 Return a tuple representing the width and height of the bitmap.
 631 (This returns the values that have been passed to the \code{newbitmap}
 632 function.)
 633 \end{funcdesc}
 634
 635 \begin{funcdesc}{setbit}{point\, bit}
 636 Set the value of the bit indicated by \var{point} to \var{bit}.
 637 \end{funcdesc}
 638
 639 \begin{funcdesc}{getbit}{point}
 640 Return the value of the bit indicated by \var{point}.
 641 \end{funcdesc}
 642
 643 \begin{funcdesc}{close}{}
 644 Discard the bitmap object.  It should not be used again.
 645 \end{funcdesc}
 646
 647 \subsection{Text-edit Object Methods}
 648
 649 A text-edit object represents a text-edit block.
 650 For semantics, see the STDWIN documentation for C programmers.
 651 The following methods exist:
 652
 653 \renewcommand{\indexsubitem}{(text-edit method)}
 654
 655 \begin{funcdesc}{arrow}{code}
 656 Pass an arrow event to the text-edit block.
 657 The
 658 \var{code}
 659 must be one of
 660 \code{WC_LEFT},
 661 \code{WC_RIGHT},
 662 \code{WC_UP}
 663 or
 664 \code{WC_DOWN}
 665 (see module
 666 \code{stdwinevents}).
 667 \end{funcdesc}
 668
 669 \begin{funcdesc}{draw}{rect}
 670 Pass a draw event to the text-edit block.
 671 The rectangle specifies the redraw area.
 672 \end{funcdesc}
 673
 674 \begin{funcdesc}{event}{type\, window\, detail}
 675 Pass an event gotten from
 676 \code{stdwin.getevent()}
 677 to the text-edit block.
 678 Return true if the event was handled.
 679 \end{funcdesc}
 680
 681 \begin{funcdesc}{getfocus}{}
 682 Return 2 integers representing the start and end positions of the
 683 focus, usable as slice indices on the string returned by
 684 \code{gettext()}.
 685 \end{funcdesc}
 686
 687 \begin{funcdesc}{getfocustext}{}
 688 Return the text in the focus.
 689 \end{funcdesc}
 690
 691 \begin{funcdesc}{getrect}{}
 692 Return a rectangle giving the actual position of the text-edit block.
 693 (The bottom coordinate may differ from the initial position because
 694 the block automatically shrinks or grows to fit.)
 695 \end{funcdesc}
 696
 697 \begin{funcdesc}{gettext}{}
 698 Return the entire text buffer.
 699 \end{funcdesc}
 700
 701 \begin{funcdesc}{move}{rect}
 702 Specify a new position for the text-edit block in the document.
 703 \end{funcdesc}
 704
 705 \begin{funcdesc}{replace}{str}
 706 Replace the text in the focus by the given string.
 707 The new focus is an insert point at the end of the string.
 708 \end{funcdesc}
 709
 710 \begin{funcdesc}{setfocus}{i\, j}
 711 Specify the new focus.
 712 Out-of-bounds values are silently clipped.
 713 \end{funcdesc}
 714
 715 \begin{funcdesc}{settext}{str}
 716 Replace the entire text buffer by the given string and set the focus
 717 to \code{(0, 0)}.
 718 \end{funcdesc}
 719
 720 \begin{funcdesc}{setview}{rect}
 721 Set the view rectangle to \var{rect}.  If \var{rect} is \code{None},
 722 viewing mode is reset.  In viewing mode, all output from the text-edit
 723 object is clipped to the viewing rectangle.  This may be useful to
 724 implement your own scrolling text subwindow.
 725 \end{funcdesc}
 726
 727 \begin{funcdesc}{close}{}
 728 Discard the text-edit object.  It should not be used again.
 729 \end{funcdesc}
 730
 731 \subsection{Example}
 732 \nodename{Stdwin Example}
 733
 734 Here is a minimal example of using STDWIN in Python.
 735 It creates a window and draws the string ``Hello world'' in the top
 736 left corner of the window.
 737 The window will be correctly redrawn when covered and re-exposed.
 738 The program quits when the close icon or menu item is requested.
 739
 740 \bcode\begin{verbatim}
 741 import stdwin
 742 from stdwinevents import *
 743
 744 def main():
 745     mywin = stdwin.open('Hello')
 746     #
 747     while 1:
 748         (type, win, detail) = stdwin.getevent()
 749         if type == WE_DRAW:
 750             draw = win.begindrawing()
 751             draw.text((0, 0), 'Hello, world')
 752             del draw
 753         elif type == WE_CLOSE:
 754             break
 755
 756 main()
 757 \end{verbatim}\ecode
 758
 759 \section{Standard Module \sectcode{stdwinevents}}
 760 \stmodindex{stdwinevents}
 761
 762 This module defines constants used by STDWIN for event types
 763 (\code{WE_ACTIVATE} etc.), command codes (\code{WC_LEFT} etc.)
 764 and selection types (\code{WS_PRIMARY} etc.).
 765 Read the file for details.
 766 Suggested usage is
 767
 768 \bcode\begin{verbatim}
 769 >>> from stdwinevents import *
 770 >>>
 771 \end{verbatim}\ecode
 772
 773 \section{Standard Module \sectcode{rect}}
 774 \stmodindex{rect}
 775
 776 This module contains useful operations on rectangles.
 777 A rectangle is defined as in module
 778 \code{stdwin}:
 779 a pair of points, where a point is a pair of integers.
 780 For example, the rectangle
 781
 782 \bcode\begin{verbatim}
 783 (10, 20), (90, 80)
 784 \end{verbatim}\ecode
 785
 786 is a rectangle whose left, top, right and bottom edges are 10, 20, 90
 787 and 80, respectively.
 788 Note that the positive vertical axis points down (as in
 789 \code{stdwin}).
 790
 791 The module defines the following objects:
 792
 793 \renewcommand{\indexsubitem}{(in module rect)}
 794 \begin{excdesc}{error}
 795 The exception raised by functions in this module when they detect an
 796 error.
 797 The exception argument is a string describing the problem in more
 798 detail.
 799 \end{excdesc}
 800
 801 \begin{datadesc}{empty}
 802 The rectangle returned when some operations return an empty result.
 803 This makes it possible to quickly check whether a result is empty:
 804
 805 \bcode\begin{verbatim}
 806 >>> import rect
 807 >>> r1 = (10, 20), (90, 80)
 808 >>> r2 = (0, 0), (10, 20)
 809 >>> r3 = rect.intersect([r1, r2])
 810 >>> if r3 is rect.empty: print 'Empty intersection'
 811 Empty intersection
 812 >>>
 813 \end{verbatim}\ecode
 814 \end{datadesc}
 815
 816 \begin{funcdesc}{is_empty}{r}
 817 Returns true if the given rectangle is empty.
 818 A rectangle
 819 \code{(\var{left}, \var{top}), (\var{right}, \var{bottom})}
 820 is empty if
 821 \iftexi
 822 \code{\var{left} >= \var{right}} or \code{\var{top} => \var{bottom}}.
 823 \else
 824 $\var{left} \geq \var{right}$ or $\var{top} \geq \var{bottom}$.
 825 %%JHXXX{\em left~$\geq$~right} or {\em top~$\leq$~bottom}.
 826 \fi
 827 \end{funcdesc}
 828
 829 \begin{funcdesc}{intersect}{list}
 830 Returns the intersection of all rectangles in the list argument.
 831 It may also be called with a tuple argument.
 832 Raises
 833 \code{rect.error}
 834 if the list is empty.
 835 Returns
 836 \code{rect.empty}
 837 if the intersection of the rectangles is empty.
 838 \end{funcdesc}
 839
 840 \begin{funcdesc}{union}{list}
 841 Returns the smallest rectangle that contains all non-empty rectangles in
 842 the list argument.
 843 It may also be called with a tuple argument or with two or more
 844 rectangles as arguments.
 845 Returns
 846 \code{rect.empty}
 847 if the list is empty or all its rectangles are empty.
 848 \end{funcdesc}
 849
 850 \begin{funcdesc}{pointinrect}{point\, rect}
 851 Returns true if the point is inside the rectangle.
 852 By definition, a point
 853 \code{(\var{h}, \var{v})}
 854 is inside a rectangle
 855 \code{(\var{left}, \var{top}), (\var{right}, \var{bottom})} if
 856 \iftexi
 857 \code{\var{left} <= \var{h} < \var{right}} and
 858 \code{\var{top} <= \var{v} < \var{bottom}}.
 859 \else
 860 $\var{left} \leq \var{h} < \var{right}$ and
 861 $\var{top} \leq \var{v} < \var{bottom}$.
 862 \fi
 863 \end{funcdesc}
 864
 865 \begin{funcdesc}{inset}{rect\, \(dh\, dv\)}
 866 Returns a rectangle that lies inside the
 867 \code{rect}
 868 argument by
 869 \var{dh}
 870 pixels horizontally
 871 and
 872 \var{dv}
 873 pixels
 874 vertically.
 875 If
 876 \var{dh}
 877 or
 878 \var{dv}
 879 is negative, the result lies outside
 880 \var{rect}.
 881 \end{funcdesc}
 882
 883 \begin{funcdesc}{rect2geom}{rect}
 884 Converts a rectangle to geometry representation:
 885 \code{(\var{left}, \var{top}), (\var{width}, \var{height})}.
 886 \end{funcdesc}
 887
 888 \begin{funcdesc}{geom2rect}{geom}
 889 Converts a rectangle given in geometry representation back to the
 890 standard rectangle representation
 891 \code{(\var{left}, \var{top}), (\var{right}, \var{bottom})}.
 892 \end{funcdesc}