`fsleyes.profiles`¶

The profiles package contains logic for mouse/keyboard interaction with ViewPanel panels.

This logic is encapsulated in four classes:

The Profile class is intended to be subclassed. A Profile instance contains the mouse/keyboard event handlers for a particular type of ViewPanel to allow the user to interact with the view in a particular way. For example, the OrthoViewProfile class allows the user to navigate through the display space in an OrthoPanel canvas, whereas the OrthoEditProfile class contains interaction logic for selecting and editing Image voxels in an OrthoPanel.

The CanvasPanelEventManager manages wx GUI events on the SliceCanvas instances contained in CanvasPanel views.

The PlotPanelEventManager manages matplotlib GUI events on the matplotlib Canvas instances contained in PlotPanel views.

The ProfileManager class is used by ViewPanel instances to create and change the Profile instance currently in use.

The profilemap module contains mappings between ViewPanel types, and their corresponding Profile types.

The profiles package is also home to the shortcuts module, which defines global FSLeyes keyboard shortcuts.

class fsleyes.profiles.ProfileManager(viewPanel, overlayList, displayCtx)[source]¶

Bases: object

Manages creation/registration/de-registration of Profile instances for a ViewPanel instance.

A ProfileManager instance is created and used by every ViewPanel instance. The profilemap module defines the Profile types which should used for specific ViewPanel types.

__init__(viewPanel, overlayList, displayCtx)[source]¶

Create a ProfileManager.

Parameters

viewPanel – The ViewPanel instance which this ProfileManager is to manage.
overlayList – The OverlayList instance containing the overlays that are being displayed.
displayCtx – The DisplayContext instance which defines how overlays are being displayed.

destroy()[source]¶

This method must be called by the owning ViewPanel when it is about to be destroyed (or when it no longer needs a ProfileManager).

This method destroys the current Profile (if any), and clears some internal object references to avoid memory leaks.

getCurrentProfile()[source]¶: Returns the Profile instance currently in use.

changeProfile(profile)[source]¶: Deregisters the current Profile instance (if necessary), and creates a new one corresponding to the named profile.

__dict__ = mappingproxy({'__module__': 'fsleyes.profiles', '__doc__': 'Manages creation/registration/de-registration of :class:`Profile`\n instances for a :class:`.ViewPanel` instance.\n\n A :class:`ProfileManager` instance is created and used by every\n :class:`.ViewPanel` instance. The :mod:`.profilemap` module defines the\n :class:`Profile` types which should used for specific :class:`.ViewPanel`\n types.\n ', '__init__': <function ProfileManager.__init__>, 'destroy': <function ProfileManager.destroy>, 'getCurrentProfile': <function ProfileManager.getCurrentProfile>, 'changeProfile': <function ProfileManager.changeProfile>, '__dict__': <attribute '__dict__' of 'ProfileManager' objects>, '__weakref__': <attribute '__weakref__' of 'ProfileManager' objects>})¶

__module__ = 'fsleyes.profiles'¶

__weakref__¶: list of weak references to the object (if defined)

class fsleyes.profiles.Profile(viewPanel, overlayList, displayCtx, modes=None)[source]¶

Bases: __main__.MockClass, fsleyes.actions.ActionProvider

A Profile class implements keyboard/mouse interaction behaviour for a ViewPanel instance.

Subclasses should specify at least one mode of operation, which defines a sort of sub-profile. The current mode can be changed with the mode property.

Subclasses must also override the getEventTargets() method, to return the wx objects that are to be the targets for mouse/keyboard interaction.

The Profile class currently only supports CanvasPanel and PlotPanel views. Profile instances use a CanvasPanelEventManager instance to manage GUI events on CanvasPanel instances, or a:class:.PlotPanelEventManager to manage GUI events on matplotlib Canvas objects.

Receiving events

In order to receive mouse or keyboard events, subclasses simply need to implement methods which handle the events of interest for the relevant mode, and name them appropriately. The name of a method handler must be of the form:

_[modeName]Mode[eventName]

