mantidqtpython_def.sip

/**************************************************************************/
/** This file is a SIP file for binding C++ methods of the MantidQt widgets
 *  to Python.
 */
/**************************************************************************/

%Include qwttypes.sip
%Include vector.sip
%Include string.sip

%ModuleHeaderCode
#include "MantidQtWidgets/Common/PythonSystemHeader.h"
#include "MantidQtWidgets/Common/WorkspaceObserver.h"
%End

%InitialisationCode
qRegisterMetaType<Mantid::API::Workspace_sptr>();
qRegisterMetaType<std::string>();
%End
/***************************************************************************/
/**************** Exceptions ***********************************************/
/***************************************************************************/

%Exception std::exception(SIP_Exception) /PyName=StdException/
{
%TypeHeaderCode
#include <stdexcept>
%End
%RaiseCode
    const char *detail = sipExceptionRef.what();

    SIP_BLOCK_THREADS
    PyErr_SetString(sipException_std_exception, detail);
    SIP_UNBLOCK_THREADS
%End
};

%Exception std::invalid_argument(SIP_Exception) /PyName=StdInvalidArgument/
{
%TypeHeaderCode
#include <stdexcept>
%End
%RaiseCode
    const char *detail = sipExceptionRef.what();

    SIP_BLOCK_THREADS
    PyErr_SetString(sipException_std_invalid_argument, detail);
    SIP_UNBLOCK_THREADS
%End
};

%Exception std::runtime_error(SIP_Exception) /PyName=StdRuntimeError/
{
%TypeHeaderCode
#include <stdexcept>
%End
%RaiseCode
    const char *detail = sipExceptionRef.what();

    SIP_BLOCK_THREADS
    PyErr_SetString(sipException_std_runtime_error, detail);
    SIP_UNBLOCK_THREADS
%End
};

namespace GraphOptions
{
%TypeHeaderCode
#include "MantidQtWidgets/Common/GraphOptions.h"
%End

  enum ScaleType {Linear, Log10};

  enum Axis{Left, Right, Bottom, Top};

  enum CurveType {
  Line,
  Scatter,
  LineSymbols,
  VerticalBars,
  Area,
  Pie,
  VerticalDropLines,
  Spline,
  HorizontalSteps,
  Histogram,
  HorizontalBars,
  VectXYXY,
  ErrorBars,
  Box,
  VectXYAM,
  VerticalSteps,
  ColorMap,
  GrayScale,
  ColorMapContour,
  Contour,
  Function,
  ImagePlot,
  User
};

};

namespace Mantid
{
namespace API
{

enum MDNormalization
{
//%TypeHeaderCode
//#include "../Framework/API/inc/MantidAPI/IMDWorkspace.h"
//%End
  NoNormalization,
  VolumeNormalization,
  NumEventsNormalization
};

}; // end namespace
}; // end namespace


namespace MantidQt
{
namespace API
{

class AlgorithmDialog : QDialog
{
%TypeHeaderCode
#include "MantidQtWidgets/Common/AlgorithmDialog.h"
%End
private:
  AlgorithmDialog();
};

class UserSubWindow : QMainWindow
{
%TypeHeaderCode
#include "MantidQtWidgets/Common/UserSubWindow.h"
%End
private:
  UserSubWindow();
};

class ManageUserDirectories : QDialog
{
%TypeHeaderCode
#include "MantidQtWidgets/Common/ManageUserDirectories.h"
%End
public:
    ManageUserDirectories();
    static void openUserDirsDialog(QWidget *parent);
};

class InterfaceManager
{
%TypeHeaderCode
#include "MantidQtWidgets/Common/InterfaceManager.h"
%End
public:
  MantidQt::API::AlgorithmDialog* createDialogFromName(const QString&, const int = -1,
                                                       QWidget* = 0, bool = false) throw(std::exception);
  MantidQt::API::UserSubWindow* createSubWindow(const QString& interface_name, QWidget* parent = 0);

  void showHelpPage(const QString & url=QString());

  void showWikiPage(const QString &page=QString());

  void showAlgorithmHelp(const QString &name, const int version=-1);

  void showConceptHelp(const QString &name);

  void showFitFunctionHelp(const QString &name=QString());

