| \chapter{Standard Windowing Interface} |
| |
| The modules in this chapter are available only on those systems where |
| the STDWIN library is available. STDWIN runs on \UNIX{} under X11 and |
| on the Macintosh. See CWI report CS-R8817. |
| |
| \strong{Warning:} Using STDWIN is not recommended for new |
| applications. It has never been ported to Microsoft Windows or |
| Windows NT, and for X11 or the Macintosh it lacks important |
| functionality --- in particular, it has no tools for the construction |
| of dialogs. For most platforms, alternative, native solutions exist |
| (though none are currently documented in this manual): Tkinter for |
| \UNIX{} under X11, native Xt with Motif or Athena widgets for \UNIX{} |
| under X11, Win32 for Windows and Windows NT, and a collection of |
| native toolkit interfaces for the Macintosh. |
| |
| |
| \section{\module{stdwin} --- |
| Platform-independent GUI System} |
| |
| \declaremodule{builtin}{stdwin} |
| \modulesynopsis{Older GUI system for X11 and Macintosh.} |
| |
| |
| This module defines several new object types and functions that |
| provide access to the functionality of STDWIN. |
| |
| On \UNIX{} running X11, it can only be used if the \envvar{DISPLAY} |
| environment variable is set or an explicit \samp{-display |
| \var{displayname}} argument is passed to the Python interpreter. |
| |
| Functions have names that usually resemble their C STDWIN counterparts |
| with the initial `w' dropped. |
| Points are represented by pairs of integers; rectangles |
| by pairs of points. |
| For a complete description of STDWIN please refer to the documentation |
| of STDWIN for C programmers (aforementioned CWI report). |
| |
| \subsection{Functions Defined in Module \module{stdwin}} |
| \nodename{STDWIN Functions} |
| |
| The following functions are defined in the \module{stdwin} module: |
| |
| \begin{funcdesc}{open}{title} |
| Open a new window whose initial title is given by the string argument. |
| Return a window object; window object methods are described |
| below.\footnote{ |
| The Python version of STDWIN does not support draw procedures; |
| all drawing requests are reported as draw events.} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getevent}{} |
| Wait for and return the next event. |
| An event is returned as a triple: the first element is the event |
| type, a small integer; the second element is the window object to which |
| the event applies, or |
| \code{None} |
| if it applies to no window in particular; |
| the third element is type-dependent. |
| Names for event types and command codes are defined in the standard |
| module \refmodule{stdwinevents}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{pollevent}{} |
| Return the next event, if one is immediately available. |
| If no event is available, return \code{()}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getactive}{} |
| Return the window that is currently active, or \code{None} if no |
| window is currently active. (This can be emulated by monitoring |
| WE_ACTIVATE and WE_DEACTIVATE events.) |
| \end{funcdesc} |
| |
| \begin{funcdesc}{listfontnames}{pattern} |
| Return the list of font names in the system that match the pattern (a |
| string). The pattern should normally be \code{'*'}; returns all |
| available fonts. If the underlying window system is X11, other |
| patterns follow the standard X11 font selection syntax (as used e.g. |
| in resource definitions), i.e. the wildcard character \code{'*'} |
| matches any sequence of characters (including none) and \code{'?'} |
| matches any single character. |
| On the Macintosh this function currently returns an empty list. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{setdefscrollbars}{hflag, vflag} |
| Set the flags controlling whether subsequently opened windows will |
| have horizontal and/or vertical scroll bars. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{setdefwinpos}{h, v} |
| Set the default window position for windows opened subsequently. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{setdefwinsize}{width, height} |
| Set the default window size for windows opened subsequently. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getdefscrollbars}{} |
| Return the flags controlling whether subsequently opened windows will |
| have horizontal and/or vertical scroll bars. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getdefwinpos}{} |
| Return the default window position for windows opened subsequently. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getdefwinsize}{} |
| Return the default window size for windows opened subsequently. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getscrsize}{} |
| Return the screen size in pixels. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getscrmm}{} |
| Return the screen size in millimeters. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{fetchcolor}{colorname} |
| Return the pixel value corresponding to the given color name. |
| Return the default foreground color for unknown color names. |
| Hint: the following code tests whether you are on a machine that |
| supports more than two colors: |
| \begin{verbatim} |
| if stdwin.fetchcolor('black') <> \ |
| stdwin.fetchcolor('red') <> \ |
| stdwin.fetchcolor('white'): |
| print 'color machine' |
| else: |
| print 'monochrome machine' |
| \end{verbatim} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{setfgcolor}{pixel} |
| Set the default foreground color. |
| This will become the default foreground color of windows opened |
| subsequently, including dialogs. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{setbgcolor}{pixel} |
| Set the default background color. |
| This will become the default background color of windows opened |
| subsequently, including dialogs. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getfgcolor}{} |
| Return the pixel value of the current default foreground color. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getbgcolor}{} |
| Return the pixel value of the current default background color. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{setfont}{fontname} |
| Set the current default font. |
| This will become the default font for windows opened subsequently, |
| and is also used by the text measuring functions \function{textwidth()}, |
| \function{textbreak()}, \function{lineheight()} and |
| \function{baseline()} below. This accepts two more optional |
| parameters, size and style: Size is the font size (in `points'). |
| Style is a single character specifying the style, as follows: |
| \code{'b'} = bold, |
| \code{'i'} = italic, |
| \code{'o'} = bold + italic, |
| \code{'u'} = underline; |
| default style is roman. |
| Size and style are ignored under X11 but used on the Macintosh. |
| (Sorry for all this complexity --- a more uniform interface is being designed.) |
| \end{funcdesc} |
| |
| \begin{funcdesc}{menucreate}{title} |
| Create a menu object referring to a global menu (a menu that appears in |
| all windows). |
| Methods of menu objects are described below. |
| Note: normally, menus are created locally; see the window method |
| \method{menucreate()} below. |
| \strong{Warning:} the menu only appears in a window as long as the object |
| returned by this call exists. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{newbitmap}{width, height} |
| Create a new bitmap object of the given dimensions. |
| Methods of bitmap objects are described below. |
| Not available on the Macintosh. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{fleep}{} |
| Cause a beep or bell (or perhaps a `visual bell' or flash, hence the |
| name). |
| \end{funcdesc} |
| |
| \begin{funcdesc}{message}{string} |
| Display a dialog box containing the string. |
| The user must click OK before the function returns. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{askync}{prompt, default} |
| Display a dialog that prompts the user to answer a question with yes or |
| no. Return 0 for no, 1 for yes. If the user hits the Return key, the |
| default (which must be 0 or 1) is returned. If the user cancels the |
| dialog, \exception{KeyboardInterrupt} is raised. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{askstr}{prompt, default} |
| Display a dialog that prompts the user for a string. |
| If the user hits the Return key, the default string is returned. |
| If the user cancels the dialog, \exception{KeyboardInterrupt} is |
| raised. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{askfile}{prompt, default, new} |
| Ask the user to specify a filename. If \var{new} is zero it must be |
| an existing file; otherwise, it must be a new file. If the user |
| cancels the dialog, \exception{KeyboardInterrupt} is raised. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{setcutbuffer}{i, string} |
| Store the string in the system's cut buffer number \var{i}, where it |
| can be found (for pasting) by other applications. On X11, there are 8 |
| cut buffers (numbered 0..7). Cut buffer number 0 is the `clipboard' |
| on the Macintosh. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getcutbuffer}{i} |
| Return the contents of the system's cut buffer number \var{i}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{rotatecutbuffers}{n} |
| On X11, rotate the 8 cut buffers by \var{n}. Ignored on the |
| Macintosh. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getselection}{i} |
| Return X11 selection number \var{i.} Selections are not cut buffers. |
| Selection numbers are defined in module \refmodule{stdwinevents}. |
| Selection \constant{WS_PRIMARY} is the \dfn{primary} selection (used |
| by \program{xterm}, for instance); selection \constant{WS_SECONDARY} |
| is the \dfn{secondary} selection; selection \constant{WS_CLIPBOARD} is |
| the \dfn{clipboard} selection (used by \program{xclipboard}). On the |
| Macintosh, this always returns an empty string. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{resetselection}{i} |
| Reset selection number \var{i}, if this process owns it. (See window |
| method \method{setselection()}). |
| \end{funcdesc} |
| |
| \begin{funcdesc}{baseline}{} |
| Return the baseline of the current font (defined by STDWIN as the |
| vertical distance between the baseline and the top of the |
| characters). |
| \end{funcdesc} |
| |
| \begin{funcdesc}{lineheight}{} |
| Return the total line height of the current font. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{textbreak}{str, width} |
| Return the number of characters of the string that fit into a space of |
| \var{width} |
| bits wide when drawn in the curent font. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{textwidth}{str} |
| Return the width in bits of the string when drawn in the current font. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{connectionnumber}{} |
| \funcline{fileno}{} |
| (X11 under \UNIX{} only) Return the ``connection number'' used by the |
| underlying X11 implementation. (This is normally the file number of |
| the socket.) Both functions return the same value; |
| \method{connectionnumber()} is named after the corresponding function in |
| X11 and STDWIN, while \method{fileno()} makes it possible to use the |
| \module{stdwin} module as a ``file'' object parameter to |
| \function{select.select()}. Note that if \constant{select()} implies that |
| input is possible on \module{stdwin}, this does not guarantee that an |
| event is ready --- it may be some internal communication going on |
| between the X server and the client library. Thus, you should call |
| \function{stdwin.pollevent()} until it returns \code{None} to check for |
| events if you don't want your program to block. Because of internal |
| buffering in X11, it is also possible that \function{stdwin.pollevent()} |
| returns an event while \function{select()} does not find \module{stdwin} to |
| be ready, so you should read any pending events with |
| \function{stdwin.pollevent()} until it returns \code{None} before entering |
| a blocking \function{select()} call. |
| \withsubitem{(in module select)}{\ttindex{select()}} |
| \end{funcdesc} |
| |
| \subsection{Window Objects} |
| \nodename{STDWIN Window Objects} |
| |
| Window objects are created by \function{stdwin.open()}. They are closed |
| by their \method{close()} method or when they are garbage-collected. |
| Window objects have the following methods: |
| |
| \begin{methoddesc}[window]{begindrawing}{} |
| Return a drawing object, whose methods (described below) allow drawing |
| in the window. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[window]{change}{rect} |
| Invalidate the given rectangle; this may cause a draw event. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[window]{gettitle}{} |
| Returns the window's title string. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[window]{getdocsize}{} |
| \begin{sloppypar} |
| Return a pair of integers giving the size of the document as set by |
| \method{setdocsize()}. |
| \end{sloppypar} |
| \end{methoddesc} |
| |
| \begin{methoddesc}[window]{getorigin}{} |
| Return a pair of integers giving the origin of the window with respect |
| to the document. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[window]{gettitle}{} |
| Return the window's title string. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[window]{getwinsize}{} |
| Return a pair of integers giving the size of the window. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[window]{getwinpos}{} |
| Return a pair of integers giving the position of the window's upper |
| left corner (relative to the upper left corner of the screen). |
| \end{methoddesc} |
| |
| \begin{methoddesc}[window]{menucreate}{title} |
| Create a menu object referring to a local menu (a menu that appears |
| only in this window). |
| Methods of menu objects are described below. |
| \strong{Warning:} the menu only appears as long as the object |
| returned by this call exists. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[window]{scroll}{rect, point} |
| Scroll the given rectangle by the vector given by the point. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[window]{setdocsize}{point} |
| Set the size of the drawing document. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[window]{setorigin}{point} |
| Move the origin of the window (its upper left corner) |
| to the given point in the document. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[window]{setselection}{i, str} |
| Attempt to set X11 selection number \var{i} to the string \var{str}. |
| (See \module{stdwin} function \function{getselection()} for the |
| meaning of \var{i}.) Return true if it succeeds. |
| If succeeds, the window ``owns'' the selection until |
| (a) another application takes ownership of the selection; or |
| (b) the window is deleted; or |
| (c) the application clears ownership by calling |
| \function{stdwin.resetselection(\var{i})}. When another application |
| takes ownership of the selection, a \constant{WE_LOST_SEL} event is |
| received for no particular window and with the selection number as |
| detail. Ignored on the Macintosh. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[window]{settimer}{dsecs} |
| Schedule a timer event for the window in \code{\var{dsecs}/10} |
| seconds. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[window]{settitle}{title} |
| Set the window's title string. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[window]{setwincursor}{name} |
| \begin{sloppypar} |
| Set the window cursor to a cursor of the given name. It raises |
| \exception{RuntimeError} if no cursor of the given name exists. |
| Suitable names include |
| \code{'ibeam'}, |
| \code{'arrow'}, |
| \code{'cross'}, |
| \code{'watch'} |
| and |
| \code{'plus'}. |
| On X11, there are many more (see \code{<X11/cursorfont.h>}). |
| \end{sloppypar} |
| \end{methoddesc} |
| |
| \begin{methoddesc}[window]{setwinpos}{h, v} |
| Set the the position of the window's upper left corner (relative to |
| the upper left corner of the screen). |
| \end{methoddesc} |
| |
| \begin{methoddesc}[window]{setwinsize}{width, height} |
| Set the window's size. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[window]{show}{rect} |
| Try to ensure that the given rectangle of the document is visible in |
| the window. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[window]{textcreate}{rect} |
| Create a text-edit object in the document at the given rectangle. |
| Methods of text-edit objects are described below. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[window]{setactive}{} |
| Attempt to make this window the active window. If successful, this |
| will generate a WE_ACTIVATE event (and a WE_DEACTIVATE event in case |
| another window in this application became inactive). |
| \end{methoddesc} |
| |
| \begin{methoddesc}[window]{close}{} |
| Discard the window object. It should not be used again. |
| \end{methoddesc} |
| |
| \subsection{Drawing Objects} |
| |
| Drawing objects are created exclusively by the window method |
| \method{begindrawing()}. Only one drawing object can exist at any |
| given time; the drawing object must be deleted to finish drawing. No |
| drawing object may exist when \function{stdwin.getevent()} is called. |
| Drawing objects have the following methods: |
| |
| \begin{methoddesc}[drawing]{box}{rect} |
| Draw a box just inside a rectangle. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[drawing]{circle}{center, radius} |
| Draw a circle with given center point and radius. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[drawing]{elarc}{center, (rh, rv), (a1, a2)} |
| Draw an elliptical arc with given center point. |
| \code{(\var{rh}, \var{rv})} |
| gives the half sizes of the horizontal and vertical radii. |
| \code{(\var{a1}, \var{a2})} |
| gives the angles (in degrees) of the begin and end points. |
| 0 degrees is at 3 o'clock, 90 degrees is at 12 o'clock. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[drawing]{erase}{rect} |
| Erase a rectangle. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[drawing]{fillcircle}{center, radius} |
| Draw a filled circle with given center point and radius. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[drawing]{fillelarc}{center, (rh, rv), (a1, a2)} |
| Draw a filled elliptical arc; arguments as for \method{elarc()}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[drawing]{fillpoly}{points} |
| Draw a filled polygon given by a list (or tuple) of points. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[drawing]{invert}{rect} |
| Invert a rectangle. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[drawing]{line}{p1, p2} |
| Draw a line from point |
| \var{p1} |
| to |
| \var{p2}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[drawing]{paint}{rect} |
| Fill a rectangle. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[drawing]{poly}{points} |
| Draw the lines connecting the given list (or tuple) of points. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[drawing]{shade}{rect, percent} |
| Fill a rectangle with a shading pattern that is about |
| \var{percent} |
| percent filled. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[drawing]{text}{p, str} |
| Draw a string starting at point p (the point specifies the |
| top left coordinate of the string). |
| \end{methoddesc} |
| |
| \begin{methoddesc}[drawing]{xorcircle}{center, radius} |
| \funcline{xorelarc}{center, (rh, rv), (a1, a2)} |
| \funcline{xorline}{p1, p2} |
| \funcline{xorpoly}{points} |
| Draw a circle, an elliptical arc, a line or a polygon, respectively, |
| in XOR mode. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[drawing]{setfgcolor}{} |
| \funcline{setbgcolor}{} |
| \funcline{getfgcolor}{} |
| \funcline{getbgcolor}{} |
| These functions are similar to the corresponding functions described |
| above for the \module{stdwin} |
| module, but affect or return the colors currently used for drawing |
| instead of the global default colors. |
| When a drawing object is created, its colors are set to the window's |
| default colors, which are in turn initialized from the global default |
| colors when the window is created. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[drawing]{setfont}{} |
| \funcline{baseline}{} |
| \funcline{lineheight}{} |
| \funcline{textbreak}{} |
| \funcline{textwidth}{} |
| These functions are similar to the corresponding functions described |
| above for the \module{stdwin} |
| module, but affect or use the current drawing font instead of |
| the global default font. |
| When a drawing object is created, its font is set to the window's |
| default font, which is in turn initialized from the global default |
| font when the window is created. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[drawing]{bitmap}{point, bitmap, mask} |
| Draw the \var{bitmap} with its top left corner at \var{point}. |
| If the optional \var{mask} argument is present, it should be either |
| the same object as \var{bitmap}, to draw only those bits that are set |
| in the bitmap, in the foreground color, or \code{None}, to draw all |
| bits (ones are drawn in the foreground color, zeros in the background |
| color). |
| Not available on the Macintosh. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[drawing]{cliprect}{rect} |
| Set the ``clipping region'' to a rectangle. |
| The clipping region limits the effect of all drawing operations, until |
| it is changed again or until the drawing object is closed. When a |
| drawing object is created the clipping region is set to the entire |
| window. When an object to be drawn falls partly outside the clipping |
| region, the set of pixels drawn is the intersection of the clipping |
| region and the set of pixels that would be drawn by the same operation |
| in the absence of a clipping region. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[drawing]{noclip}{} |
| Reset the clipping region to the entire window. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[drawing]{close}{} |
| \funcline{enddrawing}{} |
| Discard the drawing object. It should not be used again. |
| \end{methoddesc} |
| |
| \subsection{Menu Objects} |
| |
| A menu object represents a menu. |
| The menu is destroyed when the menu object is deleted. |
| The following methods are defined: |
| |
| |
| \begin{methoddesc}[menu]{additem}{text, shortcut} |
| Add a menu item with given text. |
| The shortcut must be a string of length 1, or omitted (to specify no |
| shortcut). |
| \end{methoddesc} |
| |
| \begin{methoddesc}[menu]{setitem}{i, text} |
| Set the text of item number \var{i}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[menu]{enable}{i, flag} |
| Enable or disables item \var{i}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[menu]{check}{i, flag} |
| Set or clear the \dfn{check mark} for item \var{i}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[menu]{close}{} |
| Discard the menu object. It should not be used again. |
| \end{methoddesc} |
| |
| \subsection{Bitmap Objects} |
| |
| A bitmap represents a rectangular array of bits. |
| The top left bit has coordinate (0, 0). |
| A bitmap can be drawn with the \method{bitmap()} method of a drawing object. |
| Bitmaps are currently not available on the Macintosh. |
| |
| The following methods are defined: |
| |
| |
| \begin{methoddesc}[bitmap]{getsize}{} |
| Return a tuple representing the width and height of the bitmap. |
| (This returns the values that have been passed to the |
| \function{newbitmap()} function.) |
| \end{methoddesc} |
| |
| \begin{methoddesc}[bitmap]{setbit}{point, bit} |
| Set the value of the bit indicated by \var{point} to \var{bit}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[bitmap]{getbit}{point} |
| Return the value of the bit indicated by \var{point}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[bitmap]{close}{} |
| Discard the bitmap object. It should not be used again. |
| \end{methoddesc} |
| |
| \subsection{Text-edit Objects} |
| |
| A text-edit object represents a text-edit block. |
| For semantics, see the STDWIN documentation for \C{} programmers. |
| The following methods exist: |
| |
| |
| \begin{methoddesc}[text-edit]{arrow}{code} |
| Pass an arrow event to the text-edit block. |
| The \var{code} must be one of \constant{WC_LEFT}, \constant{WC_RIGHT}, |
| \constant{WC_UP} or \constant{WC_DOWN} (see module |
| \refmodule{stdwinevents}). |
| \end{methoddesc} |
| |
| \begin{methoddesc}[text-edit]{draw}{rect} |
| Pass a draw event to the text-edit block. |
| The rectangle specifies the redraw area. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[text-edit]{event}{type, window, detail} |
| Pass an event gotten from |
| \function{stdwin.getevent()} |
| to the text-edit block. |
| Return true if the event was handled. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[text-edit]{getfocus}{} |
| Return 2 integers representing the start and end positions of the |
| focus, usable as slice indices on the string returned by |
| \method{gettext()}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[text-edit]{getfocustext}{} |
| Return the text in the focus. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[text-edit]{getrect}{} |
| Return a rectangle giving the actual position of the text-edit block. |
| (The bottom coordinate may differ from the initial position because |
| the block automatically shrinks or grows to fit.) |
| \end{methoddesc} |
| |
| \begin{methoddesc}[text-edit]{gettext}{} |
| Return the entire text buffer. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[text-edit]{move}{rect} |
| Specify a new position for the text-edit block in the document. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[text-edit]{replace}{str} |
| Replace the text in the focus by the given string. |
| The new focus is an insert point at the end of the string. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[text-edit]{setfocus}{i, j} |
| Specify the new focus. |
| Out-of-bounds values are silently clipped. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[text-edit]{settext}{str} |
| Replace the entire text buffer by the given string and set the focus |
| to \code{(0, 0)}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[text-edit]{setview}{rect} |
| Set the view rectangle to \var{rect}. If \var{rect} is \code{None}, |
| viewing mode is reset. In viewing mode, all output from the text-edit |
| object is clipped to the viewing rectangle. This may be useful to |
| implement your own scrolling text subwindow. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[text-edit]{close}{} |
| Discard the text-edit object. It should not be used again. |
| \end{methoddesc} |
| |
| \subsection{Example} |
| \nodename{STDWIN Example} |
| |
| Here is a minimal example of using STDWIN in Python. |
| It creates a window and draws the string ``Hello world'' in the top |
| left corner of the window. |
| The window will be correctly redrawn when covered and re-exposed. |
| The program quits when the close icon or menu item is requested. |
| |
| \begin{verbatim} |
| import stdwin |
| from stdwinevents import * |
| |
| def main(): |
| mywin = stdwin.open('Hello') |
| # |
| while 1: |
| (type, win, detail) = stdwin.getevent() |
| if type == WE_DRAW: |
| draw = win.begindrawing() |
| draw.text((0, 0), 'Hello, world') |
| del draw |
| elif type == WE_CLOSE: |
| break |
| |
| main() |
| \end{verbatim} |
| |
| |
| \section{\module{stdwinevents} --- |
| Constants for use with \module{stdwin}} |
| |
| \declaremodule{standard}{stdwinevents} |
| \modulesynopsis{Constant definitions for use with \module{stdwin}} |
| |
| |
| This module defines constants used by STDWIN for event types |
| (\constant{WE_ACTIVATE} etc.), command codes (\constant{WC_LEFT} etc.) |
| and selection types (\constant{WS_PRIMARY} etc.). |
| Read the file for details. |
| Suggested usage is |
| |
| \begin{verbatim} |
| >>> from stdwinevents import * |
| >>> |
| \end{verbatim} |
| |
| |
| \section{\module{rect} --- |
| Functions for use with \module{stdwin}} |
| |
| \declaremodule{standard}{rect} |
| \modulesynopsis{Geometry-related utility function for use with |
| \module{stdwin}.} |
| |
| |
| This module contains useful operations on rectangles. |
| A rectangle is defined as in module \refmodule{stdwin}: |
| a pair of points, where a point is a pair of integers. |
| For example, the rectangle |
| |
| \begin{verbatim} |
| (10, 20), (90, 80) |
| \end{verbatim} |
| |
| is a rectangle whose left, top, right and bottom edges are 10, 20, 90 |
| and 80, respectively. Note that the positive vertical axis points |
| down (as in \refmodule{stdwin}). |
| |
| The module defines the following objects: |
| |
| \begin{excdesc}{error} |
| The exception raised by functions in this module when they detect an |
| error. The exception argument is a string describing the problem in |
| more detail. |
| \end{excdesc} |
| |
| \begin{datadesc}{empty} |
| The rectangle returned when some operations return an empty result. |
| This makes it possible to quickly check whether a result is empty: |
| |
| \begin{verbatim} |
| >>> import rect |
| >>> r1 = (10, 20), (90, 80) |
| >>> r2 = (0, 0), (10, 20) |
| >>> r3 = rect.intersect([r1, r2]) |
| >>> if r3 is rect.empty: print 'Empty intersection' |
| Empty intersection |
| >>> |
| \end{verbatim} |
| \end{datadesc} |
| |
| \begin{funcdesc}{is_empty}{r} |
| Returns true if the given rectangle is empty. |
| A rectangle |
| \code{(\var{left}, \var{top}), (\var{right}, \var{bottom})} |
| is empty if |
| \begin{math}\var{left} \geq \var{right}\end{math} or |
| \begin{math}\var{top} \geq \var{bottom}\end{math}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{intersect}{list} |
| Returns the intersection of all rectangles in the list argument. |
| It may also be called with a tuple argument. Raises |
| \exception{rect.error} if the list is empty. Returns |
| \constant{rect.empty} if the intersection of the rectangles is empty. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{union}{list} |
| Returns the smallest rectangle that contains all non-empty rectangles in |
| the list argument. It may also be called with a tuple argument or |
| with two or more rectangles as arguments. Returns |
| \constant{rect.empty} if the list is empty or all its rectangles are |
| empty. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{pointinrect}{point, rect} |
| Returns true if the point is inside the rectangle. By definition, a |
| point \code{(\var{h}, \var{v})} is inside a rectangle |
| \code{(\var{left}, \var{top}), (\var{right}, \var{bottom})} if |
| \begin{math}\var{left} \leq \var{h} < \var{right}\end{math} and |
| \begin{math}\var{top} \leq \var{v} < \var{bottom}\end{math}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{inset}{rect, (dh, dv)} |
| Returns a rectangle that lies inside the \var{rect} argument by |
| \var{dh} pixels horizontally and \var{dv} pixels vertically. If |
| \var{dh} or \var{dv} is negative, the result lies outside \var{rect}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{rect2geom}{rect} |
| Converts a rectangle to geometry representation: |
| \code{(\var{left}, \var{top}), (\var{width}, \var{height})}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{geom2rect}{geom} |
| Converts a rectangle given in geometry representation back to the |
| standard rectangle representation |
| \code{(\var{left}, \var{top}), (\var{right}, \var{bottom})}. |
| \end{funcdesc} |