Logging/Status API

Overview

The logger handles status and non-status messages separately. The only reason that the logger is involved in status messages at all is so that non-tools can present status messages. Status messages are plain text only (though color can be specified). Non-status messages allow for plain text and/or HTML/image logging.

Non-Status Logging

The logger offer three functions for non-status logging: info(), warning(), and error(). They all take the same arguments and keywords. The single mandatory argument is a text string (message), which can be empty. The optional keywords are:

Name	Default	Description
add_newline	True	Append newline to text before logging
image	None	A PIL image to log, in which case the text message is used as alt text for plain-text logs
is_html	False	Is text message HTML? Use best effort to convert to plain text for plain-text logs

Status Logging

All graphical tools have a ToolWindow instance that provides the interface area that the tool will build its user interface within. Such tools will issue status messages via the ToolWindow's status() method. If available, the message will be shown in the tool's own status area (there is no such area in the current implementation). Otherwise the message (and arguments) will be forwarded to the logger's status() method, which in turn will forward to the main window's status() method. If there is no main window then the message will be dropped. Non-tools can issue status messages by calling the logger's status() method directly.

All the various status() methods have the same call signature. The only mandatory argument is a plain text message string. The primary keyword arguments are:

Name	Default	Description
color	"black"	Status text color
log	False	Also log the message using info()
secondary	False	Show message in the secondary status area

The secondary status area is typically used for "sub status" or very transitory messages. For example, when Chimera 1 saves a session it shows "Saving session…" in the primary status area and each sub step (e.g. "Saving coordinates") is shown in the secondary area. Another example is when MultAlign Viewer shows residue-association information as the mouse moves, it uses the secondary status area so that any primary status information isn't prematurely erased.

Less frequently used keyword args are:

Name	Default	Description
blank_after	None	Number of seconds to show the message before clearing. If None, use user-specified default.
follow_with	""	Follow first status with this text
follow_time	20	How log, in seconds, before showing the follow_with text
follow_log	None	Whether to log the follow_with message. If None, use the log value.

Other keyword args may be added later as its determined that they're needed.