Add documentation for the class Document.

Little api refactor

examples/xlsx/readwrite/main.cpp

@@ -4,13 +4,14 @@ int main()
 {
     //Generate a simple xlsx file at first.
     QXlsx::Document xlsx;
+    xlsx.setSheetName("First Sheet");
     xlsx.write("A1", "Hello Qt!");
     xlsx.write("A2", 500);
     xlsx.saveAs("first.xlsx");
 
     //Read, edit, save
     QXlsx::Document xlsx2("first.xlsx");
-    xlsx2.addWorksheet("Second");
+    xlsx2.addWorksheet("Second Sheet");
     xlsx2.write("A1", "Hello Qt again!");
     xlsx2.saveAs("second.xlsx");
 

src/xlsx/xlsxdocument.cpp

@@ -61,12 +61,21 @@ bool DocumentPrivate::loadPackage(QIODevice *device)
 
 */
 
+/*!
+ * Creates a new empty xlsx document.
+ * The \a parent argument is passed to QObject's constructor.
+ */
 Document::Document(QObject *parent) :
     QObject(parent), d_ptr(new DocumentPrivate(this))
 {
     d_ptr->init();
 }
 
+/*!
+ * \overload
+ * Try to open an existing xlsx document named \a name.
+ * The \a parent argument is passed to QObject's constructor.
+ */
 Document::Document(const QString &name, QObject *parent) :
     QObject(parent), d_ptr(new DocumentPrivate(this))
 {
@@ -79,6 +88,11 @@ Document::Document(const QString &name, QObject *parent) :
     d_ptr->init();
 }
 
+/*!
+ * \overload
+ * Try to open an existing xlsx document from \a device.
+ * The \a parent argument is passed to QObject's constructor.
+ */
 Document::Document(QIODevice *device, QObject *parent) :
     QObject(parent), d_ptr(new DocumentPrivate(this))
 {
@@ -87,47 +101,90 @@ Document::Document(QIODevice *device, QObject *parent) :
     d_ptr->init();
 }
 
+/*!
+ * Create a new format used by sheet cells.
+ */
 Format *Document::createFormat()
 {
     Q_D(Document);
     return d->workbook->createFormat();
 }
 
+/*!
+ * Write \a value to cell \a row_column with the \a format.
+ */
 int Document::write(const QString row_column, const QVariant &value, Format *format)
 {
-    return activedWorksheet()->write(row_column, value, format);
+    return currentWorksheet()->write(row_column, value, format);
 }
 
+/*!
+ * Write \a value to cell (\a row, \a col) with the \a format.
+ */
 int Document::write(int row, int col, const QVariant &value, Format *format)
 {
-    return activedWorksheet()->write(row, col, value, format);
+    return currentWorksheet()->write(row, col, value, format);
 }
 
+/*!
+ * \brief Insert an image to current active worksheet.
+ * \param row
+ * \param column
+ * \param image
+ * \param xOffset
+ * \param yOffset
+ * \param xScale
+ * \param yScale
+ */
 int Document::insertImage(int row, int column, const QImage &image, double xOffset, double yOffset, double xScale, double yScale)
 {
-    return activedWorksheet()->insertImage(row, column, image, QPointF(xOffset, yOffset), xScale, yScale);
+    return currentWorksheet()->insertImage(row, column, image, QPointF(xOffset, yOffset), xScale, yScale);
 }
 
+/*!
+ * Merge cell \a range.
+ */
 int Document::mergeCells(const QString &range)
 {
-    return activedWorksheet()->mergeCells(range);
+    return currentWorksheet()->mergeCells(range);
 }
 
+/*!
+ * Unmerge cell \a range.
+ */
 int Document::unmergeCells(const QString &range)
 {
-    return activedWorksheet()->unmergeCells(range);
+    return currentWorksheet()->unmergeCells(range);
 }
 
+/*!
+ * \brief Set properties for a row of cells.
+ * \param row The worksheet row (zero indexed).
+ * \param height The row height.
+ * \param format Optional Format object.
+ * \param hidden
+ */
 bool Document::setRow(int row, double height, Format *format, bool hidden)
 {
-    return activedWorksheet()->setRow(row, height, format, hidden);
+    return currentWorksheet()->setRow(row, height, format, hidden);
 }
 
+/*!
+ * \brief Set properties for columns of cells.
+ * \param First column (zero-indexed).
+ * \param Last column (zero-indexed).
+ * \param width The width of the column(s).
+ * \param format Optional Format object.
+ * \param hidden
+ */
 bool Document::setColumn(int colFirst, int colLast, double width, Format *format, bool hidden)
 {
-    return activedWorksheet()->setColumn(colFirst, colLast, width, format, hidden);
+    return currentWorksheet()->setColumn(colFirst, colLast, width, format, hidden);
 }
 
+/*!
+ * Returns the value of the document's \a key property.
+ */
 QString Document::documentProperty(const QString &key) const
 {
     Q_D(const Document);
@@ -165,31 +222,61 @@ void Document::setDocumentProperty(const QString &key, const QString &property)
     d->documentProperties[key] = property;
 }
 
+/*!
+ * Returns the names of all properties that were addedusing setDocumentProperty().
+ */
 QStringList Document::documentPropertyNames() const
 {
     Q_D(const Document);
     return d->documentProperties.keys();
 }
 
+/*!
+ * Return the internal Workbook object.
+ */
 Workbook *Document::workbook() const
 {
     Q_D(const Document);
     return d->workbook.data();
 }
 
+/*!
+ * Creates and append an document with name \a name.
+ */
 bool Document::addWorksheet(const QString &name)
 {
     Q_D(Document);
     return d->workbook->addWorksheet(name);
 }
 
+/*!
+ * Creates and inserts an document with name \a name at the \a index.
+ * Returns false if the \a name already used.
+ */
 bool Document::insertWorkSheet(int index, const QString &name)
 {
     Q_D(Document);
     return d->workbook->insertWorkSheet(index, name);
 }
 
-Worksheet *Document::activedWorksheet() const
+/*!
+ * \brief Rename current worksheet to new \a name.
+ */
+bool Document::setSheetName(const QString &name)
+{
+    Q_D(Document);
+    for (int i=0; i<d->workbook->worksheets().size(); ++i) {
+        if (d->workbook->worksheets()[i]->sheetName() == name)
+            return false;
+    }
+    currentWorksheet()->setSheetName(name);
+    return true;
+}
+
+/*!
+ * \brief Return pointer of current worksheet.
+ */
+Worksheet *Document::currentWorksheet() const
 {
     Q_D(const Document);
     if (d->workbook->worksheets().size() == 0)
@@ -198,18 +285,31 @@ Worksheet *Document::activedWorksheet() const
     return d->workbook->worksheets().at(d->workbook->activeWorksheet()).data();
 }
 
-int Document::activedWorksheetIndex() const
+/*!
-{
+ * \brief Set current worksheet to be the sheet at \a index.
-    Q_D(const Document);
+ */
-    return d->workbook->activeWorksheet();
+void Document::setCurrentWorksheet(int index)
-}
-
-void Document::setActivedWorksheetIndex(int index)
 {
     Q_D(Document);
     d->workbook->setActiveWorksheet(index);
 }
 
