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.

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.

Methods

run()

The main event loop. A program calls this method after initialisation, and it retains control until a Quit exception is raised. Catches any other unhandled exceptions and reports them to the user with a default alert box.

handle_next_event()

Waits for the next input event to occur and handles it. A custom event loop may be constructed by calling this method repeatedly until some condition is met.

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.

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.

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.

---