diff --git a/AUTHORS b/AUTHORS new file mode 100644 --- /dev/null +++ b/AUTHORS @@ -0,0 +1,8 @@ +Adam Pigg (project maintainer) +Jarosław Staniek +Wojciech Kosowicz +Friedrich W. H. Kossebau +Boudewijn Rempt +Radoslaw Wicik +Shreya Pandit + diff --git a/Doxyfile b/Doxyfile --- a/Doxyfile +++ b/Doxyfile @@ -44,7 +44,7 @@ # for a project that appears at the top of each page and should give viewer a # quick idea about the purpose of the project. Keep the description short. -PROJECT_BRIEF = "The user API for scripting KoReport items" +PROJECT_BRIEF = "The API guide for KReport" # With the PROJECT_LOGO tag one can specify a logo or an icon that is included # in the documentation. The maximum height of the logo should not exceed 55 @@ -58,7 +58,7 @@ # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = ./doxygen_script +OUTPUT_DIRECTORY = ./doxygen # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- # directories (in 2 levels) under the output directory of each output format and diff --git a/KReportScript.dox b/KReportScript.dox --- a/KReportScript.dox +++ b/KReportScript.dox @@ -1,12 +1,15 @@ /** * \mainpage * - * KoReport is a library for the generation of reports in multiple formats. + * KReport is a library for the generation of reports in multiple formats. + * + * It contains support for user generated scripts written in Javascript. + * This document describes the user facing API for controling reports. * * Concepts * ======== * - * KoReport user scripting has the following concepts: + * KReport user scripting has the following concepts: * * The top-level report object \n * This contains functions for retreiving the report name, section objects and item objects \n * It also contains event handlers which are executed at open, complete, and newPage events \n @@ -39,7 +42,7 @@ * Example * ======= * - * The following javascripy snippet contains a basic object with no methods + * The following javascript snippet contains a basic object with no methods * * \code * function detail() diff --git a/src/items/check/KReportScriptCheck.h b/src/items/check/KReportScriptCheck.h --- a/src/items/check/KReportScriptCheck.h +++ b/src/items/check/KReportScriptCheck.h @@ -39,44 +39,50 @@ public Q_SLOTS: - //! Return the value of the checkbox + //! @return the value of the checkbox bool value() const; //! Set the value of the checkbox, defaults to checked if no value is given void setValue(bool val = true); - //! Returns the style of the checkbox as Cross, Tick or Dot + //! @return the style of the checkbox as Cross, Tick or Dot QString checkStyle() const; //!Sets the style of the checkbox, valid values are Cross, Tick or Dot void setCheckStyle(const QString&); - //!Returns the foreground color + //! @return the foreground (text) color of the text-item QColor foregroundColor() const; - //!Sets the foreground color + + //! Sets the foreground (text) color of the text-item to the given color void setForegroundColor(const QColor&); - //!Returs the line color + //! @return the border line color of the text-item QColor lineColor() const; - //!Sets the line color + + //! Sets the border line color of the text-item to the given color void setLineColor(const QColor&); - //!Returns the line weight (thickness) + //! @return the border line weight (thickness) of the text-item int lineWeight() const; - //!Serts the line weight (thicknes) + + //! Sets the border line weight (thickness) of the text-item void setLineWeight(int); - //! Returns the line style. Valid values are those from Qt::PenStyle (0-5) + //! @return the border line style of the text-item. Values are from Qt::Penstyle range 0-5 int lineStyle() const; - //! Srts the line style. Valid values are those from Qt::PenStyle (0-5) + + //! Sets the border line style of the text-item to the given style in the range 0-5 void setLineStyle(int); - //!Returns the position of the checkbox within the parent section + //! @returns the position of the text-item in points QPointF position() const; - //!Sets the position of the checkbox within the parent section + + //! Sets the position of the text-item to the given point coordinates void setPosition(const QPointF&); - //!Returns the size of the checkbox + //! @returns the size of the text-item in points QSizeF size() const; - //!Serts the size of the checkbox + + //! Sets the size of the text-item to the given size in points void setSize(const QSizeF&); private: diff --git a/src/items/field/KReportScriptField.h b/src/items/field/KReportScriptField.h --- a/src/items/field/KReportScriptField.h +++ b/src/items/field/KReportScriptField.h @@ -29,6 +29,11 @@ */ namespace Scripting { +/** + @brief Field script interface + + The user facing interface for scripting report fields +*/ class Field : public QObject { Q_OBJECT @@ -38,59 +43,78 @@ ~Field() override; public Q_SLOTS: - //!Returns the source (column) that the field gets its data from* + + //! @return the source (column) that the field gets its data from* QString source() const; - //!Sets the source (column) for the field + + //! Sets the source (column) for the field. + //! Valid values include a column name, fixed string if prefixed with '$' + //! or a valid script expression if prefixed with a '=' void setSource(const QString&); - //!Returns the horizontal alignment of the field, -1 = left, 0 = center, 1 = right + //! @return the horizontal alignment as an integer + //! Valid values are left: -1, center: 0, right; 1 int horizontalAlignment() const; - //!Sets the horizontal alignment. Valid values are -1, 0, 1 + + //! Sets the horizontal alignment + //! Valid values for alignment are left: -1, center: 0, right; 1 void setHorizonalAlignment(int); - //!Returns the vertical alignment of the field, -1 = left, 0 = center, 1 = right + //! @return the vertical alignment + //! Valid values are top: -1, middle: 0, bottom: 1 int verticalAlignment() const; - //!Sets the vertical alignment. Valid values are -1, 0, 1 + + //! Sets the vertical alignment + //! Valid values for aligmnt are top: -1, middle: 0, bottom: 1 void setVerticalAlignment(int); - //!Returns the background color of the field + //! @return the background color of the lable QColor backgroundColor() const; - //!Sets the background color + + //! Set the background color of the field to the given color void setBackgroundColor(const QColor&); - //!Returns the foreground (text) color of the field + //! @return the foreground (text) color of the field QColor foregroundColor() const; - //!Srets the foreground (text) color + + //! Sets the foreground (text) color of the field to the given color void setForegroundColor(const QColor&); - //!Returns the background opacity + //! @return the opacity of the field int backgroundOpacity() const; - //!Sets the background opacity. Values 0-100 + + //! Sets the background opacity of the field + //! Valid values are in the range 0-100 void setBackgroundOpacity(int); - //!Returns the line color of the field + //! @return the border line color of the field QColor lineColor() const; - //!Sets the line color of the field + + //! Sets the border line color of the field to the given color void setLineColor(const QColor&); - //!Returns the line weight (width) of the field + //! @return the border line weight (thickness) of the field int lineWeight() const; - //!Sets the line weight (width) of the field + + //! Sets the border line weight (thickness) of the field void setLineWeight(int); - //! Returns the line style. Valid values are those from Qt::PenStyle (0-5) + //! @return the border line style of the field. Values are from Qt::Penstyle range 0-5 int lineStyle() const; - //! Srts the line style. Valid values are those from Qt::PenStyle (0-5) + + //! Sets the border line style of the field to the given style in the range 0-5 void setLineStyle(int); - //!Returns the position of the field within the parent section + //! @returns the position of the field in points QPointF position() const; - //!Sets the position of the field within the parent section + + //! Sets the position of the field to the given point coordinates void setPosition(const QPointF&); - //!Returns the size of the field + //! @returns the size of the field in points QSizeF size() const; - //!Serts the size of the field + + //! Sets the size of the field to the given size in points void setSize(const QSizeF&); private: diff --git a/src/items/label/KReportScriptLabel.h b/src/items/label/KReportScriptLabel.h --- a/src/items/label/KReportScriptLabel.h +++ b/src/items/label/KReportScriptLabel.h @@ -43,54 +43,69 @@ //!Sets the label caption void setCaption(const QString&); - //!Returns the horizontal alignment of the label, -1 = left, 0 = center, 1 = right + //! @return the horizontal alignment as an integer + //! Valid values are left: -1, center: 0, right; 1 int horizontalAlignment() const; - //!Sets the horizontal alignment. Valid values are -1, 0, 1 + + //! Sets the horizontal alignment + //! Valid values for alignment are left: -1, center: 0, right; 1 void setHorizonalAlignment(int); - //!Returns the vertical alignment of the label, -1 = left, 0 = center, 1 = right + //! @return the vertical alignment + //! Valid values are top: -1, middle: 0, bottom: 1 int verticalAlignment() const; - //!Sets the vertical alignment. Valid values are -1, 0, 1 + + //! Sets the vertical alignment + //! Valid values for aligmnt are top: -1, middle: 0, bottom: 1 void setVerticalAlignment(int); - //!Returns the background color of the label + //! @return the background color of the lable QColor backgroundColor() const; - //!Sets the background color + + //! Set the background color of the label to the given color void setBackgroundColor(const QColor&); - //!Returns the foreground (text) color of the label + //! @return the foreground (text) color of the label QColor foregroundColor() const; - //!Srets the foreground (text) color + + //! Sets the foreground (text) color of the label to the given color void setForegroundColor(const QColor&); - //!Returns the background opacity + //! @return the opacity of the label int backgroundOpacity() const; - //!Sets the background opacity. Values 0-100 + + //! Sets the background opacity of the label + //! Valid values are in the range 0-100 void setBackgroundOpacity(int); - //!Returns the line color of the label + //! @return the border line color of the label QColor lineColor() const; - //!Sets the line color of the label + + //! Sets the border line color of the label to the given color void setLineColor(const QColor&); - //!Returns the line weight (width) of the label + //! @return the border line weight (thickness) of the label int lineWeight() const; - //!Sets the line weight (width) of the label + + //! Sets the border line weight (thickness) of the label void setLineWeight(int); - //! Returns the line style. Valid values are those from Qt::PenStyle (0-5) + //! @return the border line style of the label. Values are from Qt::Penstyle range 0-5 int lineStyle() const; - //! Srts the line style. Valid values are those from Qt::PenStyle (0-5) + + //! Sets the border line style of the label to the given style in the range 0-5 void setLineStyle(int); - //!Returns the position of the label within the parent section + //! @returns the position of the label in points QPointF position() const; - //!Sets the position of the label within the parent section + + //! Sets the position of the label to the given point coordinates void setPosition(const QPointF&); - //!Returns the size of the label + //! @returns the size of the label in points QSizeF size() const; - //!Serts the size of the label + + //! Sets the size of the label to the given size in points void setSize(const QSizeF&); private: diff --git a/src/items/text/KReportScriptText.h b/src/items/text/KReportScriptText.h --- a/src/items/text/KReportScriptText.h +++ b/src/items/text/KReportScriptText.h @@ -38,59 +38,77 @@ ~Text() override; public Q_SLOTS: - //!Returns the source (column) that the text item gets its data from + //! @return the source (column) that the text-item gets its data from* QString source() const; - //!Sets the source (column) for the field + + //! Sets the source (column) for the text-item. + //! Valid values include a column name, fixed string if prefixed with '$' + //! or a valid script expression if prefixed with a '=' void setSource(const QString&); - //!Returns the horizontal alignment of the label, -1 = left, 0 = center, 1 = right + //! @return the horizontal alignment as an integer + //! Valid values are left: -1, center: 0, right; 1 int horizontalAlignment() const; - //!Sets the horizontal alignment. Valid values are -1, 0, 1 + + //! Sets the horizontal alignment + //! Valid values for alignment are left: -1, center: 0, right; 1 void setHorizonalAlignment(int); - //!Returns the vertical alignment of the label, -1 = left, 0 = center, 1 = right + //! @return the vertical alignment + //! Valid values are top: -1, middle: 0, bottom: 1 int verticalAlignment() const; - //!Sets the vertical alignment. Valid values are -1, 0, 1 + + //! Sets the vertical alignment + //! Valid values for aligmnt are top: -1, middle: 0, bottom: 1 void setVerticalAlignment(int); - //!Returns the background color of the label + //! @return the background color of the lable QColor backgroundColor() const; - //!Sets the background color + + //! Set the background color of the text-item to the given color void setBackgroundColor(const QColor&); - //!Returns the foreground (text) color of the label + //! @return the foreground (text) color of the text-item QColor foregroundColor() const; - //!Srets the foreground (text) color + + //! Sets the foreground (text) color of the text-item to the given color void setForegroundColor(const QColor&); - //!Returns the background opacity + //! @return the opacity of the text-item int backgroundOpacity() const; - //!Sets the background opacity. Values 0-100 + + //! Sets the background opacity of the text-item + //! Valid values are in the range 0-100 void setBackgroundOpacity(int); - //!Returns the line color of the label + //! @return the border line color of the text-item QColor lineColor() const; - //!Sets the line color of the label + + //! Sets the border line color of the text-item to the given color void setLineColor(const QColor&); - //!Returns the line weight (width) of the label + //! @return the border line weight (thickness) of the text-item int lineWeight() const; - //!Sets the line weight (width) of the label + + //! Sets the border line weight (thickness) of the text-item void setLineWeight(int); - //! Returns the line style. Valid values are those from Qt::PenStyle (0-5) + //! @return the border line style of the text-item. Values are from Qt::Penstyle range 0-5 int lineStyle() const; - //! Srts the line style. Valid values are those from Qt::PenStyle (0-5) + + //! Sets the border line style of the text-item to the given style in the range 0-5 void setLineStyle(int); - //!Returns the position of the label within the parent section + //! @returns the position of the text-item in points QPointF position() const; - //!Sets the position of the label within the parent section + + //! Sets the position of the text-item to the given point coordinates void setPosition(const QPointF&); - //!Returns the size of the label + //! @returns the size of the text-item in points QSizeF size() const; - //!Serts the size of the label + + //! Sets the size of the text-item to the given size in points void setSize(const QSizeF&); //!Load the contets for the text item from the given file diff --git a/src/plugins/maps/KReportScriptMaps.h b/src/plugins/maps/KReportScriptMaps.h --- a/src/plugins/maps/KReportScriptMaps.h +++ b/src/plugins/maps/KReportScriptMaps.h @@ -44,9 +44,9 @@ /** * Sets the position of the map in points - * @param Position + * @param position */ - void setPosition(const QPointF &p); + void setPosition(const QPointF &position); /** * Get the size of the map @@ -56,14 +56,26 @@ /** * Set the size of the map in points - * @param Size + * @param size */ - void setSize(const QSizeF &s); + void setSize(const QSizeF &size); + /** + * Set the latitude value of the map + * @param latitude + */ void setLatitude(qreal latitude); + /** + * Set the longitude value of the map + * @param longitude + */ void setLongitude(qreal longitude); + /** + * Set the zoom factor of the map + * @param zoom + */ void setZoom(int zoom); private: diff --git a/src/plugins/maps/KReportScriptMaps.cpp b/src/plugins/maps/KReportScriptMaps.cpp --- a/src/plugins/maps/KReportScriptMaps.cpp +++ b/src/plugins/maps/KReportScriptMaps.cpp @@ -38,19 +38,19 @@ return m_map->position(); } -void Maps::setPosition(const QPointF& p) +void Maps::setPosition(const QPointF& position) { - m_map->setPosition(p); + m_map->setPosition(position); } QSizeF Maps::size() const { return m_map->size(); } -void Maps::setSize(const QSizeF& s) +void Maps::setSize(const QSizeF& size) { - m_map->setSize(s); + m_map->setSize(size); } void Maps::setLatitude(qreal latitude) diff --git a/src/renderer/scripting/KReportScriptDraw.h b/src/renderer/scripting/KReportScriptDraw.h --- a/src/renderer/scripting/KReportScriptDraw.h +++ b/src/renderer/scripting/KReportScriptDraw.h @@ -24,6 +24,9 @@ class OROPage; /** + @brief Helper giving access to drawing functions + + Contains methods for drawing shapes on a report page */ class KReportScriptDraw : public QObject { @@ -36,7 +39,7 @@ void setOffset(QPointF); public Q_SLOTS: /** - Draw a rectangle + @brief Draw a rectangle \param x X posistion \param y Y position \param w Width @@ -49,7 +52,7 @@ void rectangle(qreal, qreal, qreal, qreal, const QString&, const QString&, qreal, int); /** - Draw an ellipse + @brief Draw an ellipse \param x X posistion \param y Y position \param w Width @@ -62,7 +65,7 @@ void ellipse(qreal, qreal, qreal, qreal, const QString&, const QString&, qreal, int); /** - Draw a line + @brief Draw a line \param x1 Start X position \param y1 Start Y Position \param x2 End X position @@ -72,7 +75,7 @@ void line(qreal, qreal, qreal, qreal, const QString&); /** - Draw some text + @brief Draw some text \param x X Position \param y Y Position \param txt The text diff --git a/src/renderer/scripting/KReportScriptLine.h b/src/renderer/scripting/KReportScriptLine.h --- a/src/renderer/scripting/KReportScriptLine.h +++ b/src/renderer/scripting/KReportScriptLine.h @@ -45,62 +45,61 @@ * Return the start position of the line * @return start position */ - QPointF startPosition(); + QPointF startPosition() const; /** * Set the start position of the line - * @param StartPosition + * @param startPosition */ - void setStartPosition(const QPointF&); + void setStartPosition(const QPointF& startPosition); /** * Return the end position of the line * @return end position */ - QPointF endPosition(); + QPointF endPosition() const; /** * Set the end position of the line - * @param EndPosition + * @param endPosition */ - void setEndPosition(const QPointF&); + void setEndPosition(const QPointF& endPosition); /** - * Return the color of the line + * Return the color of the linelineColor * @return line color */ - QColor lineColor(); + QColor lineColor() const; /** * Sets the line color - * @param LineColor + * @param lineColor */ - void setLineColor(const QColor&); + void setLineColor(const QColor& lineColor); /** * Return the weight (width) of the line * @return Weight */ - int lineWeight(); + int lineWeight() const; /** * Set the weight (width) of the line - * @param Weight + * @param weight */ - void setLineWeight(int); + void setLineWeight(int const weight); /** * Return the line style. Valid values are those from Qt::PenStyle (0-5) * @return Style */ - int lineStyle(); - + int lineStyle() const; /** * Set the style of the line - * @param Style From Qt::PenStyle (0-5) + * @param style From Qt::PenStyle (0-5) */ - void setLineStyle(int); + void setLineStyle(int style); private: KReportItemLine *m_line; diff --git a/src/renderer/scripting/KReportScriptLine.cpp b/src/renderer/scripting/KReportScriptLine.cpp --- a/src/renderer/scripting/KReportScriptLine.cpp +++ b/src/renderer/scripting/KReportScriptLine.cpp @@ -32,56 +32,56 @@ { } - -QColor Line::lineColor() +QColor Line::lineColor() const { return m_line->m_lineColor->value().value(); } -void Line::setLineColor(const QColor& c) +void Line::setLineColor(const QColor& color) { - m_line->m_lineColor->setValue(c); + m_line->m_lineColor->setValue(color); } -int Line::lineWeight() +int Line::lineWeight() const { return m_line->m_lineWeight->value().toInt(); } -void Line::setLineWeight(int w) +void Line::setLineWeight(int weight) { - m_line->m_lineWeight->setValue(w); + m_line->m_lineWeight->setValue(weight); } -int Line::lineStyle() +int Line::lineStyle() const { return m_line->m_lineStyle->value().toInt(); } -void Line::setLineStyle(int s) + +void Line::setLineStyle(int style) { - if (s < 0 || s > 5) { - s = 1; + if (style < 0 || style > 5) { + style = 1; } - m_line->m_lineStyle->setValue(s); + m_line->m_lineStyle->setValue(style); } -QPointF Line::startPosition() +QPointF Line::startPosition() const { return m_line->m_start->value().toPointF(); } -void Line::setStartPosition(const QPointF& p) +void Line::setStartPosition(const QPointF& startPosition) { - m_line->m_start->setValue(p); + m_line->m_start->setValue(startPosition); } -QPointF Line::endPosition() +QPointF Line::endPosition() const { return m_line->m_end->value().toPointF(); } -void Line::setEndPosition(const QPointF& p) +void Line::setEndPosition(const QPointF& endPosition) { - m_line->m_end->setValue(p); + m_line->m_end->setValue(endPosition); } } diff --git a/src/renderer/scripting/KReportScriptReport.h b/src/renderer/scripting/KReportScriptReport.h --- a/src/renderer/scripting/KReportScriptReport.h +++ b/src/renderer/scripting/KReportScriptReport.h @@ -28,21 +28,21 @@ /** - @ *brief Report object user scripting API. - - Contains methods for a report object which can be called by user scripts. \n - - Example: \n - \code - function report() - { - this.OnOpen = function() - { - debug.print("Report opened!"); - } - } - reportname.initialize(new report()) - \endcode + @brief Report object user scripting API. + + Contains methods for a report object which can be called by user scripts. \n + + Example: \n + \code + function report() + { + this.OnOpen = function() + { + debug.print("Report opened!"); + } + } + reportname.initialize(new report()) + \endcode */ class Report : public QObject { diff --git a/src/renderer/scripting/KReportScriptSection.h b/src/renderer/scripting/KReportScriptSection.h --- a/src/renderer/scripting/KReportScriptSection.h +++ b/src/renderer/scripting/KReportScriptSection.h @@ -23,18 +23,18 @@ class KReportSectionData; /** - @ *brief Report section object user scripting API. + @brief Report section object user scripting API. Contains methods for a report section object which can be called by user scripts. \n Example: \n \code function detail() { - this.OnRender = function() - { - debug.print("Rendering detail section!"); - } + this.OnRender = function() + { + debug.print("Rendering detail section!"); + } } reportname.section_detail.initialize(new detail()) \endcode