Abstract Classes

C++ SDK API Documentation - Abstract Classes

class AbstractAspect : public QObject

Base class of all persistent objects in a Project.

Before going into the details, it’s useful to understand the ideas behind the Aspect Framework.

Aspects organize themselves into trees, where a parent takes ownership of its children. Usually, though not necessarily, a Project instance will sit at the root of the tree (without a Project ancestor, project() will return 0 and undo does not work). Children are organized using addChild(), removeChild(), child(), indexOfChild() and childCount() on the parent’s side as well as the equivalent convenience methods index() and remove() on the child’s side. In contrast to the similar feature of QObject, Aspect trees are fully undo/redo aware and provide signals around object adding/removal.

AbstractAspect manages for every Aspect the properties name, comment, captionSpec and creationTime. All of these translate into the caption() as described in the documentation of setCaptionSpec().

If an undoStack() can be found (usually it is managed by Project), changes to the properties as well as adding/removing children support multi-level undo/redo. In order to support undo/redo for problem-specific data in derived classes, make sure that all changes to your data are done by handing appropriate commands to exec().

Subclassed by AbstractColumn, AbstractFilter, AbstractPart, Background, DatapickerCurve, DatapickerPoint, ErrorBar, Folder, Line, Symbol, Value, WorksheetElement

undo related

void setSelected(bool)

this function is called when the selection in ProjectExplorer was changed. forwards the selection/deselection to the parent aspect via emitting a signal.

virtual QUndoStack *undoStack() const

Return the undo stack of the Project, or 0 if this Aspect is not part of a Project.

It’s also possible to construct undo-enabled Aspect trees without Project. The only requirement is that the root Aspect reimplements undoStack() to get the undo stack from somewhere (the default implementation just delegates to parentAspect()).

void exec(QUndoCommand*)

Execute the given command, pushing it on the undoStack() if available.

void exec(QUndoCommand *command, const char *preChangeSignal, const char *postChangeSignal, QGenericArgument val0 = QGenericArgument(), QGenericArgument val1 = QGenericArgument(), QGenericArgument val2 = QGenericArgument(), QGenericArgument val3 = QGenericArgument())

Execute command and arrange for signals to be sent before/after it is redone or undone.

• command The command to be executed.

• preChangeSignal The name of the signal to be triggered before re-/undoing the command.

• postChangeSignal The name of the signal to be triggered after re-/undoing the command.

• val0,val1,val2,val3 Arguments to the signals; to be given using Q_ARG().

Signal arguments are given using the macro Q_ARG(typename, const value&). Since the variable given as “value” will likely be out of scope when the signals are emitted, a copy needs to be created. This uses QMetaType, which means that (non-trivial) argument types need to be registered using qRegisterMetaType() before giving them to exec() (in particular, this also goes for pointers to custom data types).

See also

SignallingUndoCommand

void beginMacro(const QString &text)

Begin an undo stack macro (series of commands)

void endMacro()

End the current undo stack macro.

static QString uniqueNameFor(const QString &name, const QStringList &names)

static helper function that makes the string name unique and avoids duplicates in the list of strings names.

serialize/deserialize

virtual void save(QXmlStreamWriter*) const = 0

Save as XML.

virtual bool load(XmlStreamReader*, bool preview) = 0

Load from XML.

XmlStreamReader supports errors as well as warnings. If only warnings (non-critical errors) occur, this function must return the reader at the end element corresponding to the current element at the time the function was called.

This function is normally intended to be called directly after the ctor. If you want to call load on an aspect that has been altered, you must make sure beforehand that it is in the same state as after creation, e.g., remove all its child aspects.

Returns:

false on error

Public Types

enum class ChildIndexFlag

Flags which control numbering scheme of children.

Values:

enumerator IncludeHidden

Include aspects marked as “hidden” in numbering or listing children.

enumerator Recursive

Recursively handle all descendents, not just immediate children.

enumerator Compress

Remove all null pointers from the result list.

Public Functions

virtual Project *project()

Return the Project this Aspect belongs to, or 0 if it is currently not part of one.

virtual QString path() const

Return the path that leads from the top-most Aspect (usually a Project) to me.

void setHidden(bool)

Set “hidden” property, i.e. whether to exclude this aspect from being shown in the explorer.

void setFixed(bool)

Set “fixed” property which defines whether the object can be renamed, deleted, etc.

virtual QIcon icon() const

Return an icon to be used for decorating my views.

virtual QMenu *createContextMenu()

Return a new context menu.

The caller takes ownership of the menu.

AbstractAspect *parentAspect() const

Return my parent Aspect or 0 if I currently don’t have one.