  void showCustomInterfaceHelp(const QString &name);
};

class MantidDesktopServices
{
%TypeHeaderCode
#include "MantidQtWidgets/Common/MantidDesktopServices.h"
%End
public:
  static bool openUrl(const QUrl &url);
  static void setUrlHandler(const QString &scheme, QObject *receiver,
                            const char *method);
  static void unsetUrlHandler(const QString &scheme);
};

};

namespace API
{

class MWRunFiles : QWidget
{
%TypeHeaderCode
#include "MantidQtWidgets/Common/MWRunFiles.h"
%End
public:
void setLabelMinWidth(const int);
void liveButtonSetChecked(bool);
bool liveButtonIsChecked();
QString getText() /PyName=text/;
bool isValid();
void setUserInput(const QVariant &);
void setText(const QString&);
signals:
void fileFindingFinished();
void liveButtonPressed(bool);
};

};

namespace SliceViewer
{

//*WIKI* == Classes ==
//*WIKI* Here follows a list of the classes exposed to python and the methods you can execute on them.


/***************************************************************************/
/***************************************************************************/
/***************************************************************************/
class SliceViewerWindow : QMainWindow
{
%TypeHeaderCode
#include "MantidQtWidgets/SliceViewer/SliceViewerWindow.h"
%End
%Docstring

SliceViewerWindow
=================

    The SliceViewerWindow is a window containing a SliceViewer widget
    and a LineViewer Widget.

    It allows you to look at 2D slices in a workspace such as a
    MDEventWorkspace or a MDHistoWorkspace, and then perform 1D line
    sections.

    You can access the two contained widgets using:
        getSlicer() (for the SliceViewer)
        getLiner() (for the LineViewer)

    However, the methods of the SliceViewer are exposed to the
    SliceViewerWindow, so you do not need to get the SliceViewer
    widget directly; you can call the methods on the SliceViewerWindow
    directly. For example:

       svw.setSlicePoint(2, 10.5)

    See the methods for SliceViewer, below.

%End

public:
  SliceViewerWindow(const QString& wsName, const QString& label, Qt::WindowFlags f);
  MantidQt::SliceViewer::SliceViewer* getSlicer();
%Docstring
MantidQt::SliceViewer::SliceViewer* SliceViewerWindow::getSlicer()
------------------------------------------------------------------
    Get the SliceViewer widget inside the SliceViewerWindow.
    This is the main widget for controlling the 2D views
    and slice points.

    Returns:
        a pointer to the SliceViewer widget.

%End

  MantidQt::SliceViewer::LineViewer* getLiner();
%Docstring
MantidQt::SliceViewer::LineViewer* SliceViewerWindow::getLiner()
----------------------------------------------------------------
    Get the LineViewer widget inside the SliceViewerWindow.
    This is the widget for controlling the 1D line integration
    settings.

    Returns:
        a pointer to the LineViewer widget.

%End

  const QString& getLabel() const;

};

/***************************************************************************/
/***************************************************************************/
/***************************************************************************/
class LineViewer : QWidget
{
%TypeHeaderCode
#include "MantidQtWidgets/SliceViewer/LineViewer.h"
%End

%Docstring

LineViewer
==========

    The LineViewer is a widget to select 1D line sections out of
    a workspace such as the MDEventWorkspace or a MDHistoWorkspace.

    It is connected to the SliceViewer.

%End

public:

void apply()   throw (std::runtime_error);
%Docstring
void LineViewer::apply()
------------------------
    Perform the 1D integration using the current parameters.

    Raises:
        std::runtime_error if an error occurs.

%End

void showPreview();
%Docstring
void LineViewer::showPreview()
------------------------------
    Calculate and show the preview (non-integrated) line,
    using the current parameters.
%End

void showFull();
%Docstring
void LineViewer::showFull()
---------------------------
    Calculate and show the full (integrated) line, using the latest
    integrated workspace. The apply() method must have been called
    before calling this.
%End


//*WIKI* ==== Start/End Points ====
void setStartXY(double x, double y)   throw (std::runtime_error);
%Docstring
void LineViewer::setStartXY(double x, double y)
-----------------------------------------------
    Set the start point of the line to integrate

