diff options
Diffstat (limited to 'Doc/lib/libstdwin.tex')
| -rw-r--r-- | Doc/lib/libstdwin.tex | 832 |
1 files changed, 0 insertions, 832 deletions
diff --git a/Doc/lib/libstdwin.tex b/Doc/lib/libstdwin.tex deleted file mode 100644 index f2278e5..0000000 --- a/Doc/lib/libstdwin.tex +++ /dev/null @@ -1,832 +0,0 @@ -\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. - -\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 Graphical User Interface System} - -\declaremodule{builtin}{stdwin} -\modulesynopsis{Older graphical user interface 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 -\programopt{-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 millimetres. -\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. -\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 current 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. -\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 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} |