AbstractAspect *parent(AspectType) const

In the parent-child hierarchy, return the first parent of type.

Parameters:

type – or null pointer if there is none.

Folder *folder()

Return the folder the Aspect is contained in or 0 if there is none.

The returned folder may be the aspect itself if it inherits Folder.

bool isDescendantOf(AbstractAspect *other)

Return whether the there is a path upwards to the given aspect.

This also returns true if other==this.

void addChild(AbstractAspect*, QUndoCommand *parent = nullptr)

Add the given Aspect to my list of children.

void addChildFast(AbstractAspect*)

Add the given Aspect to my list of children without any checks and without putting this step onto the undo-stack.

void insertChildBefore(AbstractAspect *child, AbstractAspect *before, QUndoCommand *parent = nullptr)

Insert the given Aspect at a specific position in my list of children.

void insertChildBeforeFast(AbstractAspect *child, AbstractAspect *before)

Insert the given Aspect at a specific position in my list of children.without any checks and without putting this step onto the undo-stack.

void reparent(AbstractAspect *newParent, int newIndex = -1)

Move a child to another parent aspect and transfer ownership.

void removeChild(AbstractAspect*, QUndoCommand *parent = nullptr)

removeChild Removing child aspect using an undo command

Remove the given Aspect from my list of children.

The ownership of the child is transferred to the undo command, i.e., the aspect is deleted by the undo command.

See also

reparent()

Parameters:

parent – If parent is not nullptr the command will not be executed, but the parent must be executed to indirectly execute the created undocommand

void removeAllChildren()

Remove all child Aspects.

virtual QVector<AbstractAspect*> dependsOn() const

returns the list of all parent aspects (folders and sub-folders)

virtual QVector<AspectType> pasteTypes() const

return the list of all aspect types that can be copy&pasted into the current aspect. returns an empty list on default, needs to be re-implemented in all derived classes that want to allow other aspects to be pasted into.

template<class T>
inline T *ancestor() const

Return the closest ancestor of class T (or NULL if none found).

template<class T>
inline T *child(const QString &name) const

Get child by name and class.

template<class T>
inline int childCount(ChildIndexFlags flags = {}) const

Return the number of child Aspects inheriting from given class.

template<class T>
inline int indexOfChild(const AbstractAspect *child, ChildIndexFlags flags = {}) const

Return (0 based) index of child in the list of children inheriting from class T.

Public Slots

bool setName(const QString&, NameHandling handling = NameHandling::AutoUnique, QUndoCommand *parent = nullptr)

AbstractAspect::setName sets the name of the abstract aspect.

Parameters:

• value – - the new value for the name that needs to be checked and made unique if it’s not the case yet

• autoUnique – - if set to \true the new name is automatically made unique, the name is not changed and false is returned otherwise. default is \true.

• skipAutoUnique – - if set to \true, don’t check for uniqueness, the caller has to guarantee the uniqueness. default is \false.

Returns:

returns, if the new name is valid or not

void remove(QUndoCommand *parent)

Remove me from my parent’s list of children.

void copy()

copies the aspect to the clipboard. The standard XML-serialization via AbstractAspect::load() is used.

void paste(bool duplicate = false)

in case the clipboard containts a LabPlot’s specific copy&paste content, this function deserializes the XML string and adds the created aspect as a child to the current aspect (“paste”).

Signals

void aspectDescriptionAboutToChange(const AbstractAspect*)

Emitted before the name, comment or caption spec is changed.

void aspectDescriptionChanged(const AbstractAspect*)

Emitted after the name, comment or caption spec have changed.

void childAspectAboutToBeAdded(const AbstractAspect *parent, int index, const AbstractAspect *child)

aspectAboutToBeAdded Signal indicating a new child was added at position index. Do not connect to both variants of aspectAboutToBeAdded!

Parameters:

• parent –

• index – Position of the new aspect

• child –

void childAspectAboutToBeAdded(const AbstractAspect *parent, const AbstractAspect *before, const AbstractAspect *child)

aspectAboutToBeAdded

Parameters:

• parent –

• before – aspect one position before the child

• child –

void childAspectAboutToBeRemoved(const AbstractAspect *child)

aspectAboutToBeRemoved Called from the parent if a child is being removed

void aspectAboutToBeRemoved(const AbstractAspect*)

aspectAboutToBeRemoved Called by the aspect itself when it’s being removed

Emitted before an aspect is removed from its parent.

void aspectHiddenAboutToChange(const AbstractAspect*)

Emitted before the hidden attribute is changed.

void aspectHiddenChanged(const AbstractAspect*)

Emitted after the hidden attribute has changed.

void statusInfo(const QString&)