    Args:
        x :: position of the start in the "X" dimension
           (as shown in the SliceViewer).
        y :: position of the start in the "Y" dimension
           (as shown in the SliceViewer).

%End

void setEndXY(double x, double y)   throw (std::runtime_error);
%Docstring
void LineViewer::setEndXY(double x, double y)
---------------------------------------------
    Set the start point of the line to integrate

    Args:
        x :: position of the start in the "X" dimension
           (as shown in the SliceViewer).
        y :: position of the start in the "Y" dimension
           (as shown in the SliceViewer).

%End


//*WIKI* ==== Width ====
void setThickness(double width);
%Docstring
void LineViewer::setThickness(double width)
-------------------------------------------
    Set the thickness to integrate to be the same in all dimensions

    This sets the planar width and all the other dimensions' thicknesses
    to the same value.

    Args:
        width :: width of integration, in the units of all dimensions

%End

void setThickness(int dim, double width)   throw (std::invalid_argument, std::runtime_error);
%Docstring
void LineViewer::setThickness(int dim, double width)
----------------------------------------------------
    Set the thickness to integrate in a particular dimension.

    Integration is performed perpendicular to the XY plane,
    from -0.5 * thickness below to +0.5 * thickness above the center.

    Use setPlanarWidth() to set the width along the XY plane.

    Args:
        dim :: index of the dimension to change
        width :: width of integration, in the units of the dimension.

    Raises:
        std::invalid_argument if the index is invalid

%End

void setThickness(const QString & dim, double width)   throw (std::invalid_argument, std::runtime_error);
%Docstring
void LineViewer::setThickness(const QString & dim, double width)
----------------------------------------------------------------
    Set the thickness to integrate in a particular dimension.

    Integration is performed perpendicular to the XY plane,
    from -0.5 * thickness below to +0.5 * thickness above the center.

    Use setPlanarWidth() to set the width along the XY plane.

    Args:
        dim :: name of the dimension to change
        width :: thickness of integration, in the units of the dimension.

    Raises:
        std::runtime_error if the name is not found in the workspace

%End

void setPlanarWidth(double width);
%Docstring
void LineViewer::setPlanarWidth(double width)
---------------------------------------------
    Set the width of the line in the planar dimension only.
    Other dimensions' widths will follow unless they were manually changed

    Args:
        width :: width in the plane.
%End

double getPlanarWidth() const;
%Docstring
double LineViewer::getPlanarWidth()
-----------------------------------

    Returns:
        the width in the plane, or the width in dimension 0 if not restricted to a plane
%End


//*WIKI* ==== Binning ====
void setNumBins(int numBins)   throw (std::invalid_argument);
%Docstring
void LineViewer::setNumBins(int numBins)
----------------------------------------
    Set the number of bins in the line.

    Args:
        numBins :: # of bins

    Raises:
        std::invalid_argument if numBins < 1

%End

void setFixedBinWidthMode(bool fixedWidth, double binWidth)   throw (std::invalid_argument);
%Docstring
void LineViewer::setFixedBinWidthMode(bool fixedWidth, double binWidth)
-----------------------------------------------------------------------
    Sets the fixed bin width mode on or off.

    In fixed bin width mode, the width of each bin along the line length
    is constant, and the number of bins is adjusted to as the line
    gets longer.
    If off, then you use a fixed number of bins, and the bin width is
    then simply: width = length / number_of_bins.

    Args:
        fixedWidth :: if True, then keep the bin width fixed.
        binWidth :: for fixed bin width mode, this specified the desired
           bin width. Must be > 0. Ignored for non-fixed-bin-width mode.

    Raises:
        std::invalid_argument if binWidth <= 0

%End

double getFixedBinWidth() const;
%Docstring
double LineViewer::getFixedBinWidth()
-------------------------------------
    For fixed-bin-width mode, get the desired fixed bin width.

    Returns:
        the desired fixed bin width

%End

bool getFixedBinWidthMode() const;
%Docstring
bool LineViewer::getFixedBinWidthMode()
---------------------------------------
    Is the LineViewer in fixed-bin-width mode?

    Returns:
        True if in fixed bin width mode.

%End

int getNumBins() const;
%Docstring
int LineViewer::getNumBins()
----------------------------
    Get the number of bins

    Returns:
        the number of bins in the line to integrate (int)

%End

double getBinWidth() const;
%Docstring
double LineViewer::getBinWidth()
--------------------------------
    Get the width of each bin

