class Application(MessageHandler)

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.

Global Functions

application()
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 application function returns this reference.
If this function is called before any application object has been created, it creates an instance of class Application automatically.

Constructor

Application(title = None)
Creates and initializes an Application. The title 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.

Properties

menus
List of application-wide Menu instances. These menus will always be available regardless of which window is active.

Do not modify the contents of this list directly. If you want to add or remove menus, build a new list of menus and assign the whole list to the menus property. Otherwise, the displayed menus may not be updated properly.
windows
Read only. List of all currently existing Window instances. Do not modify this list.
documents
Read only. List of all currently existing Document instances. Do not modify this list.

open_file_types
A list of FileTypes specifying the types of files that can be opened by the Open... 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 Open... command.

save_file_type
A FileType 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 Save and Save As... commands, and you don't explicitly set the file_type property of all your Documents.

file_type
Write only. This is a convenience property for applications that only deal with one type of file. Setting it to a FileType f is the same as setting open_file_types to [f] and save_file_type to f.

target
Read-only. 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.

target_window
Read-only. The Window containing the current target of keyboard events and menu commands, or None if there are no windows.

Attributes

page_setup
A default application-wide PageSetup instance that is edited by the generic implementation of the Page Setup command and used by default implementations of the Print command.

Methods

run()
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 report_exception().

The normal method of quitting the application is to call quit_cmd(). 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 _quit().
event_loop()
Runs an event loop, fetching and handling input events until exit_event_loop() is called.

If a Cancel 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 report_exception().

exit_event_loop()
Causes the current call to event_loop() to exit.

report_exception()
Displays an alert box reporting the current exception (as determined by sys.exc_info()) and giving the user the option of continuing, getting a traceback or exiting the application.
new_cmd()
Implements the standard New command. Calls make_document to create a new document, initialises it as an empty document, and calls make_window to create an initial window for it.
open_cmd()
Implements the standard Open... command. Requests a file name from the user, calls make_document to create a document, loads the document from the file, and calls make_window to create an initial window for it.
quit_cmd()
Implements the standard Quit command. Asks the user whether to save changes to any changed documents, and if the user doesn't cancel, raises a Quit exception.

page_setup_cmd()
Default implementation of the Page Setup... command. Edits the PageSetup instance referred to by the page_setup attribute.
query_clipboard()
Returns true if the clipboard contains any data. This is likely to be more efficient than testing the result of get_clipboard().
get_clipboard()
Returns the current contents of the clipboard as a string, or an empty string if the clipboard contains no data.
set_clipboard(data)
Replaces the contents of the clipboard with the given data, which should be a string.
_quit()
Exits the main event loop immediately, without giving any option to save changes. For emergency use only.

Abstract Methods

open_app()
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 new_cmd() method to create a new, empty document.
make_document(file_ref or None)
If you want to use the built-in support for the New or Open... commands, you need to implement this method.

If the file_ref argument is None, you should create a new Document object of the appropriate class in response to a New command.

Otherwise, should create a new Document object of the appropriate class for the file represented by the given FileRef. 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.
make_window(document)
If you want to use the built-in support for the New and Open... 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.

get_default_open_directory()
Called by the default implementation of open_cmd() to find an initial directory for request_old_file(). Should return a DirRef or FileRef, or  None if there is no preferred location.

The default implementation returns the last directory in which a document was opened or saved during this session.

---