[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-commits
Subject:    playground/graphics/UNNAMED_READER/corelibrary
From:       Stefan Kebekus <kebekus () kde ! org>
Date:       2006-12-11 4:15:08
Message-ID: 1165810508.914545.11463.nullmailer () svn ! kde ! org
[Download RAW message or body]

SVN commit 612369 by kebekus:

added documentation


 A             doc (directory)  
 A             doc/api (directory)  
 A             doc/api/Doxyfile.global  
 M  +1 -0      length.cpp  
 M  +10 -6     length.h  
 M  +3 -1      pageNumber.h  
 M  +18 -2     readerWidget.cpp  
 M  +43 -4     readerWidget.h  


--- trunk/playground/graphics/UNNAMED_READER/corelibrary/length.cpp #612368:612369
@@ -29,6 +29,7 @@
 
 namespace UNNAMED_READER {
 
+/** @short internal compound used by the length class */
 class unitOfDistance
 {
  public:
--- trunk/playground/graphics/UNNAMED_READER/corelibrary/length.h #612368:612369
@@ -39,11 +39,11 @@
 
 /** @short Represents a phyical length
 
-    This class is used to represent a physical length. Its main purpose
-    it to help in the conversion of units, and to avoid confusion
-    about units. To avoid misunderstandings, there is no default
-    constructor so that this class needs to be explicitly initialized
-    with one of the functions below.
+    This class is used to represent a physical length. Its main
+    purpose it to help in the conversion of units, and to avoid
+    confusion about units. To avoid misunderstandings, the default
+    constructor does not take a float, so that the length value needs
+    to be explicitly initialized with one of the functions below.
 
     @warning Lengths are stored internally in mm. If you convert to
     or from any other unit, expect floating point round-off errors.
@@ -89,7 +89,7 @@
   void setLength_in_scaledPoints(double l) {length_in_mm = l*mm_per_scaledPoint;}
 
   /** sets the length in pixel. The parameter @param res is the resolution of the
-      used device in DPI. */
+      used device in DPI, @param l is the number of pixels. */
   void setLength_in_pixel(int l, double res) { setLength_in_inch(l / res); }
 
   /** @returns the length in millimeters */
@@ -131,10 +131,14 @@
 
   /** Comparison of two lengthes */
   bool operator > (const Length &o) const {return (length_in_mm > o.getLength_in_mm());}
+
+  /** Comparison of two lengthes */
   bool operator < (const Length &o) const {return (length_in_mm < o.getLength_in_mm());}
 
   /** Comparison of two lengthes */
   bool operator >= (const Length &o) const {return (length_in_mm >= o.getLength_in_mm());}
+
+  /** Comparison of two lengthes */
   bool operator <= (const Length &o) const {return (length_in_mm <= o.getLength_in_mm());}
 
   /** Ratio of two lengthes
--- trunk/playground/graphics/UNNAMED_READER/corelibrary/pageNumber.h #612368:612369
@@ -43,8 +43,10 @@
 class PageNumber
 {
  public:
+  /** There is one special page number, the 'invalid' mentioned below */
   enum pageNums {
-    invalidPage   = 0 /*! Invalid page number */
+    /** page number zero means 'invalid' or 'unspecified' page number */
+    invalidPage   = 0
   };
 
   /** The default constructor sets the page number to 'invalidPage' */
--- trunk/playground/graphics/UNNAMED_READER/corelibrary/readerWidget.cpp #612368:612369
@@ -27,19 +27,35 @@
 #define UNNAMED_READER_DEBUG 1
 
 
-readerWidget::readerWidget(QWidget *parent) 
+readerWidget::readerWidget(QWidget *parent, KUrl url) 
   : QWidget(parent)
 {
+  documentURL = url;
+  documentURL.setRef(QString::null);
+
+#warning store and use the reference part of the url
+
   dlg = new Ui_readerWidget();
   dlg->setupUi(this);
 }
 
-  
+ 
 readerWidget::~readerWidget()
 {
 }
 
 
+void readerWidget::askToClose(void)
+{
+  kDebug(UNNAMED_READER_DEBUG, shell) << "readerWidget::askToClose()" << endl;
+
+#warning TODO: Ask if the document can be closed.
+
+  deleteLater();
+}
+
+  
+
 } // end: namespace UNNAMED_READER
 
 #include "readerWidget.moc"
--- trunk/playground/graphics/UNNAMED_READER/corelibrary/readerWidget.h #612368:612369
@@ -21,6 +21,7 @@
 #ifndef _READERWIDGET_H_
 #define _READERWIDGET_H_
 
+#include <KUrl>
 #include <QWidget>
 
 class Ui_readerWidget;
@@ -30,8 +31,20 @@
 
 /**
  * @short UNNAMED_READER Main Widget
+ *
+ * @note At times, readerWidgets delete themselves by using the method
+ * "deleteLater()", e.g. when a document is corruped, or when the user
+ * asks to close the document. This has a few consequences:
+ *
+ * - since deletion takes place in the event loop of the render
+ * thread, only the render thread may use pointers to readerWidgets
+ *
+ * - even in the render thread, never store a pointer to a render
+ * class; the pointer may become invalid next time control is given to
+ * the event loop. Use a QPointer instead, and make sure to check its
+ * validity before use.
+ *
  * @author Stefan Kebekus <kebekus@kde.org>
- * @version 0.1
  */
 class readerWidget : public QWidget
 {
@@ -40,16 +53,42 @@
  public:
   /**
    * Default Constructor
+   *
+   * @par parent the usual parent widget, or 0
+   *
+   * @par url a URL pointing to the document that this widget will
+   * show
    */
-  readerWidget(QWidget *parent);
+  readerWidget(QWidget *parent, KUrl url);
   
   /**
-       * Default Destructor
-       */
+   * Default Destructor
+   */
   virtual ~readerWidget();
 
+  /**
+   * Returns a URL pointing to document shown in this widget
+   */
+  KUrl document() const {return documentURL;}
+
+  /**
+   * Schedules deletion of the widget
+   *
+   * If the document has been modified, ask the user if the document
+   * can be closed. If ok, schedule this widget for deletion, using
+   * QObject::deleteLater().
+   */
+  void askToClose(void);
+
  protected:
+  /** Pointer to the class created by the Qt designer this sets up the
+      GUI */
   Ui_readerWidget *dlg;
+
+ private:
+  /* A copy of the URL given in the constructor, with the reference
+     part set to QString::null */
+  KUrl documentURL;
 };
 
 
[prev in list] [next in list] [prev in thread] [next in thread]