    Returns:
        the width of each bin (double)

%End

int getXAxisDimensionIndex() const;
%Docstring
int LineViewer::getXAxisDimensionIndex()
--------------------------------
    Get the index of the dimension used for the x axis

    Returns:
        the index of the dimension used for the x axis (int)

%End


////*WIKI* ==== Plotting ====
void setPlotAxis(int choice);
%Docstring
void LineViewer::setPlotAxis(int choice)
----------------------------------------
    Choose which coordinates to use as the X axis to plot in the line view.

    Args:
        choice :: PlotAxisChoice, either Auto, X, Y or Distance.

%End

int getPlotAxis() const;
%Docstring
int LineViewer::getPlotAxis()
-----------------------------
    Return which coordinates to use as the X axis to plot in the line view.

    Returns:
        PlotAxisChoice, either Auto, X, Y or Distance.

%End


};

/***************************************************************************/
/***************************************************************************/
/***************************************************************************/
class PeaksPresenter : QObject
{
%TypeHeaderCode
#include "MantidQtWidgets/SliceViewer/PeaksPresenter.h"
%End

%Docstring

PeaksPresenter
===========
    This is a controlling unit for PeaksWorkspace displayed in the PeaksOverlay of the SliceViewer.
%End

private:
    PeaksPresenter();
    PeaksPresenter(const MantidQt::SliceViewer::PeaksPresenter&);
public:
    virtual void setForegroundColor(const QColor) = 0;
%Docstring
void PeaksPresenter::setForegroundColor(const QColor color)
-----------------------------------------------------------
    Sets the Foreground color of the peaks workspace as displayed in the peaks overlay.

    Args:
        color :: color to change foreground to
%End
    virtual void setBackgroundColor(const QColor) = 0;
%Docstring
void PeaksPresenter::setBackgroundColor(const QColor color)
-----------------------------------------------------------
    Sets the Background color of the peaks workspace as displayed in the peaks overlay.

    Args:
        color :: color to change background to
%End
    virtual void showBackgroundRadius(const bool shown) = 0;
%Docstring
void PeaksPresenter::showBackgroundRadius(const bool shown)
-----------------------------------------------------------
    Toggle the background radius on and off.

    Args:
        shown :: True to show the background radius, otherwise false.
%End
    virtual void setShown(const bool shown) = 0;
%Docstring
void PeaksPresenter::setShown(const bool shown)
-----------------------------------------------
    Toggle the overplotted state of this PeaksWorkspace in the PeaksOverlay

    Args:
        shown :: True to show. False to hide.
%End
    virtual void zoomToPeak(const int index) = 0;
%Docstring
void PeaksPresenter::zoomToPeak(const int index)
------------------------------------------------------
    Zoom in on a peak of the PeaksWorkspace. Provide an index (0 based) to go to the peak.

    Args:
        index :: Index into the peaks workspace (0 based) to zoom to.
%End
};

/***************************************************************************/
/***************************************************************************/
/***************************************************************************/
class ProxyCompositePeaksPresenter :  QObject
{
%TypeHeaderCode
#include "MantidQtWidgets/SliceViewer/ProxyCompositePeaksPresenter.h"
#include "MantidQtWidgets/SliceViewer/PeaksPresenter.h"
%End
private:
    ProxyCompositePeaksPresenter();
    ProxyCompositePeaksPresenter(const MantidQt::SliceViewer::ProxyCompositePeaksPresenter&);
public:
  MantidQt::SliceViewer::PeaksPresenter* getPeaksPresenter(const QString& name);
};


/***************************************************************************/
/***************************************************************************/
/***************************************************************************/
class SliceViewer : QWidget
{
%TypeHeaderCode
#include "MantidQtWidgets/SliceViewer/SliceViewer.h"
%End

%Docstring

SliceViewer
===========

    The SliceViewer is a widget showing a 2D slice of a multi-dimensional
    workspace such as the MDEventWorkspace or a MDHistoWorkspace.

%End

public:
  //*WIKI* ==== Basics ====
  void setWorkspace(const QString & wsName)   throw (std::runtime_error);
%Docstring
void SliceViewer::setWorkspace(const QString & wsName)
------------------------------------------------------
    Set the workspace to view using its name.
    The workspace should be a MDHistoWorkspace or a MDEventWorkspace,
    with at least 2 dimensions.

