7.2. pyopus.wxmplplot.wxmgr — Manager for Matplotlib plot windows

Manager for Matplotlib plot windows

Uses the multiprocessing module if it is available. If not, threading is used.

The graphical part (wxPython + matplotlib) is running in a thread (or process if multiprocessing is used) and the part that issues the plotting commands (defined in the plotitf module) runs in the main thread (or process).

The main thread uses a GUIControl object for sending and receiving messages from the graphical thread. The messages are sent yo the GUI using a Queue object. On the graphical thread’s side a ControlApp application is running. The main window of the application is a ControlWindow object. Commands to the GUI are sent by posting ControlEvent events to the ControlApp.

The ControlEvent handler in ControlApp calls the ControlWindow.InterpretCommand() method that dispatches the message to the corresponding command handler.

class pyopus.wxmplplot.wxmgr.GUIControl(redirect=False)

This object is used in the main thread (or process) for sending the plot commands to the graphical thread. It can also collect the value returned by the functions called by the graphical thread for every command sent.

If redirect is True all output from stdout and stderr is redirected to a window that pops up when needed. redirect is passed to the constructor of wx.App.

CheckIfAlive()

Returns True if the graphical thread (or process) is running.

Join()

Waits for the GUI thread to finish.

KeyboardInterrupt and SystemExit are caught and the GUI is stopped upon which the exception is re-raised.

Lock()

Marks the beginning of a section of code where Matplotlib API calls are made. Locking prevents these calls from interfering with the wxPython event loop and crashing the application.

SendMessage(message)

Sends a message (Python object) to the graphical thread.

Collects the return value of the executed graphical command and returns it.

Returns None if talkback is disabled. This is also the case if the graphical thread is not running.

StartGUI()

Starts the graphical thread. The thread entry point is the GUIentry() function.

StopGUI()

Stops the graphical thread by sending it the ['plot', 'exit'] command.

UnLock()

Marks the end of a section of code where Matplotlib API calls are made. It reenables the wxPython event loop.

pyopus.wxmplplot.wxmgr.GUIentry(queueFromGUI, lock, redirect)

Entry point of the GUI thread.

This function creates a ControlApp object and starts the GUI application’s main loop. queueFromGUI is the queue that is used for returning values from the GUI. Commands are sent to the GUI by posting events to the ControlApp object.

If set to True redirect redirects stdout and stderr to a window that pops up when needed. redirect is passed to the constructor of wx.App.

class pyopus.wxmplplot.wxmgr.ControlApp(title='GUI Control App', responseQueue=None, lock=None, **kwds)

This is the GUI control application that will run in the GUI thread.

The commands are posted as ControlEvent events. Responses are sent back through the responseQueue.

Any additional arguments are passed to the constructor of wx.App.

ControlWindow()

Returns the ControlWindow object.

OnControlEvent(evt)

Handles a ControlEvent event.

For every event it calls the InterpretCommand() method of the ControlWindow object. If response is requested the return value of the InterpretCommand() method is sent back by pickling it and putting it in the responseQueue.

OnInit()

Called automatically when the control GUI application starts.

Initializes the main GUI control window and makes it the top window. Associates the OnControlEvent() method with ControlEvent events.

ProcessMessage(message)

This is the function that is invoked for every command that is sent to the GUI. It posts a ControlEvent event to ControlApp.

class pyopus.wxmplplot.wxmgr.ControlWindow(parent, title, lock)

This is the main GUI ControlWindow and command dispatcher.

parent is the parent window. title is the window title.

lock is the Lock object that prevents other threads from messing up Matplotlib objects while wxPython events are processed.

CloseAllPlotWindows()

Handles the ['plot', 'closeall'] command.

Closes all plot windows.

ClosePlotWindow(tag=None)

Handles the ['plot', 'close'] command.

Closes a plot window with given tag.

Returns True on success.

ExitInterpreter()

Handles the ['plot', 'exit'] command.

Exits the interpreter (thread or process).

FigureAlive(tag)

Returns True if figure tag is alive (i.e. window is not closed).

FigureDraw(tag)

Redraws the figure tag immediately.

If tag is not alive doesn’t do anything.

InitInterpreter()

Initializes the interpreter command tables.

Every command is a list of strings. The first string specifies the command group and the second string the command. Currently only one command group is available (plot).

Every command is passed an args tuple of positional arguments and a kwargs dictionary of keyword arguments.