Emitted whenever some aspect in the tree wants to give status information to the user.

See also

info(const QString&)

Public Static Functions

static AspectType clipboardAspectType(QString&)

helper function determening whether the current content of the clipboard contants the labplot specific copy&paste XML content. In case a valid content is available, the aspect type of the object to be pasted is returned. AspectType::AbstractAspect is returned otherwise.

class AbstractColumn : public AbstractAspect

Interface definition for data with column logic.

This is an abstract base class for column-based data, i.e. mathematically a vector or technically a 1D array or list. It only defines the interface but has no data members itself.

Classes derived from this are typically table columns or outputs of filters which can be chained between table columns and plots. From the point of view of the plot functions there will be no difference between a table column and a filter output since both use this interface.

Classes derived from this will either store a vector with entries of one certain data type, e.g. double, QString, QDateTime, or generate such values on demand. To determine the data type of a class derived from this, use the columnMode() function. AbstractColumn defines all access functions for all supported data types but only those corresponding to the return value of columnMode() will return a meaningful value. Calling functions not belonging to the data type of the column is safe, but will do nothing (writing function) or return some default value (reading functions).

This class also defines all signals which indicate a data change. Any class whose output values are subject to change over time must emit the according signals. These signals notify any object working with the column before and after a change of the column. In some cases it will be necessary for a class using the column to connect aboutToBeDestroyed(), to react to a column’s deletion, e.g. a filter’s reaction to a table deletion.

All writing functions have a “do nothing” standard implementation to make deriving a read-only class very easy without bothering about the writing interface.

Subclassed by Column, ColumnStringIO, SimpleFilterColumn

type specific functions

virtual QString textAt(int row) const

Return the content of row ‘row’.

Use this only when columnMode() is Text

virtual void setTextAt(int row, const QString &new_value)

Set the content of row ‘row’.

Use this only when columnMode() is Text

virtual void replaceTexts(int first, const QVector<QString> &new_values)

Replace a range of values.

Use this only when columnMode() is Text

virtual int dictionaryIndex(int row) const

Return the position/index in the dictionary for the text value at.

Use this only when columnMode() is Text

Parameters:

row –

virtual QDate dateAt(int row) const

Return the date part of row ‘row’.

Use this only when columnMode() is DateTime, Month or Day

virtual void setDateAt(int row, QDate new_value)

Set the content of row ‘row’.

Use this only when columnMode() is DateTime, Month or Day

virtual QTime timeAt(int row) const

Return the time part of row ‘row’.

Use this only when columnMode() is DateTime, Month or Day

virtual void setTimeAt(int row, QTime new_value)

Set the content of row ‘row’.

Use this only when columnMode() is DateTime, Month or Day

virtual QDateTime dateTimeAt(int row) const

Return the QDateTime in row ‘row’.

Use this only when columnMode() is DateTime, Month or Day

virtual void setDateTimeAt(int row, const QDateTime &new_value)

Set the content of row ‘row’.

Use this only when columnMode() is DateTime, Month or Day

virtual void replaceDateTimes(int first, const QVector<QDateTime> &new_values)

Replace a range of values.

Use this only when columnMode() is DateTime, Month or Day

virtual double doubleAt(int row) const

Return the double value in row ‘row’.

Use this only when columnMode() is Numeric

virtual double valueAt(int row) const

Return the double value in row ‘row’ independent of the column mode.

Integer and big integer values are converted to double, NAN is returned for other modes.

virtual void setValueAt(int row, double new_value)

Set the content of row ‘row’.

Use this only when columnMode() is Numeric

virtual void replaceValues(int first, const QVector<double> &new_values)

Replace a range of values.

Use this only when columnMode() is Numeric

virtual int integerAt(int row) const

Return the integer value in row ‘row’.

Use this only when columnMode() is Integer

virtual void setIntegerAt(int row, int new_value)

Set the content of row ‘row’.

Use this only when columnMode() is Integer

virtual void replaceInteger(int first, const QVector<int> &new_values)

Replace a range of values.

Use this only when columnMode() is Integer

virtual qint64 bigIntAt(int row) const

Return the bigint value in row ‘row’.

Use this only when columnMode() is BigInt

virtual void setBigIntAt(int row, qint64 new_value)

Set the content of row ‘row’.

Use this only when columnMode() is BigInt

virtual void replaceBigInt(int first, const QVector<qint64> &new_values)

Replace a range of values.

Use this only when columnMode() is BigInt

virtual Properties properties() const

Returns the properties hold by this column (no, constant, monotonic increasing, monotonic decreasing,…) Is used in XYCurve to improve the search velocity for the y value for a specific x value

