diff options
Diffstat (limited to 'Doc/libstdwin.tex')
| -rw-r--r-- | Doc/libstdwin.tex | 920 |
1 files changed, 0 insertions, 920 deletions
diff --git a/Doc/libstdwin.tex b/Doc/libstdwin.tex deleted file mode 100644 index 146457a..0000000 --- a/Doc/libstdwin.tex +++ /dev/null @@ -1,920 +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. - -\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{Built-in Module \module{stdwin}} -\label{module-stdwin} -\bimodindex{stdwin} - -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 \code{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 \code{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 -\code{stdwinevent}. -\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 \code{textwidth}, -\code{textbreak}, \code{lineheight} and \code{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 -\code{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, the -\code{KeyboardInterrupt} -exception 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, the -\code{KeyboardInterrupt} -exception 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, the -\code{KeyboardInterrupt} -exception 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 -\code{stdwinevents}. -Selection \code{WS_PRIMARY} is the -\dfn{primary} -selection (used by -xterm, -for instance); -selection \code{WS_SECONDARY} is the -\dfn{secondary} -selection; selection \code{WS_CLIPBOARD} is the -\dfn{clipboard} -selection (used by -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 -\code{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; -\code{connectionnumber()} is named after the corresponding function in -X11 and STDWIN, while \code{fileno()} makes it possible to use the -\code{stdwin} module as a ``file'' object parameter to -\code{select.select()}. Note that if \code{select()} implies that -input is possible on \code{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 -\code{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 \code{stdwin.pollevent()} -returns an event while \code{select()} does not find \code{stdwin} to -be ready, so you should read any pending events with -\code{stdwin.pollevent()} until it returns \code{None} before entering -a blocking \code{select()} call. -\ttindex{select} -\end{funcdesc} - -\subsection{Window Objects} -\nodename{STDWIN Window Objects} - -Window objects are created by \code{stdwin.open()}. They are closed -by their \code{close()} method or when they are garbage-collected. -Window objects have the following methods: - -\setindexsubitem{(window method)} - -\begin{funcdesc}{begindrawing}{} -Return a drawing object, whose methods (described below) allow drawing -in the window. -\end{funcdesc} - -\begin{funcdesc}{change}{rect} -Invalidate the given rectangle; this may cause a draw event. -\end{funcdesc} - -\begin{funcdesc}{gettitle}{} -Returns the window's title string. -\end{funcdesc} - -\begin{funcdesc}{getdocsize}{} -\begin{sloppypar} -Return a pair of integers giving the size of the document as set by -\code{setdocsize()}. -\end{sloppypar} -\end{funcdesc} - -\begin{funcdesc}{getorigin}{} -Return a pair of integers giving the origin of the window with respect -to the document. -\end{funcdesc} - -\begin{funcdesc}{gettitle}{} -Return the window's title string. -\end{funcdesc} - -\begin{funcdesc}{getwinsize}{} -Return a pair of integers giving the size of the window. -\end{funcdesc} - -\begin{funcdesc}{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{funcdesc} - -\begin{funcdesc}{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{funcdesc} - -\begin{funcdesc}{scroll}{rect, point} -Scroll the given rectangle by the vector given by the point. -\end{funcdesc} - -\begin{funcdesc}{setdocsize}{point} -Set the size of the drawing document. -\end{funcdesc} - -\begin{funcdesc}{setorigin}{point} -Move the origin of the window (its upper left corner) -to the given point in the document. -\end{funcdesc} - -\begin{funcdesc}{setselection}{i, str} -Attempt to set X11 selection number -\var{i} -to the string -\var{str}. -(See stdwin method -\code{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 -\code{stdwin.resetselection(\var{i})}. -When another application takes ownership of the selection, a -\code{WE_LOST_SEL} -event is received for no particular window and with the selection number -as detail. -Ignored on the Macintosh. -\end{funcdesc} - -\begin{funcdesc}{settimer}{dsecs} -Schedule a timer event for the window in -\code{\var{dsecs}/10} -seconds. -\end{funcdesc} - -\begin{funcdesc}{settitle}{title} -Set the window's title string. -\end{funcdesc} - -\begin{funcdesc}{setwincursor}{name} -\begin{sloppypar} -Set the window cursor to a cursor of the given name. -It raises the -\code{RuntimeError} -exception 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 -\file{<X11/cursorfont.h>}). -\end{sloppypar} -\end{funcdesc} - -\begin{funcdesc}{setwinpos}{h, v} -Set the the position of the window's upper left corner (relative to -the upper left corner of the screen). -\end{funcdesc} - -\begin{funcdesc}{setwinsize}{width, height} -Set the window's size. -\end{funcdesc} - -\begin{funcdesc}{show}{rect} -Try to ensure that the given rectangle of the document is visible in -the window. -\end{funcdesc} - -\begin{funcdesc}{textcreate}{rect} -Create a text-edit object in the document at the given rectangle. -Methods of text-edit objects are described below. -\end{funcdesc} - -\begin{funcdesc}{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{funcdesc} - -\begin{funcdesc}{close}{} -Discard the window object. It should not be used again. -\end{funcdesc} - -\subsection{Drawing Objects} - -Drawing objects are created exclusively by the window method -\code{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 -\code{stdwin.getevent()} -is called. -Drawing objects have the following methods: - -\setindexsubitem{(drawing method)} - -\begin{funcdesc}{box}{rect} -Draw a box just inside a rectangle. -\end{funcdesc} - -\begin{funcdesc}{circle}{center, radius} -Draw a circle with given center point and radius. -\end{funcdesc} - -\begin{funcdesc}{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{funcdesc} - -\begin{funcdesc}{erase}{rect} -Erase a rectangle. -\end{funcdesc} - -\begin{funcdesc}{fillcircle}{center, radius} -Draw a filled circle with given center point and radius. -\end{funcdesc} - -\begin{funcdesc}{fillelarc}{center, \(rh, rv\), \(a1, a2\)} -Draw a filled elliptical arc; arguments as for \code{elarc}. -\end{funcdesc} - -\begin{funcdesc}{fillpoly}{points} -Draw a filled polygon given by a list (or tuple) of points. -\end{funcdesc} - -\begin{funcdesc}{invert}{rect} -Invert a rectangle. -\end{funcdesc} - -\begin{funcdesc}{line}{p1, p2} -Draw a line from point -\var{p1} -to -\var{p2}. -\end{funcdesc} - -\begin{funcdesc}{paint}{rect} -Fill a rectangle. -\end{funcdesc} - -\begin{funcdesc}{poly}{points} -Draw the lines connecting the given list (or tuple) of points. -\end{funcdesc} - -\begin{funcdesc}{shade}{rect, percent} -Fill a rectangle with a shading pattern that is about -\var{percent} -percent filled. -\end{funcdesc} - -\begin{funcdesc}{text}{p, str} -Draw a string starting at point p (the point specifies the -top left coordinate of the string). -\end{funcdesc} - -\begin{funcdesc}{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{funcdesc} - -\begin{funcdesc}{setfgcolor}{} -\funcline{setbgcolor}{} -\funcline{getfgcolor}{} -\funcline{getbgcolor}{} -These functions are similar to the corresponding functions described -above for the -\code{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{funcdesc} - -\begin{funcdesc}{setfont}{} -\funcline{baseline}{} -\funcline{lineheight}{} -\funcline{textbreak}{} -\funcline{textwidth}{} -These functions are similar to the corresponding functions described -above for the -\code{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{funcdesc} - -\begin{funcdesc}{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{funcdesc} - -\begin{funcdesc}{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{funcdesc} - -\begin{funcdesc}{noclip}{} -Reset the clipping region to the entire window. -\end{funcdesc} - -\begin{funcdesc}{close}{} -\funcline{enddrawing}{} -Discard the drawing object. It should not be used again. -\end{funcdesc} - -\subsection{Menu Objects} - -A menu object represents a menu. -The menu is destroyed when the menu object is deleted. -The following methods are defined: - -\setindexsubitem{(menu method)} - -\begin{funcdesc}{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{funcdesc} - -\begin{funcdesc}{setitem}{i, text} -Set the text of item number -\var{i}. -\end{funcdesc} - -\begin{funcdesc}{enable}{i, flag} -Enable or disables item -\var{i}. -\end{funcdesc} - -\begin{funcdesc}{check}{i, flag} -Set or clear the -\dfn{check mark} -for item -\var{i}. -\end{funcdesc} - -\begin{funcdesc}{close}{} -Discard the menu object. It should not be used again. -\end{funcdesc} - -\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 \code{bitmap} method of a drawing object. -Bitmaps are currently not available on the Macintosh. - -The following methods are defined: - -\setindexsubitem{(bitmap method)} - -\begin{funcdesc}{getsize}{} -Return a tuple representing the width and height of the bitmap. -(This returns the values that have been passed to the \code{newbitmap} -function.) -\end{funcdesc} - -\begin{funcdesc}{setbit}{point, bit} -Set the value of the bit indicated by \var{point} to \var{bit}. -\end{funcdesc} - -\begin{funcdesc}{getbit}{point} -Return the value of the bit indicated by \var{point}. -\end{funcdesc} - -\begin{funcdesc}{close}{} -Discard the bitmap object. It should not be used again. -\end{funcdesc} - -\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: - -\setindexsubitem{(text-edit method)} - -\begin{funcdesc}{arrow}{code} -Pass an arrow event to the text-edit block. -The -\var{code} -must be one of -\code{WC_LEFT}, -\code{WC_RIGHT}, -\code{WC_UP} -or -\code{WC_DOWN} -(see module -\code{stdwinevents}). -\end{funcdesc} - -\begin{funcdesc}{draw}{rect} -Pass a draw event to the text-edit block. -The rectangle specifies the redraw area. -\end{funcdesc} - -\begin{funcdesc}{event}{type, window, detail} -Pass an event gotten from -\code{stdwin.getevent()} -to the text-edit block. -Return true if the event was handled. -\end{funcdesc} - -\begin{funcdesc}{getfocus}{} -Return 2 integers representing the start and end positions of the -focus, usable as slice indices on the string returned by -\code{gettext()}. -\end{funcdesc} - -\begin{funcdesc}{getfocustext}{} -Return the text in the focus. -\end{funcdesc} - -\begin{funcdesc}{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{funcdesc} - -\begin{funcdesc}{gettext}{} -Return the entire text buffer. -\end{funcdesc} - -\begin{funcdesc}{move}{rect} -Specify a new position for the text-edit block in the document. -\end{funcdesc} - -\begin{funcdesc}{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{funcdesc} - -\begin{funcdesc}{setfocus}{i, j} -Specify the new focus. -Out-of-bounds values are silently clipped. -\end{funcdesc} - -\begin{funcdesc}{settext}{str} -Replace the entire text buffer by the given string and set the focus -to \code{(0, 0)}. -\end{funcdesc} - -\begin{funcdesc}{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{funcdesc} - -\begin{funcdesc}{close}{} -Discard the text-edit object. It should not be used again. -\end{funcdesc} - -\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{Standard Module \module{stdwinevents}} -\label{module-stdwinevents} -\stmodindex{stdwinevents} - -This module defines constants used by STDWIN for event types -(\code{WE_ACTIVATE} etc.), command codes (\code{WC_LEFT} etc.) -and selection types (\code{WS_PRIMARY} etc.). -Read the file for details. -Suggested usage is - -\begin{verbatim} ->>> from stdwinevents import * ->>> -\end{verbatim} -% -\section{Standard Module \module{rect}} -\label{module-rect} -\stmodindex{rect} - -This module contains useful operations on rectangles. -A rectangle is defined as in module -\code{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 -\code{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{latexonly} -\iftexi -%end{latexonly} -\code{\var{left} >= \var{right}} or \code{\var{top} => \var{bottom}}. -%begin{latexonly} -\else -$\var{left} \geq \var{right}$ or $\var{top} \geq \var{bottom}$. -%%JHXXX\emph{left~$\geq$~right} or \emph{top~$\leq$~bottom}. -\fi -%end{latexonly} -\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 -\code{rect.error} -if the list is empty. -Returns -\code{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 -\code{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{latexonly} -\iftexi -%end{latexonly} -\code{\var{left} <= \var{h} < \var{right}} and -\code{\var{top} <= \var{v} < \var{bottom}}. -%begin{latexonly} -\else -$\var{left} \leq \var{h} < \var{right}$ and -$\var{top} \leq \var{v} < \var{bottom}$. -\fi -%end{latexonly} -\end{funcdesc} - -\begin{funcdesc}{inset}{rect, \(dh, dv\)} -Returns a rectangle that lies inside the -\code{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} |