Changes between Initial Version and Version 1 of LoggingAPI

Timestamp:

Nov 24, 2014, 4:59:45 PM (11 years ago)

Author:

Eric Pettersen

Comment:

--

LoggingAPI

@@ +1 @@
+
+= !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.