16.1.1 Functions Defined in Module stdwin

 

The following functions are defined in the stdwin module:

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.

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 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 stdwinevent.

pollevent()

Return the next event, if one is immediately available. If no event is available, return ().

getactive()

Return the window that is currently active, or None if no window is currently active. (This can be emulated by monitoring WE_ACTIVATE and WE_DEACTIVATE events.)

listfontnames(pattern)

Return the list of font names in the system that match the pattern (a string). The pattern should normally be '*'; 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 '*' matches any sequence of characters (including none) and '?' matches any single character. On the Macintosh this function currently returns an empty list.

setdefscrollbars(hflag, vflag)

Set the flags controlling whether subsequently opened windows will have horizontal and/or vertical scroll bars.

setdefwinpos(h, v)

Set the default window position for windows opened subsequently.

setdefwinsize(width, height)

Set the default window size for windows opened subsequently.

getdefscrollbars()

Return the flags controlling whether subsequently opened windows will have horizontal and/or vertical scroll bars.

getdefwinpos()

Return the default window position for windows opened subsequently.

getdefwinsize()

Return the default window size for windows opened subsequently.

getscrsize()

Return the screen size in pixels.

getscrmm()

Return the screen size in millimeters.

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:

if stdwin.fetchcolor('black') <> \
          stdwin.fetchcolor('red') <> \
          stdwin.fetchcolor('white'):
    print 'color machine'
else:
    print 'monochrome machine'

setfgcolor(pixel)

Set the default foreground color. This will become the default foreground color of windows opened subsequently, including dialogs.

setbgcolor(pixel)

Set the default background color. This will become the default background color of windows opened subsequently, including dialogs.

getfgcolor()

Return the pixel value of the current default foreground color.

getbgcolor()

Return the pixel value of the current default background color.

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 textwidth, textbreak, lineheight and 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: 'b' = bold, 'i' = italic, 'o' = bold + italic, '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.)

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 menucreate below. Warning: the menu only appears in a window as long as the object returned by this call exists.

newbitmap(width, height)

Create a new bitmap object of the given dimensions. Methods of bitmap objects are described below. Not available on the Macintosh.

fleep()

Cause a beep or bell (or perhaps a `visual bell' or flash, hence the name).

message(string)

Display a dialog box containing the string. The user must click OK before the function returns.

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 KeyboardInterrupt exception is raised.

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 KeyboardInterrupt exception is raised.

askfile(prompt, default, new)

Ask the user to specify a filename. If new is zero it must be an existing file; otherwise, it must be a new file. If the user cancels the dialog, the KeyboardInterrupt exception is raised.

setcutbuffer(i, string)

Store the string in the system's cut buffer number 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.

getcutbuffer(i)

Return the contents of the system's cut buffer number i.

rotatecutbuffers(n)

On X11, rotate the 8 cut buffers by n. Ignored on the Macintosh.

getselection(i)

Return X11 selection number i. Selections are not cut buffers. Selection numbers are defined in module stdwinevents. Selection WS_PRIMARY is the primary selection (used by xterm, for instance); selection WS_SECONDARY is the secondary selection; selection WS_CLIPBOARD is the clipboard selection (used by xclipboard). On the Macintosh, this always returns an empty string.

resetselection(i)

Reset selection number i, if this process owns it. (See window method setselection()).

baseline()

Return the baseline of the current font (defined by STDWIN as the vertical distance between the baseline and the top of the characters).

lineheight()

Return the total line height of the current font.

textbreak(str, width)

Return the number of characters of the string that fit into a space of width bits wide when drawn in the curent font.

textwidth(str)

Return the width in bits of the string when drawn in the current font.

connectionnumber()

,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; connectionnumber() is named after the corresponding function in X11 and STDWIN, while fileno() makes it possible to use the stdwin module as a ``file'' object parameter to select.select(). Note that if select() implies that input is possible on 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 stdwin.pollevent() until it returns 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 stdwin.pollevent() returns an event while select() does not find stdwin to be ready, so you should read any pending events with stdwin.pollevent() until it returns None before entering a blocking select() call.