where modeName is an identifier for the profile mode (see the __init__() method), and eventName is one of the following:

LeftMouseMove

LeftMouseDown

LeftMouseDrag

LeftMouseUp

RightMouseMove

RightMouseDown

RightMouseDrag

RightMouseUp

MiddleMouseMove

MiddleMouseDown

MiddleMouseDrag

MiddleMouseUp

MouseWheel

Char

Profiles for CanvasPanel views may also implement handlers for these events:

MouseEnter

MouseLeave

And PlotPanel views may implement handlers for these events:

LeftMouseArtistPick

RightMouseArtistPick

Note

The MouseEnter and MouseLeave events are not supported on PlotPanel views due to bugs in matplotlib.

For example, if a particular profile has defined a mode called nav, and is interested in left clicks, the profile class must provide a method called _navModeLeftMouseDown. Then, whenever the profile is in the nav mode, this method will be called on left mouse clicks.

Handler methods

The parameters that are passed to these methods differs slightly depending on the type of event:

All mouse events, with the exception of MouseWheel must have the following signature:
def _[modeName]Mode[eventName](ev, canvas, mouseLoc, canvasLoc)
where:

ev is the wx.Event object

canvas is the source canvas,

mouseLoc is the (x, y) mouse coordinates,

canvasLoc is the coordinates in the display/data coordinate system.
The MouseWheel handler must have the following signature:
def _[modeName]ModeMouseWheel(ev, canvas, wheel, mouseLoc, canvasLoc)
where wheel is a positive or negative number indicating how much the mouse wheel was moved.
Char events must have the following signature:
def _[modeName]ModeChar(ev, canvas, key)
where key is the key code of the key that was pressed.
Pick event handlers (only on PlotPanel views) must have the following signature:
def _[modeName]Mode[eventType](ev, canvas, artist, mouseLoc, canvasLoc)
where artist is the matplotlib artist that was picked.

All handler methods should return True to indicate that the event was handled, or False if the event was not handled. This is particularly important for Char event handlers - we don’t want Profile sub-classes to be eating global keyboard shortcuts. A return value of None is interpreted as True. If a handler returns False, and a fallback handler is defined (see below), then that fallback handler will be called.

Extra handlers

Additional handlers can be registered for any event type via the registerHandler() method. These handlers do not have to be methods of the Profile sub-class, and will be called for every occurrence of the event, regardless of the current mode. These handlers will be called after the standard handler method.

When an extra handler is no longer needed, it must be removed via the deregisterHandler() method.

Pre- and post- methods

A couple of other methods may be defined which, if they are present, will be called on all handled events:

_preEvent

_postEvent

The _preEvent method will get called just before an event is passed to the handler. Likewise, the _postEvent method will get called just after the handler has been called. If no handlers for a particular event are defined, neither of these methods will be called.

Temporary, alternate and fallback handlers

The profilemap module contains a set of dictionaries which define temporary, alternate, and fallback handlers.

The profilemap.tempModeMap defines, for each profile and each mod, a keyboard modifier which may be used to temporarily redirect mouse/keyboard events to the handlers for a different mode. For example, if while in nav mode, you would like the user to be able to switch to zoom mode with the control key, you can add a temporary mode map in the tempModeMap. Additional temporary modes can be added via the addTempMode() method.

The profilemap.altHandlerMap. dictionary allows you to re-use event handlers that have been defined for one mode in another mode. For example, if you would like right clicks in zoom mode to behave like left clicks in nav mode, you can set up such a mapping using the altHandlerMap dictionary. Additional alternate handlers can be added via the addAltHandler() method.

The profilemap.fallbackHandlerMap dictionary allows you to define fallback handlers - if the default handler for a specific mode/event type returns a value of False, the event will be forwarded to the fallback handler instead. Additional fallback handlers can be added via the addFallbackHandler() method.

Actions and attributes

As the Profile class derives from the ActionProvider class, Profile subclasses may define properties and actions for the user to configure the profile behaviour, and/or to perform any relevant actions.

The following instance attributes are present on a Profile instance, intended to be accessed by sub-classes:

`viewPanel`	The `ViewPanel` which is using this `Profile`.
`overlayList`	A `OverlayList` instance.
`displayCtx`	A `DisplayContext` instance.
`name`	A unique name for this `Profile` instance.

__init__(viewPanel, overlayList, displayCtx, modes=None)[source]¶

Create a Profile instance.

Parameters

viewPanel – The ViewPanel instance for which this Profile instance defines mouse/keyboard interaction behaviour.
overlayList – The OverlayList instance which contains the list of overlays being displayed.
displayCtx – The DisplayContext instance which defines how the overlays are to be displayed.
modes – A sequence of strings, containing the mode identifiers for this profile. These are added as options on the mode property.

mode = <MagicMock name='mock.Choice()' id='281473498355456'>¶: The current profile mode - by default this is empty, but subclasses may specify the choice options in the __init__ method.

__del__()[source]¶: Prints a log message.

destroy()[source]¶

This method must be called when this Profile is no longer needed - it is typically called by a ProfileManager.

Clears references to the display context, view panel, and overlay list, and calls ActionProvider.destroy().

property name¶: Returns the name of this Profile.

property viewPanel¶: Returns the ViewPanel associated with this Profile.

property _viewPanel¶

MagicMock is a subclass of Mock with default implementations of most of the magic methods. You can use MagicMock without having to configure the magic methods yourself.

If you use the spec or spec_set arguments then only magic methods that exist in the spec will be created.

Attributes and the return value of a MagicMock will also be MagicMocks.

property _name¶

MagicMock is a subclass of Mock with default implementations of most of the magic methods. You can use MagicMock without having to configure the magic methods yourself.

If you use the spec or spec_set arguments then only magic methods that exist in the spec will be created.

Attributes and the return value of a MagicMock will also be MagicMocks.

property _displayCtx¶

MagicMock is a subclass of Mock with default implementations of most of the magic methods. You can use MagicMock without having to configure the magic methods yourself.

If you use the spec or spec_set arguments then only magic methods that exist in the spec will be created.

Attributes and the return value of a MagicMock will also be MagicMocks.

property _overlayList¶

MagicMock is a subclass of Mock with default implementations of most of the magic methods. You can use MagicMock without having to configure the magic methods yourself.

If you use the spec or spec_set arguments then only magic methods that exist in the spec will be created.

Attributes and the return value of a MagicMock will also be MagicMocks.

getEventTargets()[source]¶: Must be overridden by subclasses, to return a sequence of wx objects that are the targets of mouse/keyboard interaction.

Note

It is currently assumed that all of the objects in the sequence derive from the SliceCanvas class.

getMouseDownLocation()[source]¶: If the mouse is currently down, returns a 2-tuple containing the x/y mouse coordinates, and the corresponding 3D display space coordinates, of the mouse down event. Otherwise, returns (None, None).

getLastMouseLocation()[source]¶: Returns a 2-tuple containing the most recent x/y mouse coordinates, and the corresponding 3D display space coordinates.

getLastMouseUpLocation()[source]¶: Returns a 2-tuple containing the most recent x/y mouse up event coordinates, and the corresponding 3D display space coordinates.

getLastMouseUpHandler()[source]¶: Returns a tuple of two strings specifying the (mode, eventType) of the most recent mouse up event that was handled. If no events have been handled, returns (None, None).

getLastHandler()[source]¶: Returns a tuple of two strings specifying the (mode, eventType) of the most recent event that was handled. If no events have been handled, returns (None, None).

getLastCanvas()[source]¶: Returns a reference to the canvas which most recently generated a mouse down or up event.

getMplEvent()[source]¶

If this Profile object is associated with a PlotPanel, this method will return the last matplotlib event that was generated. Otherwise, this method returns None.

This method can be called from within an event handler to retrieve the current matplotlib event. See the PlotPanelEventManager.getMplEvent() method.

addTempMode(mode, modifier, tempMode)[source]¶

Add a temporary mode to this Profile, in addition to those defined in the profilemap.tempModeMap dictionary.

