Add documentation for the class Document.

Little api refactor
12 years ago · f8ca19f14b
5 changed files with 137 additions and 23 deletions
--- a/examples/xlsx/readwrite/main.cpp
+++ b/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");

--- a/src/xlsx/xlsxdocument.cpp
+++ b/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.
+ */
+void Document::setCurrentWorksheet(int index)
 {
-    Q_D(const Document);
-    return d->workbook->activeWorksheet();
+    Q_D(Document);
+    d->workbook->setActiveWorksheet(index);
 }

-void Document::setActivedWorksheetIndex(int index)
+/*!
+ * \brief Set current worksheet to be the sheet named \a name.
+ */
+void Document::setCurrentWorksheet(const QString &name)
 {
    Q_D(Document);
-    d->workbook->setActiveWorksheet(index);
+    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;
--- a/src/xlsx/xlsxdocument.h
+++ b/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;
-    int activedWorksheetIndex() const;
-    void setActivedWorksheetIndex(int index);
+    bool setSheetName(const QString &name);
+
+    Workbook *workbook() const;
+    Worksheet *currentWorksheet() const;
+    void setCurrentWorksheet(int index);
+    void setCurrentWorksheet(const QString &name);

    bool save();
    bool saveAs(const QString &xlsXname);
--- a/src/xlsx/xlsxworksheet.h
+++ b/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);
--- a/tests/auto/mergecell/tst_mergecelltest.cpp
+++ b/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"), "");
 }