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.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: 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.

clear(timeout)

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

veto()

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

die()

This method may be used to force the ClearThread to exit immediately, rather than when the process exits.

To cleanly kill the ClearThread, follow this procedure:

import fsleyes_widgets.utils.status as status

status._clearThread.die()
status._clearThread.clear(0.1)
status._clearThread.join()
status._clearThread = None

If the update() function is used again, a new ClearThread will automatically be started.

run()

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