    Args:
        wsName :: name of the MDWorkspace to look for

    Raises:
        std::runtime_error if the workspace is not found or is a MatrixWorkspace

%End

  QString getWorkspaceName() const;
%Docstring
QString SliceViewer::getWorkspaceName()
---------------------------------------

    Returns:
        the name of the workspace selected, or a blank string
    if no workspace is set.

%End

  void showControls(bool visible);
%Docstring
void SliceViewer::showControls(bool visible)
--------------------------------------------
    Programmatically show/hide the controls (sliders etc)

    Args:
        visible :: true if you want to show the controls.

%End

  void openFromXML(const QString & xml)   throw (std::invalid_argument, std::runtime_error);
%Docstring
void SliceViewer::openFromXML(const QString & xml)
--------------------------------------------------
    Opens a workspace and sets the view and slice points
    given the XML from the MultiSlice view in XML format.

    Args:
        xml :: string describing workspace, slice point, etc.

    Raises:
        std::runtime_error if error in parsing XML

%End

  QPixmap getImage();
%Docstring
QPixmap SliceViewer::getImage()
-------------------------------
    Grab the 2D view as an image. The image is rendered at the current window
    size, with the color scale but without the text boxes for changing them.

    See also saveImage() and copyImageToClipboard()

    Returns:
        QPixmap containing the image.

%End

  void saveImage(const QString & filename);
%Docstring
void SliceViewer::saveImage(const QString & filename)
-----------------------------------------------------
    Save the rendered 2D slice to an image file.

    Args:
        filename :: full path to the file to save, including extension
           (e.g. .png). If not specified or empty, then a dialog will prompt
           the user to pick a file.

%End

  void copyImageToClipboard();
%Docstring
void SliceViewer::copyImageToClipboard()
----------------------------------------
    Copy the rendered 2D image to the clipboard

%End

  void setFastRender(bool fast);
%Docstring
void SliceViewer::setFastRender(bool fast)
------------------------------------------
    Sets whether the image should be rendered in "fast" mode, where
    the workspace's resolution is used to guess how many pixels to render.

    If false, each pixel on screen will be rendered. This is the most
    accurate view but the slowest.

    This redraws the screen.

    Args:
        fast :: true to use "fast" rendering mode.

%End

  bool getFastRender() const;
%Docstring
bool SliceViewer::getFastRender()
---------------------------------
    Return true if the image is in "fast" rendering mode.

    In "fast" mode, the workspace's resolution is used to guess how many
    pixels to render. If false, each pixel on screen will be rendered.
    This is the most accurate view but the slowest.

    Returns:
        True if the image is in "fast" rendering mode.

%End

  void toggleLineMode(bool lineMode);
%Docstring
void SliceViewer::toggleLineMode(bool lineMode)
-----------------------------------------------
    Toggle "line-drawing" mode (to draw 1D lines using the mouse)

    Args:
        lineMode :: True to go into line mode, False to exit it.

%End


  //*WIKI* ==== X/Y Dimension ====
  void setXYDim(int indexX, int indexY)     throw (std::invalid_argument);
%Docstring
void SliceViewer::setXYDim(int indexX, int indexY)
--------------------------------------------------
    Set the index of the dimensions that will be shown as
    the X and Y axis of the plot.
    You cannot set both axes to be the same.

    To be called from Python, primarily.

    Args:
        indexX :: index of the X dimension, from 0 to NDims-1.
        indexY :: index of the Y dimension, from 0 to NDims-1.

    Raises:
        std::invalid_argument if an index is invalid or repeated.

%End

  void setXYDim(const QString & dimX, const QString & dimY)     throw (std::invalid_argument, std::runtime_error);
%Docstring
void SliceViewer::setXYDim(const QString & dimX, const QString & dimY)
----------------------------------------------------------------------
    Set the dimensions that will be shown as the X and Y axes

    Args:
        dimX :: name of the X dimension. Must match the workspace dimension names.
        dimY :: name of the Y dimension. Must match the workspace dimension names.

    Raises:
        std::runtime_error if the dimension name is not found.

%End

