This is Info file /home/pdm/tmp/Python-1.5.2p1/Doc/mac/python-mac.info, produced by Makeinfo version 1.68 from the input file mac.texi. July 6, 1999 1.5.2  File: python-mac.info, Node: Top, Next: Front Matter, Prev: (dir), Up: (dir) Macintosh Library Modules ************************* * Menu: * Front Matter:: * Module Index:: * Class-Exception-Object Index:: * Function-Method-Variable Index:: * Miscellaneous Index::  File: python-mac.info, Node: Front Matter, Next: Module Index, Prev: Top, Up: Top Front Matter ************ Copyright (C) 1991-1995 by Stichting Mathematisch Centrum, Amsterdam, The Netherlands. All Rights Reserved Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the names of Stichting Mathematisch Centrum or CWI or Corporation for National Research Initiatives or CNRI not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. While CWI is the initial source for this software, a modified version is made available by the Corporation for National Research Initiatives (CNRI) at the Internet address `ftp://ftp.python.org'. STICHTING MATHEMATISCH CENTRUM AND CNRI DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM OR CNRI BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. This library reference manual documents Python's extensions for the Macintosh. It should be used in conjunction with the *Python Library Reference*, which documents the standard library and built-in types. This manual assumes basic knowledge about the Python language. For an informal introduction to Python, see the *Python Tutorial*; the *Python Reference Manual* remains the highest authority on syntactic and semantic questions. Finally, the manual entitled *Extending and Embedding the Python Interpreter* describes how to add new extensions to Python and how to embed it in other applications. * Menu: * Introduction:: * mac:: * macpath:: * ctb:: * macconsole:: * macdnr:: * macfs:: * ic:: * MacOS:: * macostools:: * findertools:: * mactcp:: * macspeech:: * EasyDialogs:: * FrameWork:: * MiniAEFrame::  File: python-mac.info, Node: Introduction, Next: mac, Prev: Front Matter, Up: Front Matter Introduction ============ The modules in this manual are available on the Apple Macintosh only. Aside from the modules described here there are also interfaces to various MacOS toolboxes, which are currently not extensively described. The toolboxes for which modules exist are: `AE' (Apple Events), `Cm' (Component Manager), `Ctl' (Control Manager), `Dlg' (Dialog Manager), `Evt' (Event Manager), `Fm' (Font Manager), `List' (List Manager), `Menu' (Moenu Manager), `Qd' (QuickDraw), `Qt' (QuickTime), `Res' (Resource Manager and Handles), `Scrap' (Scrap Manager), `Snd' (Sound Manager), `TE' (TextEdit), `Waste' (non-Apple `TextEdit' replacement) and `Win' (Window Manager). If applicable the module will define a number of Python objects for the various structures declared by the toolbox, and operations will be implemented as methods of the object. Other operations will be implemented as functions in the module. Not all operations possible in C will also be possible in Python (callbacks are often a problem), and parameters will occasionally be different in Python (input and output buffers, especially). All methods and functions have a `__doc__' string describing their arguments and return values, and for additional description you are referred to *Inside Macintosh* or similar works. The following modules are documented here:  File: python-mac.info, Node: mac, Next: macpath, Prev: Introduction, Up: Front Matter Implementations for the `os' module =================================== Implementations for the `os' module. This module implements the operating system dependent functionality provided by the standard module `os'. It is best accessed through the `os' module. The following functions are available in this module: `chdir()', `close()', `dup()', `fdopen()', `getcwd()', `lseek()', `listdir()', `mkdir()', `open()', `read()', `rename()', `rmdir()', `stat()', `sync()', `unlink()', `write()', as well as the exception `error'. Note that the times returned by `stat()' are floating-point values, like all time values in MacPython. One additional function is available: `xstat(path)' This function returns the same information as `stat()', but with three additional values appended: the size of the resource fork of the file and its 4-character creator and type.  File: python-mac.info, Node: macpath, Next: ctb, Prev: mac, Up: Front Matter MacOS path manipulation functions ================================= MacOS path manipulation functions. This module is the Macintosh implementation of the `os.path' module. It is most portably accessed as `os.path'. Refer to the *Python Library Reference* for documentation of `os.path'. The following functions are available in this module: `normcase()', `normpath()', `isabs()', `join()', `split()', `isdir()', `isfile()', `walk()', `exists()'. For other functions available in `os.path' dummy counterparts are available.  File: python-mac.info, Node: ctb, Next: macconsole, Prev: macpath, Up: Front Matter Interface to the Communications Tool Box ======================================== Interfaces to the Communications Tool Box. Only the Connection Manager is supported. This module provides a partial interface to the Macintosh Communications Toolbox. Currently, only Connection Manager tools are supported. It may not be available in all Mac Python versions. `error' The exception raised on errors. `cmData' `cmCntl' `cmAttn' Flags for the CHANNEL argument of the `Read()' and `Write()' methods. `cmFlagsEOM' End-of-message flag for `Read()' and `Write()'. `choose*' Values returned by `Choose()'. `cmStatus*' Bits in the status as returned by `Status()'. `available()' Return `1' if the Communication Toolbox is available, zero otherwise. `CMNew(name, sizes)' Create a connection object using the connection tool named NAME. SIZES is a 6-tuple given buffer sizes for data in, data out, control in, control out, attention in and attention out. Alternatively, passing `None' for SIZES will result in default buffer sizes. * Menu: * Connection Objects::  File: python-mac.info, Node: Connection Objects, Prev: ctb, Up: ctb Connection Objects ------------------ For all connection methods that take a TIMEOUT argument, a value of `-1' is indefinite, meaning that the command runs to completion. `callback' If this member is set to a value other than `None' it should point to a function accepting a single argument (the connection object). This will make all connection object methods work asynchronously, with the callback routine being called upon completion. *Note:* for reasons beyond my understanding the callback routine is currently never called. You are advised against using asynchronous calls for the time being. `Open(timeout)' Open an outgoing connection, waiting at most TIMEOUT seconds for the connection to be established. `Listen(timeout)' Wait for an incoming connection. Stop waiting after TIMEOUT seconds. This call is only meaningful to some tools. `accept(yesno)' Accept (when YESNO is non-zero) or reject an incoming call after `Listen()' returned. `Close(timeout, now)' Close a connection. When NOW is zero, the close is orderly (i.e. outstanding output is flushed, etc.) with a timeout of TIMEOUT seconds. When NOW is non-zero the close is immediate, discarding output. `Read(len, chan, timeout)' Read LEN bytes, or until TIMEOUT seconds have passed, from the channel CHAN (which is one of `cmData', `cmCntl' or `cmAttn'). Return a 2-tuple: the data read and the end-of-message flag, `cmFlagsEOM'. `Write(buf, chan, timeout, eom)' Write BUF to channel CHAN, aborting after TIMEOUT seconds. When EOM has the value `cmFlagsEOM', an end-of-message indicator will be written after the data (if this concept has a meaning for this communication tool). The method returns the number of bytes written. `Status()' Return connection status as the 2-tuple `(SIZES, FLAGS)'. SIZES is a 6-tuple giving the actual buffer sizes used (see `CMNew()'), FLAGS is a set of bits describing the state of the connection. `GetConfig()' Return the configuration string of the communication tool. These configuration strings are tool-dependent, but usually easily parsed and modified. `SetConfig(str)' Set the configuration string for the tool. The strings are parsed left-to-right, with later values taking precedence. This means individual configuration parameters can be modified by simply appending something like `'baud 4800'' to the end of the string returned by `GetConfig()' and passing that to this method. The method returns the number of characters actually parsed by the tool before it encountered an error (or completed successfully). `Choose()' Present the user with a dialog to choose a communication tool and configure it. If there is an outstanding connection some choices (like selecting a different tool) may cause the connection to be aborted. The return value (one of the `choose*' constants) will indicate this. `Idle()' Give the tool a chance to use the processor. You should call this method regularly. `Abort()' Abort an outstanding asynchronous `Open()' or `Listen()'. `Reset()' Reset a connection. Exact meaning depends on the tool. `Break(length)' Send a break. Whether this means anything, what it means and interpretation of the LENGTH parameter depends on the tool in use.  File: python-mac.info, Node: macconsole, Next: macdnr, Prev: ctb, Up: Front Matter Think C's console package ========================= Think C's console package. This module is available on the Macintosh, provided Python has been built using the Think C compiler. It provides an interface to the Think console package, with which basic text windows can be created. `options' An object allowing you to set various options when creating windows, see below. `C_ECHO' `C_NOECHO' `C_CBREAK' `C_RAW' Options for the `setmode' method. `C_ECHO' and `C_CBREAK' enable character echo, the other two disable it, `C_ECHO' and `C_NOECHO' enable line-oriented input (erase/kill processing, etc). `copen()' Open a new console window. Return a console window object. `fopen(fp)' Return the console window object corresponding with the given file object. FP should be one of `sys.stdin', `sys.stdout' or `sys.stderr'. * Menu: * macconsole options object:: * console window object::  File: python-mac.info, Node: macconsole options object, Next: console window object, Prev: macconsole, Up: macconsole macconsole options object ------------------------- These options are examined when a window is created: `top' `left' The origin of the window. `nrows' `ncols' The size of the window. `txFont' `txSize' `txStyle' The font, fontsize and fontstyle to be used in the window. `title' The title of the window. `pause_atexit' If set non-zero, the window will wait for user action before closing.  File: python-mac.info, Node: console window object, Prev: macconsole options object, Up: macconsole console window object --------------------- `file' The file object corresponding to this console window. If the file is buffered, you should call `FILE.flush()' between `write()' and `read()' calls. `setmode(mode)' Set the input mode of the console to `C_ECHO', etc. `settabs(n)' Set the tabsize to N spaces. `cleos()' Clear to end-of-screen. `cleol()' Clear to end-of-line. `inverse(onoff)' Enable inverse-video mode: characters with the high bit set are displayed in inverse video (this disables the upper half of a non-ASCII character set). `gotoxy(x, y)' Set the cursor to position `(X, Y)'. `hide()' Hide the window, remembering the contents. `show()' Show the window again. `echo2printer()' Copy everything written to the window to the printer as well.  File: python-mac.info, Node: macdnr, Next: macfs, Prev: macconsole, Up: Front Matter Interface to the Macintosh Domain Name Resolver =============================================== Interfaces to the Macintosh Domain Name Resolver. This module provides an interface to the Macintosh Domain Name Resolver. It is usually used in conjunction with the `mactcp' module, to map hostnames to IP addresses. It may not be available in all Mac Python versions. The `macdnr' module defines the following functions: `Open([filename])' Open the domain name resolver extension. If FILENAME is given it should be the pathname of the extension, otherwise a default is used. Normally, this call is not needed since the other calls will open the extension automatically. `Close()' Close the resolver extension. Again, not needed for normal use. `StrToAddr(hostname)' Look up the IP address for HOSTNAME. This call returns a dnr result object of the "address" variation. `AddrToName(addr)' Do a reverse lookup on the 32-bit integer IP-address ADDR. Returns a dnr result object of the "address" variation. `AddrToStr(addr)' Convert the 32-bit integer IP-address ADDR to a dotted-decimal string. Returns the string. `HInfo(hostname)' Query the nameservers for a `HInfo' record for host HOSTNAME. These records contain hardware and software information about the machine in question (if they are available in the first place). Returns a dnr result object of the "hinfo" variety. `MXInfo(domain)' Query the nameservers for a mail exchanger for DOMAIN. This is the hostname of a host willing to accept SMTP mail for the given domain. Returns a dnr result object of the "mx" variety. * Menu: * DNR Result Objects::  File: python-mac.info, Node: DNR Result Objects, Prev: macdnr, Up: macdnr DNR Result Objects ------------------ Since the DNR calls all execute asynchronously you do not get the results back immediately. Instead, you get a dnr result object. You can check this object to see whether the query is complete, and access its attributes to obtain the information when it is. Alternatively, you can also reference the result attributes directly, this will result in an implicit wait for the query to complete. The `rtnCode' and `cname' attributes are always available, the others depend on the type of query (address, hinfo or mx). `wait()' Wait for the query to complete. `isdone()' Return `1' if the query is complete. `rtnCode' The error code returned by the query. `cname' The canonical name of the host that was queried. `ip0' `ip1' `ip2' `ip3' At most four integer IP addresses for this host. Unused entries are zero. Valid only for address queries. `cpuType' `osType' Textual strings giving the machine type an OS name. Valid for "hinfo" queries. `exchange' The name of a mail-exchanger host. Valid for "mx" queries. `preference' The preference of this mx record. Not too useful, since the Macintosh will only return a single mx record. Valid for "mx" queries only. The simplest way to use the module to convert names to dotted-decimal strings, without worrying about idle time, etc: >>> def gethostname(name): ... import macdnr ... dnrr = macdnr.StrToAddr(name) ... return macdnr.AddrToStr(dnrr.ip0)  File: python-mac.info, Node: macfs, Next: ic, Prev: macdnr, Up: Front Matter Various file system services ============================ Support for FSSpec, the Alias Manager, `finder' aliases, and the Standard File package. This module provides access to Macintosh FSSpec handling, the Alias Manager, `finder' aliases and the Standard File package. Whenever a function or method expects a FILE argument, this argument can be one of three things: (1) a full or partial Macintosh pathname, (2) an `FSSpec' object or (3) a 3-tuple `(WDREFNUM, PARID, NAME)' as described in *Inside Macintosh: Files*. A description of aliases and the Standard File package can also be found there. `FSSpec(file)' Create an `FSSpec' object for the specified file. `RawFSSpec(data)' Create an `FSSpec' object given the raw data for the C structure for the `FSSpec' as a string. This is mainly useful if you have obtained an `FSSpec' structure over a network. `RawAlias(data)' Create an `Alias' object given the raw data for the C structure for the alias as a string. This is mainly useful if you have obtained an `FSSpec' structure over a network. `FInfo()' Create a zero-filled `FInfo' object. `ResolveAliasFile(file)' Resolve an alias file. Returns a 3-tuple `(FSSPEC, ISFOLDER, ALIASED)' where FSSPEC is the resulting `FSSpec' object, ISFOLDER is true if FSSPEC points to a folder and ALIASED is true if the file was an alias in the first place (otherwise the `FSSpec' object for the file itself is returned). `StandardGetFile([type, ...])' Present the user with a standard "open input file" dialog. Optionally, you can pass up to four 4-character file types to limit the files the user can choose from. The function returns an `FSSpec' object and a flag indicating that the user completed the dialog without cancelling. `PromptGetFile(prompt[, type, ...])' Similar to `StandardGetFile()' but allows you to specify a prompt. `StandardPutFile(prompt, [default])' Present the user with a standard "open output file" dialog. PROMPT is the prompt string, and the optional DEFAULT argument initializes the output file name. The function returns an `FSSpec' object and a flag indicating that the user completed the dialog without cancelling. `GetDirectory([prompt])' Present the user with a non-standard "select a directory" dialog. PROMPT is the prompt string, and the optional. Return an `FSSpec' object and a success-indicator. `SetFolder([fsspec])' Set the folder that is initially presented to the user when one of the file selection dialogs is presented. FSSPEC should point to a file in the folder, not the folder itself (the file need not exist, though). If no argument is passed the folder will be set to the current directory, i.e. what `os.getcwd()' returns. Note that starting with system 7.5 the user can change Standard File behaviour with the "general controls" controlpanel, thereby making this call inoperative. `FindFolder(where, which, create)' Locates one of the "special" folders that MacOS knows about, such as the trash or the Preferences folder. WHERE is the disk to search, WHICH is the 4-character string specifying which folder to locate. Setting CREATE causes the folder to be created if it does not exist. Returns a `(VREFNUM, DIRID)' tuple. `NewAliasMinimalFromFullPath(pathname)' Return a minimal `alias' object that points to the given file, which must be specified as a full pathname. This is the only way to create an `Alias' pointing to a non-existing file. The constants for WHERE and WHICH can be obtained from the standard module MACFS. `FindApplication(creator)' Locate the application with 4-char creator code CREATOR. The function returns an `FSSpec' object pointing to the application. * Menu: * FSSpec objects:: * Alias Objects:: * FInfo Objects::  File: python-mac.info, Node: FSSpec objects, Next: Alias Objects, Prev: macfs, Up: macfs FSSpec objects -------------- `data' The raw data from the FSSpec object, suitable for passing to other applications, for instance. `as_pathname()' Return the full pathname of the file described by the `FSSpec' object. `as_tuple()' Return the `(WDREFNUM, PARID, NAME)' tuple of the file described by the `FSSpec' object. `NewAlias([file])' Create an Alias object pointing to the file described by this FSSpec. If the optional FILE parameter is present the alias will be relative to that file, otherwise it will be absolute. `NewAliasMinimal()' Create a minimal alias pointing to this file. `GetCreatorType()' Return the 4-character creator and type of the file. `SetCreatorType(creator, type)' Set the 4-character creator and type of the file. `GetFInfo()' Return a `FInfo' object describing the finder info for the file. `SetFInfo(finfo)' Set the finder info for the file to the values given as FINFO (an `FInfo' object). `GetDates()' Return a tuple with three floating point values representing the creation date, modification date and backup date of the file. `SetDates(crdate, moddate, backupdate)' Set the creation, modification and backup date of the file. The values are in the standard floating point format used for times throughout Python.  File: python-mac.info, Node: Alias Objects, Next: FInfo Objects, Prev: FSSpec objects, Up: macfs Alias Objects ------------- `data' The raw data for the Alias record, suitable for storing in a resource or transmitting to other programs. `Resolve([file])' Resolve the alias. If the alias was created as a relative alias you should pass the file relative to which it is. Return the FSSpec for the file pointed to and a flag indicating whether the `Alias' object itself was modified during the search process. If the file does not exist but the path leading up to it does exist a valid fsspec is returned. `GetInfo(num)' An interface to the C routine `GetAliasInfo()'. `Update(file, [file2])' Update the alias to point to the FILE given. If FILE2 is present a relative alias will be created. Note that it is currently not possible to directly manipulate a resource as an `Alias' object. Hence, after calling `Update()' or after `Resolve()' indicates that the alias has changed the Python program is responsible for getting the `data' value from the `Alias' object and modifying the resource.  File: python-mac.info, Node: FInfo Objects, Prev: Alias Objects, Up: macfs FInfo Objects ------------- See *Inside Macintosh: Files* for a complete description of what the various fields mean. `Creator' The 4-character creator code of the file. `Type' The 4-character type code of the file. `Flags' The finder flags for the file as 16-bit integer. The bit values in FLAGS are defined in standard module `MACFS'. `Location' A Point giving the position of the file's icon in its folder. `Fldr' The folder the file is in (as an integer).  File: python-mac.info, Node: ic, Next: MacOS, Prev: macfs, Up: Front Matter Access to Internet Config ========================= Access to Internet Config. This module provides access to Macintosh Internet Config package, which stores preferences for Internet programs such as mail address, default homepage, etc. Also, Internet Config contains an elaborate set of mappings from Macintosh creator/type codes to foreign filename extensions plus information on how to transfer files (binary, ascii, etc). There is a low-level companion module `icglue' which provides the basic Internet Config access functionality. This low-level module is not documented, but the docstrings of the routines document the parameters and the routine names are the same as for the Pascal or C API to Internet Config, so the standard IC programmers' documentation can be used if this module is needed. The `ic' module defines the `error' exception and symbolic names for all error codes Internet Config can produce; see the source for details. `error' Exception raised on errors in the `ic' module. The `ic' module defines the following class and function: `IC([signature[, ic]])' Create an internet config object. The signature is a 4-character creator code of the current application (default `'Pyth'') which may influence some of ICs settings. The optional IC argument is a low-level `icglue.icinstance' created beforehand, this may be useful if you want to get preferences from a different config file, etc. `launchurl(url[, hint])' `parseurl data[, start[, end[, hint]]]' `mapfile file' `maptypecreator type, creator[, filename]' `settypecreator file' These functions are "shortcuts" to the methods of the same name, described below. * Menu: * IC Objects::  File: python-mac.info, Node: IC Objects, Prev: ic, Up: ic IC Objects ---------- `IC' objects have a mapping interface, hence to obtain the mail address you simply get `IC['MailAddress']'. Assignment also works, and changes the option in the configuration file. The module knows about various datatypes, and converts the internal IC representation to a "logical" Python data structure. Running the `ic' module standalone will run a test program that lists all keys and values in your IC database, this will have to server as documentation. If the module does not know how to represent the data it returns an instance of the `ICOpaqueData' type, with the raw data in its `data' attribute. Objects of this type are also acceptable values for assignment. Besides the dictionary interface, `IC' objects have the following methods: `launchurl(url[, hint])' Parse the given URL, lauch the correct application and pass it the URL. The optional HINT can be a scheme name such as `'mailto:'', in which case incomplete URLs are completed with this scheme. If HINT is not provided, incomplete URLs are invalid. `parseurl(data[, start[, end[, hint]]])' Find an URL somewhere in DATA and return start position, end position and the URL. The optional START and END can be used to limit the search, so for instance if a user clicks in a long textfield you can pass the whole textfield and the click-position in START and this routine will return the whole URL in which the user clicked. As above, HINT is an optional scheme used to complete incomplete URLs. `mapfile(file)' Return the mapping entry for the given FILE, which can be passed as either a filename or an `macfs.FSSpec()' result, and which need not exist. The mapping entry is returned as a tuple `(VERSION, TYPE, CREATOR, POSTCREATOR, FLAGS, EXTENSION, APPNAME, POSTAPPNAME, MIMETYPE, ENTRYNAME)', where VERSION is the entry version number, TYPE is the 4-character filetype, CREATOR is the 4-character creator type, POSTCREATOR is the 4-character creator code of an optional application to post-process the file after downloading, FLAGS are various bits specifying whether to transfer in binary or ascii and such, EXTENSION is the filename extension for this file type, APPNAME is the printable name of the application to which this file belongs, POSTAPPNAME is the name of the postprocessing application, MIMETYPE is the MIME type of this file and ENTRYNAME is the name of this entry. `maptypecreator(type, creator[, filename])' Return the mapping entry for files with given 4-character TYPE and CREATOR codes. The optional FILENAME may be specified to further help finding the correct entry (if the creator code is `'????'', for instance). The mapping entry is returned in the same format as for MAPFILE. `settypecreator(file)' Given an existing FILE, specified either as a filename or as an `macfs.FSSpec()' result, set its creator and type correctly based on its extension. The finder is told about the change, so the finder icon will be updated quickly.  File: python-mac.info, Node: MacOS, Next: macostools, Prev: ic, Up: Front Matter Access to MacOS interpreter features ==================================== Access to MacOS specific interpreter features. This module provides access to MacOS specific functionality in the Python interpreter, such as how the interpreter eventloop functions and the like. Use with care. Note the capitalisation of the module name, this is a historical artifact. `Error' This exception is raised on MacOS generated errors, either from functions in this module or from other mac-specific modules like the toolbox interfaces. The arguments are the integer error code (the `OSErr' value) and a textual description of the error code. Symbolic names for all known error codes are defined in the standard module `macerrors'. `SetEventHandler(handler)' In the inner interpreter loop Python will occasionally check for events, unless disabled with `ScheduleParams()'. With this function you can pass a Python event-handler function that will be called if an event is available. The event is passed as parameter and the function should return non-zero if the event has been fully processed, otherwise event processing continues (by passing the event to the console window package, for instance). Call `SetEventHandler()' without a parameter to clear the event handler. Setting an event handler while one is already set is an error. `SchedParams([doint[, evtmask[, besocial[, interval[, bgyield]]]]])' Influence the interpreter inner loop event handling. INTERVAL specifies how often (in seconds, floating point) the interpreter should enter the event processing code. When true, DOINT causes interrupt (command-dot) checking to be done. EVTMASK tells the interpreter to do event processing for events in the mask (redraws, mouseclicks to switch to other applications, etc). The BESOCIAL flag gives other processes a chance to run. They are granted minimal runtime when Python is in the foreground and BGYIELD seconds per INTERVAL when Python runs in the background. All parameters are optional, and default to the current value. The return value of this function is a tuple with the old values of these options. Initial defaults are that all processing is enabled, checking is done every quarter second and the CPU is given up for a quarter second when in the background. `HandleEvent(ev)' Pass the event record EV back to the Python event loop, or possibly to the handler for the `sys.stdout' window (based on the compiler used to build Python). This allows Python programs that do their own event handling to still have some command-period and window-switching capability. If you attempt to call this function from an event handler set through `SetEventHandler()' you will get an exception. `GetErrorString(errno)' Return the textual description of MacOS error code ERRNO. `splash(resid)' This function will put a splash window on-screen, with the contents of the DLOG resource specified by RESID. Calling with a zero argument will remove the splash screen. This function is useful if you want an applet to post a splash screen early in initialization without first having to load numerous extension modules. `DebugStr(message [, object])' Drop to the low-level debugger with message MESSAGE. The optional OBJECT argument is not used, but can easily be inspected from the debugger. Note that you should use this function with extreme care: if no low-level debugger like MacsBug is installed this call will crash your system. It is intended mainly for developers of Python extension modules. `openrf(name [, mode])' Open the resource fork of a file. Arguments are the same as for the built-in function `open()'. The object returned has file-like semantics, but it is not a Python file object, so there may be subtle differences.  File: python-mac.info, Node: macostools, Next: findertools, Prev: MacOS, Up: Front Matter Convenience routines for file manipulation ========================================== Convenience routines for file manipulation. This module contains some convenience routines for file-manipulation on the Macintosh. The `macostools' module defines the following functions: `copy(src, dst[, createpath[, copytimes]])' Copy file SRC to DST. The files can be specified as pathnames or `FSSpec' objects. If CREATEPATH is non-zero DST must be a pathname and the folders leading to the destination are created if necessary. The method copies data and resource fork and some finder information (creator, type, flags) and optionally the creation, modification and backup times (default is to copy them). Custom icons, comments and icon position are not copied. If the source is an alias the original to which the alias points is copied, not the aliasfile. `copytree(src, dst)' Recursively copy a file tree from SRC to DST, creating folders as needed. SRC and DST should be specified as pathnames. `mkalias(src, dst)' Create a finder alias DST pointing to SRC. Both may be specified as pathnames or `FSSpec' objects. `touched(dst)' Tell the finder that some bits of finder-information such as creator or type for file DST has changed. The file can be specified by pathname or fsspec. This call should prod the finder into redrawing the files icon. `BUFSIZ' The buffer size for `copy', default 1 megabyte. Note that the process of creating finder aliases is not specified in the Apple documentation. Hence, aliases created with `mkalias()' could conceivably have incompatible behaviour in some cases.  File: python-mac.info, Node: findertools, Next: mactcp, Prev: macostools, Up: Front Matter The `finder''s Apple Events interface ===================================== Wrappers around the `finder''s Apple Events interface. This module contains routines that give Python programs access to some functionality provided by the finder. They are implemented as wrappers around the AppleEvent interface to the finder. All file and folder parameters can be specified either as full pathnames or as `FSSpec' objects. The `findertools' module defines the following functions: `launch(file)' Tell the finder to launch FILE. What launching means depends on the file: applications are started, folders are opened and documents are opened in the correct application. `Print(file)' Tell the finder to print a file (again specified by full pathname or `FSSpec'). The behaviour is identical to selecting the file and using the print command in the finder. `copy(file, destdir)' Tell the finder to copy a file or folder FILE to folder DESTDIR. The function returns an `Alias' object pointing to the new file. `move(file, destdir)' Tell the finder to move a file or folder FILE to folder DESTDIR. The function returns an `Alias' object pointing to the new file. `sleep()' Tell the finder to put the Macintosh to sleep, if your machine supports it. `restart()' Tell the finder to perform an orderly restart of the machine. `shutdown()' Tell the finder to perform an orderly shutdown of the machine.  File: python-mac.info, Node: mactcp, Next: macspeech, Prev: findertools, Up: Front Matter The MacTCP interfaces ===================== The MacTCP interfaces. This module provides an interface to the Macintosh TCP/IP driver MacTCP. There is an accompanying module, `macdnr', which provides an interface to the name-server (allowing you to translate hostnames to IP addresses), a module `MACTCPconst'which has symbolic names for constants constants used by MacTCP. Since the built-in module `socket' is also available on the Macintosh it is usually easier to use sockets instead of the Macintosh-specific MacTCP API. A complete description of the MacTCP interface can be found in the Apple MacTCP API documentation. `MTU()' Return the Maximum Transmit Unit (the packet size) of the network interface. `IPAddr()' Return the 32-bit integer IP address of the network interface. `NetMask()' Return the 32-bit integer network mask of the interface. `TCPCreate(size)' Create a TCP Stream object. SIZE is the size of the receive buffer, `4096' is suggested by various sources. `UDPCreate(size, port)' Create a UDP Stream object. SIZE is the size of the receive buffer (and, hence, the size of the biggest datagram you can receive on this port). PORT is the UDP port number you want to receive datagrams on, a value of zero will make MacTCP select a free port. * Menu: * TCP Stream Objects:: * TCP Status Objects:: * UDP Stream Objects::  File: python-mac.info, Node: TCP Stream Objects, Next: TCP Status Objects, Prev: mactcp, Up: mactcp TCP Stream Objects ------------------ `asr' When set to a value different than `None' this should refer to a function with two integer parameters: an event code and a detail. This function will be called upon network-generated events such as urgent data arrival. Macintosh documentation calls this the "asynchronous service routine". In addition, it is called with eventcode `MACTCP.PassiveOpenDone' when a `PassiveOpen()' completes. This is a Python addition to the MacTCP semantics. It is safe to do further calls from ASR. `PassiveOpen(port)' Wait for an incoming connection on TCP port PORT (zero makes the system pick a free port). The call returns immediately, and you should use `wait()' to wait for completion. You should not issue any method calls other than `wait()', `isdone()' or `GetSockName()' before the call completes. `wait()' Wait for `PassiveOpen()' to complete. `isdone()' Return `1' if a `PassiveOpen()' has completed. `GetSockName()' Return the TCP address of this side of a connection as a 2-tuple `(HOST, PORT)', both integers. `ActiveOpen(lport, host, rport)' Open an outgoing connection to TCP address `(HOST, RPORT)'. Use local port LPORT (zero makes the system pick a free port). This call blocks until the connection has been established. `Send(buf, push, urgent)' Send data BUF over the connection. PUSH and URGENT are flags as specified by the TCP standard. `Rcv(timeout)' Receive data. The call returns when TIMEOUT seconds have passed or when (according to the MacTCP documentation) "a reasonable amount of data has been received". The return value is a 3-tuple `(DATA, URGENT, MARK)'. If urgent data is outstanding `Rcv' will always return that before looking at any normal data. The first call returning urgent data will have the URGENT flag set, the last will have the MARK flag set. `Close()' Tell MacTCP that no more data will be transmitted on this connection. The call returns when all data has been acknowledged by the receiving side. `Abort()' Forcibly close both sides of a connection, ignoring outstanding data. `Status()' Return a TCP status object for this stream giving the current status (see below).  File: python-mac.info, Node: TCP Status Objects, Next: UDP Stream Objects, Prev: TCP Stream Objects, Up: mactcp TCP Status Objects ------------------ This object has no methods, only some members holding information on the connection. A complete description of all fields in this objects can be found in the Apple documentation. The most interesting ones are: `localHost' `localPort' `remoteHost' `remotePort' The integer IP-addresses and port numbers of both endpoints of the connection. `sendWindow' The current window size. `amtUnackedData' The number of bytes sent but not yet acknowledged. `sendWindow - amtUnackedData' is what you can pass to `Send()' without blocking. `amtUnreadData' The number of bytes received but not yet read (what you can `Recv()' without blocking).  File: python-mac.info, Node: UDP Stream Objects, Prev: TCP Status Objects, Up: mactcp UDP Stream Objects ------------------ Note that, unlike the name suggests, there is nothing stream-like about UDP. `asr' The asynchronous service routine to be called on events such as datagram arrival without outstanding `Read' call. The ASR has a single argument, the event code. `port' A read-only member giving the port number of this UDP Stream. `Read(timeout)' Read a datagram, waiting at most TIMEOUT seconds (-1 is infinite). Return the data. `Write(host, port, buf)' Send BUF as a datagram to IP-address HOST, port PORT.  File: python-mac.info, Node: macspeech, Next: EasyDialogs, Prev: mactcp, Up: Front Matter Interface to the Macintosh Speech Manager ========================================= Interface to the Macintosh Speech Manager. This module provides an interface to the Macintosh Speech Manager, allowing you to let the Macintosh utter phrases. You need a version of the Speech Manager extension (version 1 and 2 have been tested) in your `Extensions' folder for this to work. The module does not provide full access to all features of the Speech Manager yet. It may not be available in all Mac Python versions. `Available()' Test availability of the Speech Manager extension (and, on the PowerPC, the Speech Manager shared library). Return `0' or `1'. `Version()' Return the (integer) version number of the Speech Manager. `SpeakString(str)' Utter the string STR using the default voice, asynchronously. This aborts any speech that may still be active from prior `SpeakString()' invocations. `Busy()' Return the number of speech channels busy, system-wide. `CountVoices()' Return the number of different voices available. `GetIndVoice(num)' Return a `Voice' object for voice number NUM. * Menu: * Voice Objects:: * Speech Channel Objects::  File: python-mac.info, Node: Voice Objects, Next: Speech Channel Objects, Prev: macspeech, Up: macspeech Voice Objects ------------- Voice objects contain the description of a voice. It is currently not yet possible to access the parameters of a voice. `GetGender()' Return the gender of the voice: `0' for male, `1' for female and `-1' for neuter. `NewChannel()' Return a new Speech Channel object using this voice.  File: python-mac.info, Node: Speech Channel Objects, Prev: Voice Objects, Up: macspeech Speech Channel Objects ---------------------- A Speech Channel object allows you to speak strings with slightly more control than `SpeakString()', and allows you to use multiple speakers at the same time. Please note that channel pitch and rate are interrelated in some way, so that to make your Macintosh sing you will have to adjust both. `SpeakText(str)' Start uttering the given string. `Stop()' Stop babbling. `GetPitch()' Return the current pitch of the channel, as a floating-point number. `SetPitch(pitch)' Set the pitch of the channel. `GetRate()' Get the speech rate (utterances per minute) of the channel as a floating point number. `SetRate(rate)' Set the speech rate of the channel.  File: python-mac.info, Node: EasyDialogs, Next: FrameWork, Prev: macspeech, Up: Front Matter Basic Macintosh dialogs ======================= Basic Macintosh dialogs. The `EasyDialogs' module contains some simple dialogs for the Macintosh, modelled after the `stdwin' dialogs with similar names. All routines have an optional parameter ID with which you can override the DLOG resource used for the dialog, as long as the item numbers correspond. See the source for details. The `EasyDialogs' module defines the following functions: `Message(str)' A modal dialog with the message text STR, which should be at most 255 characters long, is displayed. Control is returned when the user clicks "OK". `AskString(prompt[, default])' Ask the user to input a string value, in a modal dialog. PROMPT is the promt message, the optional DEFAULT arg is the initial value for the string. All strings can be at most 255 bytes long. `AskString()' returns the string entered or `None' in case the user cancelled. `AskYesNoCancel(question[, default])' Present a dialog with text QUESTION and three buttons labelled "yes", "no" and "cancel". Return `1' for yes, `0' for no and `-1' for cancel. The default return value chosen by hitting return is `0'. This can be changed with the optional DEFAULT argument. `ProgressBar([label[, maxval]])' Display a modeless progress dialog with a thermometer bar. LABEL is the text string displayed (default "Working..."), MAXVAL is the value at which progress is complete (default `100'). The returned object has one method, `set(VALUE)', which sets the value of the progress bar. The bar remains visible until the object returned is discarded. The progress bar has a "cancel" button, but it is currently non-functional. Note that `EasyDialogs' does not currently use the notification manager. This means that displaying dialogs while the program is in the background will lead to unexpected results and possibly crashes. Also, all dialogs are modeless and hence expect to be at the top of the stacking order. This is true when the dialogs are created, but windows that pop-up later (like a console window) may also result in crashes.  File: python-mac.info, Node: FrameWork, Next: MiniAEFrame, Prev: EasyDialogs, Up: Front Matter Interactive application framework ================================= Interactive application framework. The `FrameWork' module contains classes that together provide a framework for an interactive Macintosh application. The programmer builds an application by creating subclasses that override various methods of the bases classes, thereby implementing the functionality wanted. Overriding functionality can often be done on various different levels, i.e. to handle clicks in a single dialog window in a non-standard way it is not necessary to override the complete event handling. The `FrameWork' is still very much work-in-progress, and the documentation describes only the most important functionality, and not in the most logical manner at that. Examine the source or the examples for more details. The `FrameWork' module defines the following functions: `Application()' An object representing the complete application. See below for a description of the methods. The default `__init__()' routine creates an empty window dictionary and a menu bar with an apple menu. `MenuBar()' An object representing the menubar. This object is usually not created by the user. `Menu(bar, title[, after])' An object representing a menu. Upon creation you pass the `MenuBar' the menu appears in, the TITLE string and a position (1-based) AFTER where the menu should appear (default: at the end). `MenuItem(menu, title[, shortcut, callback])' Create a menu item object. The arguments are the menu to crate the item it, the item title string and optionally the keyboard shortcut and a callback routine. The callback is called with the arguments menu-id, item number within menu (1-based), current front window and the event record. In stead of a callable object the callback can also be a string. In this case menu selection causes the lookup of a method in the topmost window and the application. The method name is the callback string with `'domenu_'' prepended. Calling the `MenuBar' `fixmenudimstate()' method sets the correct dimming for all menu items based on the current front window. `Separator(menu)' Add a separator to the end of a menu. `SubMenu(menu, label)' Create a submenu named LABEL under menu MENU. The menu object is returned. `Window(parent)' Creates a (modeless) window. PARENT is the application object to which the window belongs. The window is not displayed until later. `DialogWindow(parent)' Creates a modeless dialog window. `windowbounds(width, height)' Return a `(LEFT, TOP, RIGHT, BOTTOM)' tuple suitable for creation of a window of given width and height. The window will be staggered with respect to previous windows, and an attempt is made to keep the whole window on-screen. The window will however always be exact the size given, so parts may be offscreen. `setwatchcursor()' Set the mouse cursor to a watch. `setarrowcursor()' Set the mouse cursor to an arrow. * Menu: * Application Objects:: * Window Objects:: * ControlsWindow Object:: * ScrolledWindow Object:: * DialogWindow Objects::