void plotDesignationAboutToChange(const AbstractColumn *source)

Column plot designation will be changed.

‘source’ is always the this pointer of the column that emitted this signal. This way it’s easier to use one handler for lots of columns.

void plotDesignationChanged(const AbstractColumn *source)

Column plot designation changed.

‘source’ is always the this pointer of the column that emitted this signal. This way it’s easier to use one handler for lots of columns.

void modeAboutToChange(const AbstractColumn *source)

Column mode (possibly also the data type) will be changed.

‘source’ is always the this pointer of the column that emitted this signal. This way it’s easier to use one handler for lots of columns.

void modeChanged(const AbstractColumn *source)

Column mode (possibly also the data type) changed.

‘source’ is always the this pointer of the column that emitted this signal. This way it’s easier to use one handler for lots of columns.

void dataAboutToChange(const AbstractColumn *source)

Data of the column will be changed.

‘source’ is always the this pointer of the column that emitted this signal. This way it’s easier to use one handler for lots of columns.

void dataChanged(const AbstractColumn *source)

Data of the column has changed.

Important: When data has changed also the number of rows in the column may have changed without any other signal emission. ‘source’ is always the this pointer of the column that emitted this signal. This way it’s easier to use one handler for lots of columns.

void rowsAboutToBeInserted(const AbstractColumn *source, int before, int count)

rowsAboutToBeInserted

Rows will be inserted.

Parameters:

• source –

• before – Old number of rows

• count – Number of rows added

• source – the column that emitted the signal

• before – the row to insert before

• count – the number of rows to be inserted

void rowsInserted(const AbstractColumn *source, int before, int count)

rowsInserted

Rows have been inserted.

Parameters:

• source –

• before – Old number of rows

• count – Number of rows added

• source – the column that emitted the signal

• before – the row to insert before

• count – the number of rows to be inserted

void rowsAboutToBeRemoved(const AbstractColumn *source, int first, int count)

rowsAboutToBeRemoved

Rows will be deleted.

Parameters:

• source –

• first – Old number of rows

• count – Number of rows removed

• source – the column that emitted the signal

• first – the first row to be deleted

• count – the number of rows to be deleted

void rowsRemoved(const AbstractColumn *source, int first, int count)

rowsRemoved

Rows have been deleted.

Parameters:

• source –

• first – Old number of rows

• count – Number of rows removed

• source – the column that emitted the signal

• first – the first row that was deleted

• count – the number of deleted rows

void maskingAboutToChange(const AbstractColumn *source)

Rows are about to be masked or unmasked.

void maskingChanged(const AbstractColumn *source)

Rows have been masked or unmasked.

void aboutToBeDestroyed(const AbstractColumn *source)

Emitted shortl before this column is deleted.

This is needed by AbstractFilter.

Parameters:

source – the object emitting this signal

IntervalAttribute related functions

bool isMasked(int row) const

Return whether a certain row is masked.

bool isMasked(const Interval<int> &i) const

Return whether a certain interval of rows is fully masked.

QVector<Interval<int>> maskedIntervals() const

Return all intervals of masked rows.

void clearMasks()

Clear all masking information.

void setMasked(const Interval<int> &i, bool mask = true)

Set an interval masked.

Parameters:

• i – the interval

• mask – true: mask, false: unmask

void setMasked(int row, bool mask = true)

Overloaded function for convenience.

Formula related functions

virtual QString formula(int row) const

Return the formula associated with row ‘row’.

virtual QVector<Interval<int>> formulaIntervals() const

Return the intervals that have associated formulas.

This can be used to make a list of formulas with their intervals. Here is some example code:

QStringList list;
QVector< Interval<int> > intervals = my_column.formulaIntervals();
foreach(Interval<int> interval, intervals)
    list << QString(interval.toString() + ": " + my_column.formula(interval.start()));

virtual void setFormula(const Interval<int> &i, const QString &formula)

Set a formula string for an interval of rows.

virtual void setFormula(int row, const QString &formula)

Overloaded function for convenience.

virtual void clearFormulas()

Clear all formulas.

void reset()

resets the connections for the dependent objects like plots and formulas in other columns to the dataChanged signal in the current column.

void setChanged()

invalidates the internal properties of the columns and emits the signal dataChanged().

call this function if the data of the column was changed directly via the data()-pointer and not via the setValueAt() or when multiple cells are being notified and the signal dataChanged() is suppressed for performance reasons and this function needs to be called after all cells were modified.

void setSuppressDataChangedSignal(const bool)

suppresses the dataChanged signal if value is true, enables it otherwise.

used when multiple cells are being modified and the signal needs to be supressed for performance reasons,

