diff --git a/README.md b/README.md index c2fbd35..cb9832f 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,8 @@ The library can be used to The library, the header files, and others will be installed to your system. +> ```make html_docs``` can be used to generate documentations of the library, and ```make check``` can be used to run unit tests of the library. + #### Using the module * Add following line to your qmake's project file: diff --git a/src/xlsx/doc/qtxlsx.qdocconf b/src/xlsx/doc/qtxlsx.qdocconf index 57951ed..ef11181 100644 --- a/src/xlsx/doc/qtxlsx.qdocconf +++ b/src/xlsx/doc/qtxlsx.qdocconf @@ -55,7 +55,7 @@ HTML.footer = \ "
\n" \ "
\n" \ "

\n" \ - " © 2013 Debao Zhang. \n" \ + " © 2013-2014 Debao Zhang. \n" \ " Documentation contributions included herein are the copyrights of\n" \ " their respective owners.

\n" \ "

\n" \ diff --git a/src/xlsx/xlsxabstractsheet.cpp b/src/xlsx/xlsxabstractsheet.cpp index 7ca892d..9e2b397 100644 --- a/src/xlsx/xlsxabstractsheet.cpp +++ b/src/xlsx/xlsxabstractsheet.cpp @@ -54,6 +54,13 @@ AbstractSheetPrivate::~AbstractSheetPrivate() \omitvalue ST_MacroSheet */ +/*! + \fn AbstractSheet::copy(const QString &distName, int distId) const + + Copies the current sheet to a sheet called \a distName with \a distId. + Returns the new sheet. + */ + /*! * \internal */ diff --git a/src/xlsx/xlsxdocument.cpp b/src/xlsx/xlsxdocument.cpp index 0ec106d..63bce3a 100644 --- a/src/xlsx/xlsxdocument.cpp +++ b/src/xlsx/xlsxdocument.cpp @@ -404,7 +404,7 @@ Document::Document(QIODevice *device, QObject *parent) : /*! \overload - Write \a value to cell \a row_column with the \a format. + Write \a value to cell \a row_column with the given \a format. */ bool Document::write(const CellReference &row_column, const QVariant &value, const Format &format) { @@ -415,6 +415,7 @@ bool Document::write(const CellReference &row_column, const QVariant &value, con /*! * Write \a value to cell (\a row, \a col) with the \a format. + * Returns true on success. */ bool Document::write(int row, int col, const QVariant &value, const Format &format) { @@ -426,6 +427,8 @@ bool Document::write(int row, int col, const QVariant &value, const Format &form /*! \overload Returns the contents of the cell \a cell. + + \sa cellAt() */ QVariant Document::read(const CellReference &cell) const { @@ -436,6 +439,8 @@ QVariant Document::read(const CellReference &cell) const /*! Returns the contents of the cell (\a row, \a col). + + \sa cellAt() */ QVariant Document::read(int row, int col) const { @@ -468,10 +473,11 @@ Chart *Document::insertChart(int row, int col, const QSize &size) } /*! - Merge a \a range of cells. The first cell should contain the data and the others should - be blank. All cells will be applied the same style if a valid \a format is given. + Merge a \a range of cells. The first cell should contain the data and the others should + be blank. All cells will be applied the same style if a valid \a format is given. + Returns true on success. - \note All cells except the top-left one will be cleared. + \note All cells except the top-left one will be cleared. */ bool Document::mergeCells(const CellRange &range, const Format &format) { @@ -481,7 +487,8 @@ bool Document::mergeCells(const CellRange &range, const Format &format) } /*! - Unmerge the cells in the \a range. + Unmerge the cells in the \a range. + Returns true on success. */ bool Document::unmergeCells(const CellRange &range) { @@ -491,7 +498,7 @@ bool Document::unmergeCells(const CellRange &range) } /*! - Sets width in characters of a range of columns. + Sets width in characters of columns with the given \a range and \a width. Returns true on success. */ bool Document::setColumnWidth(const CellRange &range, double width) @@ -502,7 +509,7 @@ bool Document::setColumnWidth(const CellRange &range, double width) } /*! - Sets format property of a range of columns. + Sets format property of columns with the gien \a range and \a format. Returns true on success. */ bool Document::setColumnFormat(const CellRange &range, const Format &format) @@ -513,7 +520,7 @@ bool Document::setColumnFormat(const CellRange &range, const Format &format) } /*! - Sets hidden property of a range of columns. Columns are 1-indexed. + Sets hidden property of columns \a range to \a hidden. Columns are 1-indexed. Hidden columns are not visible. Returns true on success. */ @@ -525,7 +532,7 @@ bool Document::setColumnHidden(const CellRange &range, bool hidden) } /*! - Sets width in characters of a range of columns. Columns are 1-indexed. + Sets width in characters \a column to \a width. Columns are 1-indexed. Returns true on success. */ bool Document::setColumnWidth(int column, double width) @@ -534,7 +541,8 @@ bool Document::setColumnWidth(int column, double width) } /*! - Sets format property of a range of columns. Columns are 1-indexed. + Sets format property \a column to \a format. Columns are 1-indexed. + Returns true on success. */ bool Document::setColumnFormat(int column, const Format &format) { @@ -542,7 +550,8 @@ bool Document::setColumnFormat(int column, const Format &format) } /*! - Sets hidden property of a column. Columns are 1-indexed. + Sets hidden property of a \a column. Columns are 1-indexed. + Returns true on success. */ bool Document::setColumnHidden(int column, bool hidden) { @@ -550,7 +559,7 @@ bool Document::setColumnHidden(int column, bool hidden) } /*! - Sets width in characters of a range of columns. Columns are 1-indexed. + Sets width in characters for columns [\a colFirst, \a colLast]. Columns are 1-indexed. Returns true on success. */ bool Document::setColumnWidth(int colFirst, int colLast, double width) @@ -561,7 +570,9 @@ bool Document::setColumnWidth(int colFirst, int colLast, double width) } /*! - Sets format property of a range of columns. Columns are 1-indexed. + Sets format property of columns [\a colFirst, \a colLast] to \a format. + Columns are 1-indexed. + Returns true on success. */ bool Document::setColumnFormat(int colFirst, int colLast, const Format &format) { @@ -572,7 +583,9 @@ bool Document::setColumnFormat(int colFirst, int colLast, const Format &format) /*! - Sets hidden property of a range of columns. Columns are 1-indexed. + Sets hidden property of columns [\a colFirst, \a colLast] to \a hidden. + Columns are 1-indexed. + Returns true on success. */ bool Document::setColumnHidden(int colFirst, int colLast, bool hidden) { @@ -582,7 +595,9 @@ bool Document::setColumnHidden(int colFirst, int colLast, bool hidden) } /*! - Returns width of the column in characters of the normal font. Columns are 1-indexed. + Returns width of the \a column in characters of the normal font. + Columns are 1-indexed. + Returns true on success. */ double Document::columnWidth(int column) { @@ -592,7 +607,7 @@ double Document::columnWidth(int column) } /*! - Returns formatting of the column. Columns are 1-indexed. + Returns formatting of the \a column. Columns are 1-indexed. */ Format Document::columnFormat(int column) { @@ -602,7 +617,7 @@ Format Document::columnFormat(int column) } /*! - Returns true if column is hidden. Columns are 1-indexed. + Returns true if \a column is hidden. Columns are 1-indexed. */ bool Document::isColumnHidden(int column) { @@ -612,7 +627,7 @@ bool Document::isColumnHidden(int column) } /*! - Sets the \a format of the row \a row. + Sets the \a format of the \a row. Rows are 1-indexed. Returns true if success. @@ -758,7 +773,11 @@ bool Document::addConditionalFormatting(const ConditionalFormatting &cf) } /*! - * Returns a Cell object based on the given \a pos. 0 will be returned if the cell doesn't exist. + * \overload + * Returns the cell at the position \a pos. If there is no cell at + * the specified position, the function returns 0. + * + * \sa read() */ Cell *Document::cellAt(const CellReference &pos) const { @@ -768,7 +787,10 @@ Cell *Document::cellAt(const CellReference &pos) const } /*! - * Returns a Cell object based on the given \a row and \a col. + * Returns the cell at the given \a row and \a col. If there + * is no cell at the specified position, the function returns 0. + * + * \sa read() */ Cell *Document::cellAt(int row, int col) const { @@ -871,7 +893,7 @@ AbstractSheet *Document::sheet(const QString &sheetName) const } /*! - * Creates and append an document with name \a name. + * Creates and append an sheet with the given \a name and \a type. * Return true if success. */ bool Document::addSheet(const QString &name, AbstractSheet::SheetType type) @@ -881,7 +903,7 @@ bool Document::addSheet(const QString &name, AbstractSheet::SheetType type) } /*! - * Creates and inserts an document with name \a name at the \a index. + * Creates and inserts an document with the given \a name and \a type at the \a index. * Returns false if the \a name already used. */ bool Document::insertSheet(int index, const QString &name, AbstractSheet::SheetType type) diff --git a/src/xlsx/xlsxworksheet.cpp b/src/xlsx/xlsxworksheet.cpp index 7028094..e813ed0 100755 --- a/src/xlsx/xlsxworksheet.cpp +++ b/src/xlsx/xlsxworksheet.cpp @@ -420,6 +420,8 @@ void Worksheet::setWhiteSpaceVisible(bool visible) /*! * Write \a value to cell (\a row, \a column) with the \a format. * Both \a row and \a column are all 1-indexed value. + * + * Returns true on success. */ bool Worksheet::write(int row, int column, const QVariant &value, const Format &format) { @@ -483,6 +485,7 @@ bool Worksheet::write(int row, int column, const QVariant &value, const Format & * \overload * Write \a value to cell \a row_column with the \a format. * Both row and column are all 1-indexed value. + * Returns true on success. */ bool Worksheet::write(const CellReference &row_column, const QVariant &value, const Format &format) { @@ -527,9 +530,8 @@ QVariant Worksheet::read(int row, int column) const } /*! - * \overload - * Returns the cell at the position \a row_column. - * 0 will be returned if the cell doesn't exist. + * Returns the cell at the given \a row_column. If there + * is no cell at the specified position, the function returns 0. */ Cell *Worksheet::cellAt(const CellReference &row_column) const { @@ -540,8 +542,8 @@ Cell *Worksheet::cellAt(const CellReference &row_column) const } /*! - * Returns the cell at the position (\a row \a column). - * 0 will be returned if the cell doesn't exist. + * Returns the cell at the given \a row and \a column. If there + * is no cell at the specified position, the function returns 0. */ Cell *Worksheet::cellAt(int row, int column) const { @@ -564,8 +566,10 @@ Format WorksheetPrivate::cellFormat(int row, int col) const } /*! - \overload - Write string \a value to the cell \a row_column with the \a format + \overload + Write string \a value to the cell \a row_column with the \a format. + + Returns true on success. */ bool Worksheet::writeString(const CellReference &row_column, const RichString &value, const Format &format) { @@ -576,7 +580,8 @@ bool Worksheet::writeString(const CellReference &row_column, const RichString &v } /*! - Write string \a value to the cell (\a row, \a column) with the \a format + Write string \a value to the cell (\a row, \a column) with the \a format. + Returns true on success. */ bool Worksheet::writeString(int row, int column, const RichString &value, const Format &format) { @@ -603,7 +608,7 @@ bool Worksheet::writeString(int row, int column, const RichString &value, const /*! \overload - Write string \a value to the cell \a row_column with the \a format + Write string \a value to the cell \a row_column with the \a format. */ bool Worksheet::writeString(const CellReference &row_column, const QString &value, const Format &format) { @@ -616,7 +621,8 @@ bool Worksheet::writeString(const CellReference &row_column, const QString &valu /*! \overload - Write string \a value to the cell (\a row, \a column) with the \a format + Write string \a value to the cell (\a row, \a column) with the \a format. + Returns true on success. */ bool Worksheet::writeString(int row, int column, const QString &value, const Format &format) { @@ -646,7 +652,8 @@ bool Worksheet::writeInlineString(const CellReference &row_column, const QString } /*! - Write string \a value to the cell (\a row, \a column) with the \a format + Write string \a value to the cell (\a row, \a column) with the \a format. + Returns true on success. */ bool Worksheet::writeInlineString(int row, int column, const QString &value, const Format &format) { @@ -669,7 +676,8 @@ bool Worksheet::writeInlineString(int row, int column, const QString &value, con /*! \overload - Write numeric \a value to the cell \a row_column with the \a format + Write numeric \a value to the cell \a row_column with the \a format. + Returns true on success. */ bool Worksheet::writeNumeric(const CellReference &row_column, double value, const Format &format) { @@ -680,7 +688,8 @@ bool Worksheet::writeNumeric(const CellReference &row_column, double value, cons } /*! - Write numeric \a value to the cell (\a row, \a column) with the \a format + Write numeric \a value to the cell (\a row, \a column) with the \a format. + Returns true on success. */ bool Worksheet::writeNumeric(int row, int column, double value, const Format &format) { @@ -697,6 +706,7 @@ bool Worksheet::writeNumeric(int row, int column, double value, const Format &fo /*! \overload Write \a formula to the cell \a row_column with the \a format and \a result. + Returns true on success. */ bool Worksheet::writeFormula(const CellReference &row_column, const CellFormula &formula, const Format &format, double result) { @@ -707,7 +717,8 @@ bool Worksheet::writeFormula(const CellReference &row_column, const CellFormula } /*! - Write \a formula to the cell (\a row, \a column) with the \a format and \a result. + Write \a formula_ to the cell (\a row, \a column) with the \a format and \a result. + Returns true on success. */ bool Worksheet::writeFormula(int row, int column, const CellFormula &formula_, const Format &format, double result) { @@ -759,7 +770,8 @@ bool Worksheet::writeFormula(int row, int column, const CellFormula &formula_, c /*! \overload - Write a empty cell \a row_column with the \a format + Write a empty cell \a row_column with the \a format. + Returns true on success. */ bool Worksheet::writeBlank(const CellReference &row_column, const Format &format) { @@ -770,7 +782,8 @@ bool Worksheet::writeBlank(const CellReference &row_column, const Format &format } /*! - Write a empty cell (\a row, \a column) with the \a format + Write a empty cell (\a row, \a column) with the \a format. + Returns true on success. */ bool Worksheet::writeBlank(int row, int column, const Format &format) { @@ -788,7 +801,8 @@ bool Worksheet::writeBlank(int row, int column, const Format &format) } /*! \overload - Write a bool \a value to the cell \a row_column with the \a format + Write a bool \a value to the cell \a row_column with the \a format. + Returns true on success. */ bool Worksheet::writeBool(const CellReference &row_column, bool value, const Format &format) { @@ -799,7 +813,8 @@ bool Worksheet::writeBool(const CellReference &row_column, bool value, const For } /*! - Write a bool \a value to the cell (\a row, \a column) with the \a format + Write a bool \a value to the cell (\a row, \a column) with the \a format. + Returns true on success. */ bool Worksheet::writeBool(int row, int column, bool value, const Format &format) { @@ -815,7 +830,8 @@ bool Worksheet::writeBool(int row, int column, bool value, const Format &format) } /*! \overload - Write a QDateTime \a dt to the cell \a row_column with the \a format + Write a QDateTime \a dt to the cell \a row_column with the \a format. + Returns true on success. */ bool Worksheet::writeDateTime(const CellReference &row_column, const QDateTime &dt, const Format &format) { @@ -826,7 +842,8 @@ bool Worksheet::writeDateTime(const CellReference &row_column, const QDateTime & } /*! - Write a QDateTime \a dt to the cell (\a row, \a column) with the \a format + Write a QDateTime \a dt to the cell (\a row, \a column) with the \a format. + Returns true on success. */ bool Worksheet::writeDateTime(int row, int column, const QDateTime &dt, const Format &format) { @@ -848,7 +865,8 @@ bool Worksheet::writeDateTime(int row, int column, const QDateTime &dt, const Fo /*! \overload - Write a QTime \a t to the cell \a row_column with the \a format + Write a QTime \a t to the cell \a row_column with the \a format. + Returns true on success. */ bool Worksheet::writeTime(const CellReference &row_column, const QTime &t, const Format &format) { @@ -859,7 +877,8 @@ bool Worksheet::writeTime(const CellReference &row_column, const QTime &t, const } /*! - Write a QTime \a t to the cell (\a row, \a column) with the \a format + Write a QTime \a t to the cell (\a row, \a column) with the \a format. + Returns true on success. */ bool Worksheet::writeTime(int row, int column, const QTime &t, const Format &format) { @@ -879,7 +898,8 @@ bool Worksheet::writeTime(int row, int column, const QTime &t, const Format &for /*! \overload - Write a QUrl \a url to the cell \a row_column with the given \a format \a display and \a tip + Write a QUrl \a url to the cell \a row_column with the given \a format \a display and \a tip. + Returns true on success. */ bool Worksheet::writeHyperlink(const CellReference &row_column, const QUrl &url, const Format &format, const QString &display, const QString &tip) { @@ -891,6 +911,7 @@ bool Worksheet::writeHyperlink(const CellReference &row_column, const QUrl &url, /*! Write a QUrl \a url to the cell (\a row, \a column) with the given \a format \a display and \a tip. + Returns true on success. */ bool Worksheet::writeHyperlink(int row, int column, const QUrl &url, const Format &format, const QString &display, const QString &tip) { @@ -945,7 +966,7 @@ bool Worksheet::writeHyperlink(int row, int column, const QUrl &url, const Forma /*! * Add one DataValidation \a validation to the sheet. - * Return true if it's successful. + * Returns true on success. */ bool Worksheet::addDataValidation(const DataValidation &validation) { @@ -959,7 +980,7 @@ bool Worksheet::addDataValidation(const DataValidation &validation) /*! * Add one ConditionalFormatting \a cf to the sheet. - * Return true if it's successful. + * Returns true on success. */ bool Worksheet::addConditionalFormatting(const ConditionalFormatting &cf) { @@ -979,7 +1000,7 @@ bool Worksheet::addConditionalFormatting(const ConditionalFormatting &cf) /*! * Insert an \a image at the position \a row, \a column - * Returns ture if success. + * Returns true on success. */ bool Worksheet::insertImage(int row, int column, const QImage &image) { @@ -1036,6 +1057,7 @@ Chart *Worksheet::insertChart(int row, int column, const QSize &size) /*! Merge a \a range of cells. The first cell should contain the data and the others should be blank. All cells will be applied the same style if a valid \a format is given. + Returns true on success. \note All cells except the top-left one will be cleared. */ @@ -1072,7 +1094,8 @@ bool Worksheet::mergeCells(const CellRange &range, const Format &format) } /*! - Unmerge the cells in the \a range. + Unmerge the cells in the \a range. Returns true on success. + */ bool Worksheet::unmergeCells(const CellRange &range) { @@ -1085,7 +1108,7 @@ bool Worksheet::unmergeCells(const CellRange &range) } /*! - Returns all the merged cells + Returns all the merged cells. */ QList Worksheet::mergedCells() const { @@ -1093,6 +1116,9 @@ QList Worksheet::mergedCells() const return d->merges; } +/*! + * \internal + */ void Worksheet::saveToXmlFile(QIODevice *device) const { Q_D(const Worksheet); @@ -1481,7 +1507,7 @@ QList WorksheetPrivate ::getColumnIndexes(int colFirst, int colLast) } /*! - Sets width in characters of a range of columns. + Sets width in characters of a \a range of columns to \a width. Returns true on success. */ bool Worksheet::setColumnWidth(const CellRange &range, double width) @@ -1493,7 +1519,7 @@ bool Worksheet::setColumnWidth(const CellRange &range, double width) } /*! - Sets format property of a range of columns. Columns are 1-indexed. + Sets format property of a \a range of columns to \a format. Columns are 1-indexed. Returns true on success. */ bool Worksheet::setColumnFormat(const CellRange& range, const Format &format) @@ -1505,7 +1531,7 @@ bool Worksheet::setColumnFormat(const CellRange& range, const Format &format) } /*! - Sets hidden property of a range of columns. Columns are 1-indexed. + Sets hidden property of a \a range of columns to \a hidden. Columns are 1-indexed. Hidden columns are not visible. Returns true on success. */ @@ -1518,7 +1544,8 @@ bool Worksheet::setColumnHidden(const CellRange &range, bool hidden) } /*! - Sets width in characters of a range of columns. Columns are 1-indexed. + Sets width in characters for columns [\a colFirst, \a colLast] to \a width. + Columns are 1-indexed. Returns true on success. */ bool Worksheet::setColumnWidth(int colFirst, int colLast, double width) @@ -1533,7 +1560,9 @@ bool Worksheet::setColumnWidth(int colFirst, int colLast, double width) } /*! - Sets format property of a range of columns. Columns are 1-indexed. + Sets format property of a range of columns [\a colFirst, \a colLast] to \a format. + Columns are 1-indexed. + Returns true on success. */ bool Worksheet::setColumnFormat(int colFirst, int colLast, const Format &format) { @@ -1552,7 +1581,8 @@ bool Worksheet::setColumnFormat(int colFirst, int colLast, const Format &format) } /*! - Sets hidden property of a range of columns. Columns are 1-indexed. + Sets hidden property of a range of columns [\a colFirst, \a colLast] to \a hidden. + Columns are 1-indexed. Returns true on success. */ bool Worksheet::setColumnHidden(int colFirst, int colLast, bool hidden) { @@ -1566,7 +1596,7 @@ bool Worksheet::setColumnHidden(int colFirst, int colLast, bool hidden) } /*! - Returns width of the column in characters of the normal font. Columns are 1-indexed. + Returns width of the \a column in characters of the normal font. Columns are 1-indexed. */ double Worksheet::columnWidth(int column) { @@ -1580,7 +1610,7 @@ double Worksheet::columnWidth(int column) } /*! - Returns formatting of the column. Columns are 1-indexed. + Returns formatting of the \a column. Columns are 1-indexed. */ Format Worksheet::columnFormat(int column) { @@ -1594,7 +1624,7 @@ Format Worksheet::columnFormat(int column) } /*! - Returns true if column is hidden. Columns are 1-indexed. + Returns true if \a column is hidden. Columns are 1-indexed. */ bool Worksheet::isColumnHidden(int column) { @@ -1735,6 +1765,8 @@ bool Worksheet::groupRows(int rowFirst, int rowLast, bool collapsed) /*! \overload + + Groups columns with the given \a range and \a collapsed. */ bool Worksheet::groupColumns(const CellRange &range, bool collapsed) {