+/*!
+ * \brief Set current worksheet to be the sheet named \a name.
+ */
+void Document::setCurrentWorksheet(const QString &name)
+{
+    Q_D(Document);
+    for (int i=0; i<d->workbook->worksheets().size(); ++i) {
+        if (d->workbook->worksheets()[i]->sheetName() == name)
+            d->workbook->setActiveWorksheet(i);
+    }
+}
+
+/*!
+ * Save current document to the filesystem. If no name specified when
+ * the document constructed, a default name "book1.xlsx" will be used.
+ */
 bool Document::save()
 {
     Q_D(Document);
@@ -218,6 +318,9 @@ bool Document::save()
     return saveAs(name);
 }
 
+/*!
+ * Saves the document to the file with the given \a name.
+ */
 bool Document::saveAs(const QString &name)
 {
     QFile file(name);
@@ -226,6 +329,10 @@ bool Document::saveAs(const QString &name)
     return false;
 }
 
+/*!
+ * \overload
+ * This function writes a document to the given \a device.
+ */
 bool Document::saveAs(QIODevice *device)
 {
     Q_D(Document);
@@ -238,6 +345,9 @@ bool Document::saveAs(QIODevice *device)
     return package.createPackage(device);
 }
 
+/*!
+ * Destroys the document and cleans up.
+ */
 Document::~Document()
 {
     delete d_ptr;

src/xlsx/xlsxdocument.h

@@ -64,12 +64,14 @@ public:
     void setDocumentProperty(const QString &name, const QString &property);
     QStringList documentPropertyNames() const;
 
-    Workbook *workbook() const;
     bool addWorksheet(const QString &name = QString());
     bool insertWorkSheet(int index, const QString &name = QString());
-    Worksheet *activedWorksheet() const;
+    bool setSheetName(const QString &name);
-    int activedWorksheetIndex() const;
+
-    void setActivedWorksheetIndex(int index);
+    Workbook *workbook() const;
+    Worksheet *currentWorksheet() const;
+    void setCurrentWorksheet(int index);
+    void setCurrentWorksheet(const QString &name);
 
     bool save();
     bool saveAs(const QString &xlsXname);

src/xlsx/xlsxworksheet.h

@@ -77,6 +77,9 @@ public:
     bool loadFromXmlFile(QIODevice *device);
     bool loadFromXmlData(const QByteArray &data);
 
+    QString sheetName() const;
+    void setSheetName(const QString &sheetName);
+
     ~Worksheet();
 private:
     friend class Package;
@@ -84,8 +87,6 @@ private:
     Worksheet(const QString &sheetName, Workbook *book=0);
 
     virtual bool isChartsheet() const;
-    QString sheetName() const;
-    void setSheetName(const QString &sheetName);
     bool isHidden() const;
     bool isSelected() const;
     void setHidden(bool hidden);

tests/auto/mergecell/tst_mergecelltest.cpp

@@ -29,7 +29,7 @@ void MergeCellTest::testWithoutMerge()
     QByteArray xmldata;
     QBuffer buffer(&xmldata);
     buffer.open(QIODevice::WriteOnly);
-    xlsx.activedWorksheet()->saveToXmlFile(&buffer);
+    xlsx.currentWorksheet()->saveToXmlFile(&buffer);
 
     QVERIFY2(!xmldata.contains("<mergeCell"), "");
 }
@@ -43,7 +43,7 @@ void MergeCellTest::testMerge()
     QByteArray xmldata;
     QBuffer buffer(&xmldata);
     buffer.open(QIODevice::WriteOnly);
-    xlsx.activedWorksheet()->saveToXmlFile(&buffer);
+    xlsx.currentWorksheet()->saveToXmlFile(&buffer);
 
     QVERIFY2(xmldata.contains("<mergeCells count=\"1\"><mergeCell ref=\"B1:B5\"/></mergeCells>"), "");
 }
@@ -58,7 +58,7 @@ void MergeCellTest::testUnMerge()
     QByteArray xmldata;
     QBuffer buffer(&xmldata);
     buffer.open(QIODevice::WriteOnly);
-    xlsx.activedWorksheet()->saveToXmlFile(&buffer);
+    xlsx.currentWorksheet()->saveToXmlFile(&buffer);
 
     QVERIFY2(!xmldata.contains("<mergeCell"), "");
 }