See also

setChanged().

Public Functions

AbstractColumn(const QString &name, AspectType type)

Ctor.

Parameters:

name – the column name (= aspect name)

inline virtual bool isReadOnly() const

Return whether the object is read-only.

virtual ColumnMode columnMode() const = 0

Return the column mode.

This function is most used by tables but can also be used by plots. The column mode specifies how to interpret the values in the column additional to the data type.

virtual void setColumnMode(AbstractColumn::ColumnMode)

Set the column mode.

This sets the column mode and, if necessary, converts it to another datatype.

virtual PlotDesignation plotDesignation() const = 0

Return the column plot designation.

virtual void setPlotDesignation(AbstractColumn::PlotDesignation)

Set the column plot designation.

virtual bool copy(const AbstractColumn *source)

Copy another column of the same type.

This function will return false if the data type of ‘other’ is not the same as the type of ‘this’. Use a filter to convert a column to another type.

virtual bool copy(const AbstractColumn *source, int source_start, int dest_start, int num_rows)

Copies part of another column of the same type.

This function will return false if the data type of ‘other’ is not the same as the type of ‘this’.

Parameters:

• source – pointer to the column to copy

• source_start – first row to copy in the column to copy

• destination_start – first row to copy in

• num_rows – the number of rows to copy

virtual int rowCount() const = 0

Return the data vector size.

virtual int availableRowCount(int max = -1) const = 0

Return the number of available data rows.

void insertRows(int before, int count, QUndoCommand *parent = nullptr)

Insert some empty (or initialized with invalid values) rows.

void removeRows(int first, int count, QUndoCommand *parent = nullptr)

Remove ‘count’ rows starting from row ‘first’.

virtual void clear(QUndoCommand*)

Clear the whole column.

bool isValid(int row) const

Convenience method for mode-independent testing of validity.

Public Static Functions

static QString timeUnitString(TimeUnit)

Convenience method for getting time unit string translated since used in UI.

static QString plotDesignationString(PlotDesignation, bool withBrackets = true)

Convenience method for getting plot designation string translated since used in UI.

static QString columnModeString(ColumnMode)

Convenience method for getting mode string translated since used in UI.

static QIcon modeIcon(ColumnMode)

Convenience method for mode-dependent icon.

struct ColumnStatistics

struct HeatmapFormat

class AbstractDataSource : public AbstractPart

Interface for the data sources.

Subclassed by Matrix, Spreadsheet

class AbstractFileFilter : public QObject

Interface for the input/output file filters.

Subclassed by AsciiFilter, BinaryFilter, CANFilter, FITSFilter, HDF5Filter, ImageFilter, JsonFilter, MatioFilter, McapFilter, NetCDFFilter, OdsFilter, ROOTFilter, ReadStatFilter, SpiceFilter, XLSXFilter

Public Functions

virtual void write(const QString &fileName, AbstractDataSource*) = 0

write

Writing the content of the datasource to the file with filename fileName

Parameters:

fileName –

QString lastError() const

Returns the last error that occured during the last parse step.

QStringList lastWarnings() const

Returns the list of warnings that occured during the last parse step.

Signals

void completed(int) const

int ranging from 0 to 100 notifies about the status of a read/write process

Public Static Functions

static AbstractColumn::ColumnMode columnMode(const QString &valueString, QString &dateTimeFormat, const QLocale& = QLocale(), bool intAsDouble = false, int baseYear = QLocale::DefaultTwoDigitBaseYear)

return the column mode for the given value string and settings dateTimeFormat and locale. in case dateTimeFormat is empty, all possible datetime formats are tried out to determine the valid datetime object.

static QString convertFromNumberToColumn(int n)

returns the list of all supported data file formats

class AbstractPart : public AbstractAspect

Base class of Aspects with MDI windows as views (AspectParts).

Subclassed by AbstractDataSource, Datapicker, DatapickerImage, Note, Notebook, Workbook, Worksheet

Public Functions

virtual QWidget *view() const = 0

Construct a primary view on me.

The caller receives ownership of the view.

This method may be called multiple times during the life time of a Part, or it might not get called at all. Parts must not depend on the existence of a view for their operation.

void deleteView() const

this function is called when PartMdiView, the mdi-subwindow-wrapper of the actual view, is closed (=deleted) in MainWindow. Makes sure that the view also gets deleted.

ContentDockWidget *dockWidget() const

Wrap the view() into a PartMdiView.

A new view is only created the first time this method is called; after that, a pointer to the pre-existing view is returned.

virtual QMenu *createContextMenu() override

Return AbstractAspect::createContextMenu() plus operations on the primary view.