fsleyes_widgets.dialog

This module contains a collection of basic dialog classes, available for use throughout fslpy. The available dialogs are:

SimpleMessageDialog

A simple, no-frills wx.Dialog for displaying a message.

TimeoutDialog

A SimpleMessageDialog which automatically destroys itself after a specified timeout period.

ProcessingDialog

A SimpleMessageDialog which displays a message and runs a task in the background.

TextEditDialog

A dialog which shows an editable/selectable text field.

FSLDirDialog

A dialog which warns the user that the $FSLDIR environment variable is not set, and prompts them to identify the FSL installation directory.

class fsleyes_widgets.dialog.SimpleMessageDialog(parent=None, message='', style=None)

Bases: wx._core.Dialog

A simple, no-frills wx.Dialog for displaying a message. The message can be updated via the SetMessage() method. As a simple usage example:

import fsleyes_widgets.dialog as fsldlg
dlg = fsldlg.SimpleMessageDialog(message='Loading data ...')

dlg.Show()

# load the data, like
# you said you would

# Data is loaded, so we
# can kill the dialog
dlg.Close()
dlg.Destroy()

The SimpleMessageDialog class supports the following styles:

SMD_KEEP_CENTERED

If set, the dialog will be re-centred on its parent whenever its message changes.

a SimpleMessageDialog looks something like this:

_images/simplemessagedialog.png

Create a SimpleMessageDialog.

Parameters
  • parent – The wx parent object.

  • message – The initial message to show.

  • style – Only one style flag is supported, SMD_KEEP_CENTERED. This flag is enabled by default.

Show()

Overrides wx.Dialog.Show. Calls that method, and calls wx.Yield.

SetMessage(msg)

Updates the message shown on this SimpleMessageDialog.

If the SMD_KEEP_CENTERED style is set, the dialog is re-centered on its parent, to account for changes in the message width.

fsleyes_widgets.dialog.SMD_KEEP_CENTERED = 1

If set, the dialog will be re-centred on its parent whenever its message changes.

class fsleyes_widgets.dialog.TimeoutDialog(parent, message, timeout=1000, **kwargs)

Bases: fsleyes_widgets.dialog.SimpleMessageDialog

A SimpleMessageDialog which automatically destroys itself after a specified timeout period.

Note

The timeout functionality will not work if you show the dialog by any means other than the wx.Dialog.Show() or wx.Dialog.ShowModal() methods … but is there any other way of showing a wx.Dialog?

Create a TimeoutDialog.

Parameters
  • parent – The wx parent object.

  • message – The initial message to display.

  • timeout – Timeout period in milliseconds.

  • kwargs – Passed through to SimpleMessageDialog.__init__().

Show()

Shows this TimeoutDialog, and sets up a callback to close it after the specified timeout.

ShowModal()

Shows this TimeoutDialog, and sets up a callback to close it after the specified timeout.

class fsleyes_widgets.dialog.ProcessingDialog(parent, message, task, *args, **kwargs)

Bases: fsleyes_widgets.dialog.SimpleMessageDialog

A SimpleMessageDialog which displays a message and runs a task in the background. User interaction is blocked while the task runs, and the dialog closes and destroys itself automatically on task completion.

The task is simply passed in as a function. If the task supports it, the ProcessingDialog will pass it two message-updating functions, which can be used by the task to update the message being displayed. This functionality is controlled by the passFuncs, messageFunc and errorFunc parameters to __init__().

A ProcessingDialog must be displayed via the Run() method, not with the wx.Dialog.Show() or wx.Dialog.ShowModal() methods.

Create a ProcessingDialog.

Parameters
  • parent – The wx parent object.

  • message – Initial message to display.

  • task – The function to run.

  • args – Positional arguments passed to the task function.

  • kwargs – Keyword arguments passed to the task function.

Some special keyword arguments are also accepted:

Name

Description

passFuncs

If True, two extra keyword arguments are passed to the task function - messageFunc and errorFunc.

messageFunc is a function which accepts a single string as its argument; when it is called, the dialog message is updated to display the string.

errorFunc is a function which accepts two arguemnts - a message string and an Exception instance. If the task detects an error, it may call this function. A new dialog is shown, containing the details of the error, to inform the user.

messageFunc

Overrides the default messageFunc described above.

errorFunc

Overrides the default errorFunc described above.

Run(mainThread=False)

Shows this ProcessingDialog, and runs the task function passed to __init__(). When the task completes, this dialog is closed and destroyed.

Parameters

mainThread – If True the task is run in the current thread. Otherwise, the default behaviour is to run the task in a separate thread.

Returns

the return value of the task function.

Note