Parameters

mode – The mode to change from.
modifier – A keyboard modifier which will temporarily change the mode from mode to tempMode.
tempMode – The temporary mode which the modifier key will change into.

addAltHandler(mode, event, altMode, altEvent)[source]¶

Add an alternate handler to this Profile, in addition to those already defined in the profilemap.altHandleMap dictionary.

Parameters

mode – The source mode.
event – Name of the event to handle (e.g. LeftMouseDown).
altMode – The mode for which the handler is defined.
altEvent – The event name for which the handler is defined.

addFallbackHandler(mode, event, fbMode, fbEvent)[source]¶

Add a fallback handler to this Profile, in addition to those already defined in the profilemap.fallbackHandleMap dictionary.

Parameters

mode – The source mode.
event – Name of the event to handle (e.g. LeftMouseDown).
fbMode – The mode for which the handler is defined.
fbEvent – The event name for which the handler is defined.

register()[source]¶

This method must be called to register this Profile instance as the target for mouse/keyboard events. This method is called by the ProfileManager.

Subclasses may override this method to performa any initialisation, but must make sure to call this implementation.

deregister()[source]¶

This method de-registers this Profile instance from receiving mouse/keybouard events. This method is called by the ProfileManager.

Subclasses may override this method to performa any initialisation, but must make sure to call this implementation.

registerHandler(event, name, handler)[source]¶

Add an extra handler for the specified event.

When the event occurs, The handler function will be called after the default handler, provided by the Profie sub-class, is called.

Parameters

event – The event type (e.g. LeftMouseDown).
name – A unique name for the handler. A KeyError will be raised if a handler with name is already registered.
handler – Function to call when the event occurs. See the class documentation for details on the required signature.

deregisterHandler(event, name)[source]¶

Remove an extra handler from the specified event, that was previously added via registerHandler()

Parameters

event – The event type (e.g. LeftMouseDown).
name – A unique name for the handler. A KeyError will be raised if a handler with name is already registered.

handleEvent(ev)[source]¶

Called by the event manager when any event occurs on any of the ViewPanel targets. Delegates the event to one of the handler functions.

Parameters: ev – The wx.Event that occurred.

handlePickEvent(ev)[source]¶: Called by the PlotPanelEventManager when a matplotlib pick_event occurs.

_Profile__getHandler(ev, evType, mode=None, origEvType=None, direct=False)¶

Returns a function which will handle the given wx.MouseEvent or wx.KeyEvent (the ev argument), or None if no handlers are found.

If an alternate handler for the mode/event has been specified, it is returned.

Parameters

ev – The event object
evType – The event type (e.g. 'LeftMouseDown')
mode – Override the default mode with this one. If not provided, the handler for the current mode (or temporary mode, if one is active) will be used.
origEvType – If the evType is not the actual event that occurred (e.g. this method has been called to look up an alternate or fallback handler), the original event type must be passed in here.
direct – If False (the default), the returned function will call the standard event handler (a method of the Profile sub-class), its fallback handler if it returns False and a fallback has been specfiied, any extra handlers that have been registered for the event type, and will also call the pre- and post- event methods. Otherwise, the returned function will just be the sub-class handler method for the specified for evType/ ``mode.

_Profile__getMode(ev)¶: Returns the current profile mode - either the value of mode, or a temporary mode if one is active.

_Profile__getMouseButton(ev)¶: Returns a string describing the mouse button associated with the given wx.MouseEvent.

_Profile__getMouseLocation(ev)¶

Returns two tuples; the first contains the x/y coordinates of the given wx.MouseEvent, and the second contains the corresponding x/y/z display space coordinates (for CanvasPanel views), or x/y data coordinates (for PlotPanel views).

See the CanvasPanelEventManager.getMouseLocation() and PlotPanelEventManager.getMouseLocation() methods.

_Profile__getTempMode(ev)¶: Checks the temporary mode map to see if a temporary mode should be applied. Returns the mode identifier, or None if no temporary mode is applicable.

_Profile__onChar(ev)¶

Called on keyboard key presses.