\input{libmacic}

\input{libmacic}

Return the next message in the mailbox, as a \code{rfc822.Message} object.

object may be a true file object or a class instance simulating a file object,

taking care of things like message boundaries if multiple mail messages are

\begin{funcdesc}{NewAliasMinimalFromFullPath}{pathname}

Return a minimal alias record object that points to the given file, which

must be specified as a full pathname. This is the only way to create an

alias record pointing to a non-existing file.

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.

\section{Standard Module \sectcode{ic}}

\bimodindex{ic}

\renewcommand{\indexsubitem}{(in module ic)}

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 \code{icglue} which provides the

basic ic 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 \code{ic} module defines the \code{error} exception and symbolic

names for all error codes IC can produce, see the source for details.

The \code{ic} module defines the following functions:

\begin{funcdesc}{IC}{\optional{signature\, ic}}

Create an internet config object. The signature is a 4-char creator

code of the current application (default \code{'Pyth'}) which may

influence some of ICs settings. The optional \var{ic} argument is a

low-level \code{icinstance} created beforehand, this may be useful if

you want to get preferences from a different config file, etc.

\end{funcdesc}

\begin{funcdesc}{launchurl}{url \optional{\, hint}}

\end{funcdesc}

\begin{funcdesc}{parseurl}{data \optional{\, start\, end\, hint}}

\end{funcdesc}

\begin{funcdesc}{mapfile}{file}

\end{funcdesc}

\begin{funcdesc}{maptypecreator}{type\, creator \optional{\,

filename}}

\end{funcdesc}

\begin{funcdesc}{settypecreator}{file}

These functions are ``shortcuts'' to the methods of the same name,

described below.

\end{funcdesc}

\subsection{IC objects}

IC objects have a mapping interface, hence to obtain the mail address

you simply get \code{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 datastructure. Running the

\code{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 \var{ICOpaqueData} type, with the raw data in its

\var{data} attribute. Objects of this type are also acceptable values

for assignment.

Besides the dictionary interface IC objects have the following methods:

\renewcommand{\indexsubitem}{(IC object attribute)}

\begin{funcdesc}{launchurl}{url \optional{\, hint}}

Parse the given URL, lauch the correct application and pass it the

URL. The optional \var{hint} can be a scheme name such as

\code{mailto:}, in which case incomplete URLs are completed with this

scheme (otherwise incomplete URLs are invalid).

\end{funcdesc}

\begin{funcdesc}{parseurl}{data \optional{\, start\, end\, hint}}

Find an URL somewhere in \var{data} and return start position, end

position and the URL. The optional \var{start} and \var{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

\var{start} and this routine will return the whole URL in which the

user clicked. \var{Hint} is again an optional scheme used to complete

incomplete URLs.

\end{funcdesc}

\begin{funcdesc}{mapfile}{file}

Return the mapping entry for the given \var{file}, which can be passed

as either a filename or an \var{FSSpec} object, and which need not

exist.

The mapping entry is returned as a tuple \code{(version\, type\,

creator\, postcreator\, flags\, extension\, appname\, postappname\,

mimetype\, entryname)}, where \var{version} is the entry version

number, \var{type} is the 4-char filetype, \var{creator} is the 4-char

creator type, \var{postcreator} is the 4-char creator code of an

optional application to post-process the file after downloading,

\var{flags} are various bits specifying whether to transfer in binary

or ascii and such, \var{extension} is the filename extension for this

file type, \var{appname} is the printable name of the application to

which this file belongs, \var{postappname} is the name of the

postprocessing application, \var{mimetype} is the MIME type of this

file and \var{entryname} is the name of this entry.

\end{funcdesc}

\begin{funcdesc}{maptypecreator}{type\, creator \optional{\,

filename}}

Return the mapping entry for files with given 4-char \var{type} and

\var{creator} codes. The optional \var{filename} may be specified to

further help finding the correct entry (if the creator code is

\code{'????'}, for instance).

The mapping entry is returned in the same format as for \var{mapfile}.

\end{funcdesc}

\begin{funcdesc}{settypecreator}{file}

Given an existing \var{file}, specified either as a filename or as an

\var{FSSpec} record, 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.

\end{funcdesc}

\begin{funcdesc}{SetEventHandler}{handler}

In the inner interpreter loop Python will occasionally check for events,

unless disabled with \var{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 parameter to clear the event handler. Setting

an eventhandler while one is already set is an error.

\begin{funcdesc}{SchedParams}{\optional{doint\, evtmask\, besocial\,

interval\, bgyield}}

Influence the interpreter inner loop event handling. \var{Interval}

specifies how often (in seconds, floating point) the interpreter

should enter the event processing code. When true, \var{doint} causes

interrupt (command-dot) checking to be done. \var{Evtmask} tells the

interpreter to do event processing for events in the mask (redraws,

mouseclicks to switch to other applications, etc). \bar{Besocial}

gives other processes a chance to run. They are granted minimal

runtime when Python is in the foreground and \var{bgyield} seconds per

\var{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.

If you attempt to call this function from an event handler set through

\code{SetEventHandler} you will get an exception.

names. All routines have an optional parameter \var{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.

In general, all event handlers should return 1 if the event is fully

handled and 0 otherwise (because the front window was not a FrameWork

window, for instance). This is needed so that update events and such

can be passed on to other windows like the Sioux console window.

Calling \code{MacOS.HandleEvent} is not allowed within \var{our_dispatch}

or its callees, since this may result in an infinite loop if the

code is called through the python inner-loop event handler.

\end{funcdesc}

\begin{funcdesc}{asyncevents}{onoff}

Call this method with a nonzero parameter to enable

asynchronous event handling. This will tell the inner interpreter loop

to call the application event handler \var{async_dispatch} whenever events

are available. This will cause FrameWork window updates and the user

interface to remain working during long computations, but will slow the

interpreter down and may cause surprising results in non-reentrant code

(such as FrameWork itself). By default \var{async_dispatch} will immedeately

call \var{our_dispatch} but you may override this to handle only certain

events asynchronously. Events you do not handle will be passed to Sioux

and such.

The old on/off value is returned.

Return the next message in the mailbox, as a \code{rfc822.Message} object.

object may be a true file object or a class instance simulating a file object,

taking care of things like message boundaries if multiple mail messages are

\begin{funcdesc}{NewAliasMinimalFromFullPath}{pathname}

Return a minimal alias record object that points to the given file, which

must be specified as a full pathname. This is the only way to create an

alias record pointing to a non-existing file.

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.