If mainThread=True, the task should call wx.Yield() periodically - under GTK, there is a chance that this ProcessingDialog will not get drawn before the task begins.

Show()

Raises a NotImplementedError.

ShowModal()

Raises a NotImplementedError.

class fsleyes_widgets.dialog.TextEditDialog(parent, title='', message='', text='', icon=None, style=None)

Bases: wx._core.Dialog

A dialog which shows an editable/selectable text field.

TextEditDialog supports the following styles:

TED_READONLY

If set, the user will not be able to change the text field contents.

TED_MULTILINE

If set, the text field will span multiple lines.

TED_OK

If set, an Ok button will be shown.

TED_CANCEL

If set, a Cancel button will be shown.

TED_OK_CANCEL

If set, Ok and Cancel buttons will be shown.

TED_COPY

If set, a Copy button will be shown, allowing the use to copy the text to the system clipboard.

TED_COPY_MESSAGE

If set, and if TED_COPY is also set, when the user chooses to copy the text to the system clipboard, a popup message is displayed.

A TextEditDialog looks something like this:

_images/texteditdialog.png

Create a TextEditDialog.

Parameters
onOk(ev)

Called when the Ok button is pressed. Ends the dialog.

onCancel(ev)

Called when the Cancel button is pressed. Ends the dialog.

SetMessage(message)

Set the message displayed on the dialog.

SetOkLabel(label)

Set the label to show on the Ok button.

SetCopyLabel(label)

Sets the label to show on the Copy button.

SetCancelLabel(label)

Sets the label to show on the Cancel button.

SetText(text)

Sets the text to show in the text field.

GetText()

Returns the text shown in the text field.

fsleyes_widgets.dialog.TED_READONLY = 1

If set, the user will not be able to change the text field contents.

fsleyes_widgets.dialog.TED_MULTILINE = 2

If set, the text field will span multiple lines.

fsleyes_widgets.dialog.TED_OK = 4

If set, an Ok button will be shown.

fsleyes_widgets.dialog.TED_CANCEL = 8

If set, a Cancel button will be shown.

fsleyes_widgets.dialog.TED_OK_CANCEL = 12

If set, Ok and Cancel buttons will be shown. Equivalent to TED_OK | TED_CANCEL.

fsleyes_widgets.dialog.TED_COPY = 16

If set, a Copy button will be shown, allowing the use to copy the text to the system clipboard.

fsleyes_widgets.dialog.TED_COPY_MESSAGE = 32

If set, and if TED_COPY is also set, when the user chooses to copy the text to the system clipboard, a popup message is displayed.

class fsleyes_widgets.dialog.FSLDirDialog(parent, toolName, osxHint)

Bases: wx._core.Dialog

A dialog which warns the user that the $FSLDIR environment variable is not set, and prompts them to identify the FSL installation directory.

If the user selects a directory, the getFSLDir() method can be called to retrieve their selection after the dialog has been closed.

A FSLDirDialog looks something like this:

_images/fsldirdialog.png

Create a FSLDirDialog.

Parameters
  • parent – The wx parent object.

  • toolName – The name of the tool which is running.

  • osxHint – If True, an OSX-specific hint is added to the dialog.

GetFSLDir()

If the user selected a directory, this method returns their selection. Otherwise, it returns None.

class fsleyes_widgets.dialog.CheckBoxMessageDialog(parent, title=None, message=None, cbMessages=None, cbStates=None, yesText=None, noText=None, cancelText=None, hintText=None, focus=None, icon=None, style=None)

Bases: wx._core.Dialog

A wx.Dialog which displays a message, one or more wx.CheckBox widgets, with associated messages, an Ok button, and (optionally) a Cancel button.

Create a CheckBoxMessageDialog.

Parameters
  • parent – A wx parent object.

  • title – The dialog frame title.

  • message – Message to show on the dialog.

  • cbMessages – A list of labels, one for each wx.CheckBox.

  • cbStates – A list of initial states (boolean values) for each wx.CheckBox.

  • yesText – Text to show on the yes/confirm button. Defaults to OK.

  • noText – Text to show on the no button. If not provided, there will be no no button.

  • cancelText – Text to show on the cancel button. If not provided, there will be no cancel button.

  • hintText – If provided, shown as a “hint”, in a slightly faded font, between the checkboxes and the buttons.

  • focus – One of 'yes', 'no'`, or 'cancel', specifying which button should be given initial focus.

  • icon – A wx icon identifier (e.g. wx.ICON_EXCLAMATION).

  • style – Passed through to the wx.Dialog.__init__ method. Defaults to wx.DEFAULT_DIALOG_STYLE.

CheckBoxState(index=0)

After this CheckBoxMessageDialog has been closed, this method will retrieve the state of the dialog CheckBox.