  int getDimX() const;
%Docstring
int SliceViewer::getDimX()
--------------------------

    Returns:
        the index of the dimension that is currently
    being shown as the X axis of the plot.

%End

  int getDimY() const;
%Docstring
int SliceViewer::getDimY()
--------------------------

    Returns:
        the index of the dimension that is currently
    being shown as the Y axis of the plot.

%End


  //*WIKI* ==== Slice Point ====
  void setSlicePoint(int dim, double value)     throw (std::invalid_argument);
%Docstring
void SliceViewer::setSlicePoint(int dim, double value)
------------------------------------------------------
    Sets the slice point in the given dimension:
    that is, what is the position of the plane in that dimension

    Args:
        dim :: index of the dimension to change
        value :: value of the slice point, in the units of the given dimension.
           This should be within the range of min/max for that dimension.

    Raises:
        std::invalid_argument if the index is invalid

%End

  void setSlicePoint(const QString & dim, double value)   throw (std::invalid_argument, std::runtime_error);
%Docstring
void SliceViewer::setSlicePoint(const QString & dim, double value)
------------------------------------------------------------------
    Sets the slice point in the given dimension:
    that is, what is the position of the plane in that dimension

    Args:
        dim :: name of the dimension to change
        value :: value of the slice point, in the units of the given dimension.
           This should be within the range of min/max for that dimension.

    Raises:
        std::runtime_error if the name is not found in the workspace

%End

  double getSlicePoint(int dim) const     throw (std::invalid_argument);
%Docstring
double SliceViewer::getSlicePoint(int dim)
------------------------------------------
    Returns the slice point in the given dimension

    Args:
        dim :: index of the dimension

    Returns:
        slice point for that dimension. Value has no significance for the
            X or Y display dimensions.

    Raises:
        std::invalid_argument if the index is invalid

%End

  double getSlicePoint(const QString & dim) const   throw (std::invalid_argument, std::runtime_error);
%Docstring
double SliceViewer::getSlicePoint(const QString & dim)
------------------------------------------------------
    Returns the slice point in the given dimension

    Args:
        dim :: name of the dimension

    Returns:
        slice point for that dimension. Value has no significance for the
            X or Y display dimensions.

    Raises:
        std::runtime_error if the name is not found in the workspace

%End


  //*WIKI* ==== View Limits ====
  void setXYLimits(double xleft, double xright, double ybottom, double ytop);
%Docstring
void SliceViewer::setXYLimits(double xleft, double xright, double ybottom, double ytop)
---------------------------------------------------------------------------------------
    Set the limits in X and Y to be shown in the plot.
    The X and Y values are in the units of their respective dimensions.
    You can change the mapping from X/Y in the plot to specific
    dimensions in the displayed workspace using setXYDim().

    You can flip the direction of the scale if you specify,
    e.g., xleft > xright.

    Args:
        xleft   :: x-value on the left side of the graph
        xright  :: x-value on the right side of the graph
        ybottom :: y-value on the bottom of the graph
        ytop    :: y-value on the top of the graph

%End

  QwtDoubleInterval getXLimits() const;
%Docstring
QwtDoubleInterval SliceViewer::getXLimits()
-------------------------------------------

    Returns:
        Returns the [left, right] limits of the view in the X axis.
%End

  QwtDoubleInterval getYLimits() const;
%Docstring
QwtDoubleInterval SliceViewer::getYLimits()
-------------------------------------------

    Returns:
        Returns the [bottom, top] limits of the view in the Y axis.
%End

  void zoomBy(double factor);
%Docstring
void SliceViewer::zoomBy(double factor)
---------------------------------------
    Zoom in or out, keeping the center of the plot in the same position.

    Args:
        factor :: double, if > 1 : zoom in by this factor.
                     if < 1 : it will zoom out.

%End

  void setXYCenter(double x, double y);
%Docstring
void SliceViewer::setXYCenter(double x, double y)
-------------------------------------------------
    Manually set the center of the plot, in X Y coordinates.
    This keeps the plot the same size as previously.
    Use setXYLimits() to modify the size of the plot by setting the X/Y edges,
    or you can use zoomBy() to zoom in/out

    Args:
        x :: new position of the center in X
        y :: new position of the center in Y

%End

  void resetZoom();