228 lines
11 KiB
HTML
228 lines
11 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
|
|
<html><head><meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type"><title>Application</title>
|
|
|
|
<meta name="GENERATOR" content="Mozilla/3.01Gold (X11; I; SunOS 5.6 sun4u) [Netscape]"></head>
|
|
<body>
|
|
<h1>class <tt>Application(MessageHandler)</tt></h1>
|
|
<p>Each application has exactly one Application object, which
|
|
looks after application-wide concerns such as maintaining the set of
|
|
windows and documents, running the event loop, and handling global menu
|
|
commands.</p>
|
|
<h2>Global Functions</h2>
|
|
<dl>
|
|
<dt><tt>application()</tt></dt>
|
|
<dd>Returns the Application instance. The first time an
|
|
instance of Application or a subclass of Application is created, a
|
|
global reference to it is stored; the <tt>application</tt>
|
|
function returns this reference.<br>
|
|
</dd>
|
|
<dd>If this function is called before any application object
|
|
has been created, it creates an instance of class Application
|
|
automatically.</dd>
|
|
</dl>
|
|
<h2>Constructor</h2>
|
|
<dl style="margin-left: 40px;">
|
|
<dt style="font-family: monospace;">Application(title =
|
|
None)</dt>
|
|
<dd>Creates and initializes an Application. The <span style="font-style: italic;">title</span> must be
|
|
specified as a keyword argument; it
|
|
defaults to the name of the main Python file, or in the case of a
|
|
MacOSX application built with Py2App, it is taken from the info.plist
|
|
resource.</dd>
|
|
</dl>
|
|
<h2>Properties</h2>
|
|
<blockquote>
|
|
<dl>
|
|
<dt><tt>menus</tt></dt>
|
|
<dd>List of application-wide Menu instances. These menus will
|
|
always be
|
|
available regardless of which window is active.<br>
|
|
<br>
|
|
</dd>
|
|
<dd><i>Do not modify the contents of this list
|
|
directly. </i>If you want to add or remove menus, build a new
|
|
list of menus and assign the whole
|
|
list to the <tt>menus</tt> property. Otherwise, the
|
|
displayed menus may
|
|
not be updated properly.</dd>
|
|
</dl>
|
|
<dl>
|
|
<dt><tt>windows</tt></dt>
|
|
<dd><i>Read only</i>. List of all currently
|
|
existing Window instances.<span style="font-style: italic;">
|
|
Do not modify this list.</span><br>
|
|
</dd>
|
|
</dl>
|
|
<dl>
|
|
<dt><tt>documents</tt></dt>
|
|
<dd><i>Read only</i>. List of all currently
|
|
existing Document instances.<span style="font-style: italic;"> Do not modify this list.</span><br>
|
|
<br>
|
|
</dd>
|
|
<dt style="font-family: monospace;">open_file_types</dt>
|
|
<dd>A list of <a href="FileType.html">FileType</a>s
|
|
specifying the types of files that can be opened by the <span style="font-weight: bold;">Open...</span>
|
|
command. If empty, any type of file is acceptable. You only need to set
|
|
this if you want to make use of the default implementation of the <span style="font-weight: bold;">Open...</span> command.<br>
|
|
<br>
|
|
</dd>
|
|
<dt style="font-family: monospace;">save_file_type</dt>
|
|
<dd>A <a href="FileType.html">FileType</a>
|
|
specifying the default file type for Documents that don't specify one
|
|
of their own. You only need to set
|
|
this if you want to make use of the default implementations of the <span style="font-weight: bold;">Save</span> and <span style="font-weight: bold;">Save As...</span> commands,
|
|
and you don't explicitly set the <span style="font-family: monospace;">file_type</span>
|
|
property of all your Documents.<br>
|
|
<br>
|
|
</dd>
|
|
<dt style="font-family: monospace;">file_type</dt>
|
|
<dd><span style="font-style: italic;">Write only.</span>
|
|
This is a convenience property for applications that only deal with one
|
|
type of file. Setting it to a FileType <span style="font-style: italic;">f</span> is the same as
|
|
setting <span style="font-family: monospace;">open_file_types</span>
|
|
to <span style="font-family: monospace;">[</span><span style="font-style: italic;">f</span><span style="font-family: monospace;">]</span> and <span style="font-family: monospace;">save_file_type</span>
|
|
to <span style="font-style: italic;">f</span>.<br>
|
|
<br>
|
|
</dd>
|
|
<dt style="font-family: monospace;">target</dt>
|
|
<dd><span style="font-style: italic;">Read-only.</span>
|
|
The object which is the current target of keyboard events and menu
|
|
commands. This will be a Component contained within the frontmost
|
|
window, the frontmost window itself, or if there are no windows, the
|
|
Application itself.<br>
|
|
<br>
|
|
</dd>
|
|
<dt style="font-family: monospace;">target_window</dt>
|
|
<dd><span style="font-style: italic;">Read-only.
|
|
</span>The Window containing the current target of keyboard
|
|
events and menu commands, or None if there are no windows.</dd>
|
|
</dl>
|
|
<dl>
|
|
</dl>
|
|
</blockquote>
|
|
<h2>Attributes</h2><dl style="margin-left: 40px;"><dt style="font-family: monospace;">page_setup</dt><dd>A default application-wide <a href="PageSetup.html">PageSetup</a> instance that is edited by the generic implementation of the <span style="font-style: italic;">Page Setup</span> command and used by default implementations of the <span style="font-style: italic;">Print</span> command.</dd></dl><h2>Methods</h2>
|
|
<blockquote>
|
|
<dl>
|
|
<dt><tt>run()</tt></dt>
|
|
<dd>The main event loop. A program calls this method after
|
|
initialisation, and it retains control until the application is quit.
|
|
Catches any unhandled exceptions and reports them to the user via <span style="font-family: monospace;">report_exception()</span>.<br>
|
|
<br>
|
|
The normal method of quitting the application is to call <span style="font-family: monospace;">quit_cmd()</span>.
|
|
This gives the user the opportunity to close any open documents and
|
|
save any unsaved changes. If this is undesirable for some reason, a
|
|
more direct exit can be achieved using <span style="font-family: monospace;">_quit()</span>.<br></dd></dl>
|
|
</blockquote>
|
|
<blockquote>
|
|
<dl>
|
|
<dt style="font-family: monospace;">event_loop()</dt>
|
|
<dd>Runs an event loop, fetching and handling input events
|
|
until <span style="font-family: monospace;">exit_event_loop()</span>
|
|
is called.<br>
|
|
<br>
|
|
If a <span style="font-family: monospace;">Cancel</span>
|
|
exception is raised during the event loop, it is silently caught and
|
|
the event loop continues. The handling of an exception of any other
|
|
type is platform-dependent; it may break the event loop and be
|
|
propagated, or it may be handled within the loop using <span style="font-family: monospace;">report_exception()</span>.<br><br></dd>
|
|
<dt style="font-family: monospace;">exit_event_loop()</dt>
|
|
<dd>Causes the current call to <span style="font-family: monospace;">event_loop()</span><span style="font-family: monospace;"></span> to
|
|
exit.<br>
|
|
<br>
|
|
</dd>
|
|
<dt style="font-family: monospace;"><a name="report_exception"></a>report_exception()</dt>
|
|
<dd>Displays an alert box reporting the current exception (as
|
|
determined by <span style="font-family: monospace;">sys.exc_info()</span>)
|
|
and giving the user the option of continuing, getting a traceback or
|
|
exiting the application.</dd>
|
|
</dl>
|
|
<dl>
|
|
</dl>
|
|
<dl>
|
|
<dt><tt>new_cmd()</tt></dt>
|
|
<dd>Implements the standard <b>New </b>command.
|
|
Calls <tt>make_document</tt> to create a new document,
|
|
initialises it as an empty document, and calls <tt>make_window</tt>
|
|
to create an initial window for it.</dd>
|
|
</dl>
|
|
<dl>
|
|
<dt><tt><a name="open_cmd"></a>open_cmd()</tt></dt>
|
|
<dd>Implements the standard <b>Open...</b>
|
|
command. Requests a file name from the user, calls <tt>make_document</tt>
|
|
to create a document, loads the document from the file, and calls <tt>make_window</tt>
|
|
to create an initial window for it.</dd>
|
|
</dl>
|
|
<dl>
|
|
<dt><tt>quit_cmd()</tt></dt>
|
|
<dd>Implements the standard <b>Quit </b>command.
|
|
Asks the user whether to save changes to any changed documents, and if
|
|
the user doesn't cancel, raises a <tt>Quit</tt> exception.<br><br></dd><dt style="font-family: monospace;">page_setup_cmd()</dt><dd>Default implementation of the <span style="font-weight: bold;">Page Setup...</span> command. Edits the PageSetup instance referred to by the <span style="font-family: monospace;">page_setup</span> attribute.</dd>
|
|
</dl>
|
|
<dl>
|
|
<dt><tt>query_clipboard()</tt></dt>
|
|
<dd>Returns true if the clipboard contains any data. This is
|
|
likely to
|
|
be more efficient than testing the result of <tt>get_clipboard()</tt>.</dd>
|
|
</dl>
|
|
<dl>
|
|
<dt><tt>get_clipboard()</tt></dt>
|
|
<dd>Returns the current contents of the clipboard as a
|
|
string, or an
|
|
empty string if the clipboard contains no data.<br>
|
|
</dd>
|
|
</dl>
|
|
</blockquote>
|
|
<blockquote>
|
|
<dl>
|
|
<dt><tt>set_clipboard(</tt><i>data</i><tt>)</tt></dt>
|
|
<dd>Replaces the contents of the clipboard with the given
|
|
data, which
|
|
should be a string.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
<ul>
|
|
</ul>
|
|
<blockquote> <dl><dt style="font-family: monospace;">_quit()</dt><dd>Exits the main event loop immediately, without giving any option to save changes. For emergency use only.</dd></dl></blockquote>
|
|
<h2>Abstract Methods</h2>
|
|
<blockquote>
|
|
<dl>
|
|
<dt style="font-family: monospace;">open_app()</dt>
|
|
<dd>This
|
|
method is called when the application is started without any
|
|
command-line arguments. The default implementation does nothing. In a
|
|
document-based application, you will typically override it to call the <span style="font-family: monospace;">new_cmd()</span>
|
|
method to create a new, empty document.<br>
|
|
</dd>
|
|
</dl>
|
|
<dl>
|
|
<dt><tt>make_document(</tt>file_ref<tt> </tt><span style="font-style: italic;">or</span><tt> None)</tt></dt>
|
|
<dd>If you want to use the built-in support for the <span style="font-weight: bold;">New</span> or <span style="font-weight: bold;">Open...</span>
|
|
commands, you need to implement this method.<br>
|
|
<br>
|
|
If the <span style="font-weight: bold;">file_ref</span>
|
|
argument is None, you should create a new Document object of the
|
|
appropriate class in response to a <b>New </b>command.<br>
|
|
<br>
|
|
Otherwise, should
|
|
create a new Document object of the appropriate class for
|
|
the file represented by the given <a href="FileRef.html">FileRef</a>.
|
|
You may
|
|
examine the file name, read the beginning of the file or do whatever
|
|
else
|
|
is necessary to determine what class of object to create. If you can't
|
|
recognise the file, you should return None, and an appropriate error
|
|
message will be displayed. The default implementation returns None.<br>
|
|
</dd>
|
|
</dl>
|
|
<dl>
|
|
<dt><tt>make_window(</tt>document<tt>)</tt></dt>
|
|
<dd>If you want to use the built-in support for the <span style="font-weight: bold;">New</span> and <span style="font-weight: bold;">Open...</span>
|
|
commands, you need to implement this method. Your
|
|
implementation
|
|
should create a Window containing a component hierarchy suitable
|
|
for viewing the given Document object. There is no default
|
|
implementation.<br><br></dd><dt><tt>get_default_open_directory()</tt></dt><dd>Called by the default implementation of <a href="#open_cmd"><tt>open_cmd()</tt></a> to find an initial directory for <a href="file_dialogs.html#request_old_file"><tt>request_old_file()</tt></a>. Should return a <a href="DirRef.html">DirRef</a> or <a href="FileRef.html">FileRef</a>, or None if there is no preferred location.<br><br>The default implementation returns the last directory in which a document was opened or saved during this session.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
<p>---</p>
|
|
</body></html> |