fsleyes_widgets.utils.status

This is a little module which provides an interface for displaying a message, or status update, to the user. The status module provides the following functions:

setTarget	Set a target function to receive status updates.
update	Display a status update to the user.
clearStatus	Clear the status.

A couple of other functions are also provided, for reporting error messages to the user:

reportError	Reports an error to the user in a generic manner.
reportIfError	A context manager which calls reportError() if the enclosed code raises an Exception.
reportErrorDecorator	A decorator which wraps the decorated function with reportIfError().

The update() function may be used to display a message. By default, the message is simply logged (via the logging module). However, if a status target has been set via the setTarget() function, the message is also passed to this target.

Warning

If the status update target is a wx GUI object, you must make sure that it is updated asynchronously (e.g. via wx.CallAfter).

fsleyes_widgets.utils.status._statusUpdateTarget = None

A reference to the status update target - this is None by default, and can be set via setTarget().

fsleyes_widgets.utils.status._clearThread = None

Reference to a ClearThread, which is a daemon thread that clears the status after the timeout passed to the update() function.

fsleyes_widgets.utils.status.setTarget(target)

Set a target function to receive status updates. The target must be a function which accepts a string as its sole parameter.

fsleyes_widgets.utils.status.update(message, timeout=1.0)

Display a status update to the user. The message is logged and, if a status update target has been set, passed to the target.

Parameters:timeout – Timeout (in seconds) after which the status will be cleared (via the ClearThread). Pass in None to disable this behaviour.

Note

The timeout method only makes sense to use if the status target is a GUI widget of some sort.

fsleyes_widgets.utils.status.clearStatus()

Clear the status. If a status update target has been set, it is passed the empty string.

fsleyes_widgets.utils.status.reportError(title, msg, err)

Reports an error to the user in a generic manner. If a GUI is available, a wx.MessageBox is shown. Otherwise a log message is generated.

fsleyes_widgets.utils.status.reportIfError(title, msg, raiseError=True, report=True)

A context manager which calls reportError() if the enclosed code raises an Exception.

Parameters:

• raiseError – If True, the Exception which was raised is propagated upwards.
• report – Defaults to True. If False, an error message is logged, but reportError() is not called.

fsleyes_widgets.utils.status.reportErrorDecorator(*args, **kwargs)

A decorator which wraps the decorated function with reportIfError().

class fsleyes_widgets.utils.status.ClearThread

Bases: threading.Thread

The ClearThread is a daemon thread used by the update() function. Only one ClearThread is ever started - it is started on the first call to update when a timeout is specified.

The ClearThread waits until the clear() method is called. It then waits for the specified timeout and, unless another call to clear(), or a call to veto() has been made, clears the status via a call to clearStatus().

Create a ClearThread.

__init__()

Create a ClearThread.

clear(timeout)

Clear the status after the specified timeout (in seconds).

__module__ = 'fsleyes_widgets.utils.status'

veto()

If this ClearThread is waiting on a timeout to clear the status, a call to veto will prevent it from doing so.

run()

The ClearThread function. Infinite loop which waits until the clear() method is called, and then clears the status (via a call to clearStatus()).