Every plot window is actually a PlotFrame object displaying a Matplotlib Figure. Every plot window is associated with a tag at its creation. A tag is a hashable object (usually a string). If not tag is specified at creation a tag is assigned automatically.

Every Matplotlib Figure can have multiple Axes. Every axes represent a part of the figure where plotting takes place within the coordinate system of the Axes. Every axes in a figure are associated with a numeric tag in a similar way as every plot window has its tag. Axes tags are unique because they cannot be assigned by the user.

Tags should be unique. If a duplicate figure tag occurs that older figure with that tag becomes inaccessible.

The plot command group has the following commands:

• exit - exits the interpreter
• updatercparams - update the rc parameters with the given dictionary
• new - create a new plot window and return its tag
• close - close a plot window
• closeall - close all plot windows
• setwindowtitle - sets the title of a plot window
• show - show or hide aplot window
• raise - raise a plot window
• savefigure - saves the contents of a figure to a file

InterpretCommand(command, args=[], kwargs={})

Interprets the command given by the command list of strings. The first string is the command family and the second string is the command. Currently only one command family is available (plot).

The arguments to the command are given by args and kwargs.

The command handlers are given in handler dictionaries with command name for key. The handler dictionary for the plot command family is is the plot_cmdtab member.

Every command is handled in a try-except block If an error occurs during command execution the error is displayed in the command window.

The return value of the command handler is returned.

This method is invoked by the ControlApp on every ControlEvent. The contents of the event specify the command, the arguments and a talkback flag which is True if the return value of the command handler should be sent back to the main thread (process).

NewPlotWindow(windowTitle='Untitled', show=True, inFront=True, **kwargs)

Handles the ['plot', 'new'] command.

windowTitle is the title string for the plot window.

If show is True the window becomes visible immediately after it is created.

If inFront is True the window is created atop of all other windows.

All remaining arguments are passed on to the constructor of the PlotFrame object.

Returns the plot window’s Figure object or None on failure.

OnChildClosed(evt)

Called when a child (plot window) receives a close event.

OnClose(evt)

Event handler for EVT_CLOSE

OnCloseAll(evt)

Event handler for the menu option ‘Close all plots’.

OnDestroy(evt)

Event handler for EVT_WINDOW_DESTROY.

OnExit(evt)

Event handler for the menu option ‘Exit’.

OnNewPlot(evt)

Event handler for the menu option ‘New plot’.

OutputMessage(msg, colour=(0, 0, 0), bgcolour=(255, 255, 255), fontfamily=74)

Displays a message given by msg in the control window. The message colour and background colour are specified with the colour and bgcolour arguments (tuples of RGB values between 0 and 255).

fontfamily specifies the font family for the message.

RaisePlotWindow(tag)

Handles the ['plot', 'raise'] command.

Raises a plot window with given tag.

Returns True on success.

SaveFigure(tag, fileName)

Handles the ['plot', 'savefigure'] command.

Saves the contents of a plot window with given tag to a file with a name given by fileName. File type is determined from the extension in the fileName.

See the FigureCanvasWxAgg.print_figure() method. The available file types are listed in the FigureCanvasWxAgg.filetypes dictionary.

Returns True on success.

SetPlotWindowTitle(tag, title)

Handles the ['plot', 'setwindowtitle'] command.

Sets the window title of the active plot window.

Returns True on success.

ShowPlotWindow(tag, on=True)

Handles the ['plot', 'show'] command.

Shows (on set to True) or hides a plot window.

Returns True on success.

UpdateRCParams(dict)

Handles the ['plot', 'updatercparams'] command.

Update the rcParams structure of Matplotlib with the given dictionary. Returns True on success.

class pyopus.wxmplplot.wxmgr.ControlEvent(id, message)

Control event for the ControlApp’s main window.

The event carries a message.

id is the identifier associated with the event.

Clone()

Creates a clone of the ControlEvent object.

pyopus.wxmplplot.wxmgr.EVT_CONTROL(win, id, func)

Register to receive ControlEvent events from a ControlApp. The events originating from win are to be handled by function func.

id is the identifier to be associated with the event.

pyopus.wxmplplot.wxmgr.EVT_CONTROL_ID = 116

The wxPyhton identifier of a ControlEvent event.

pyopus.wxmplplot.wxmgr.CONTROL_MSG = 117

The wxPyhton identifier of a message sender carried by a ControlEvent event.