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

List:       kde-commits
Subject:    KDE/kdelibs
From:       Christoph Cullmann <cullmann () kde ! org>
Date:       2010-11-17 5:14:55
Message-ID: 20101117051455.026C3AC8A0 () svn ! kde ! org
[Download RAW message or body]

SVN commit 1197943 by cullmann:

port dhaumanns fixes to the interface, fixed before beta

    RecoveryInterface: use Qt-style naming
    
    - isDataRecoveryAvailable()
    - recoverData()
    - discardDataRecovery()
    - add proper API documentation
    - more safe implementation in the Document



 M  +23 -0     interfaces/ktexteditor/Mainpage.dox  
 M  +2 -1      interfaces/ktexteditor/movinginterface.h  
 M  +36 -12    interfaces/ktexteditor/recoveryinterface.h  
 M  +5 -3      kate/document/katedocument.cpp  
 M  +4 -3      kate/document/katedocument.h  


--- trunk/KDE/kdelibs/interfaces/ktexteditor/Mainpage.dox #1197942:1197943
@@ -230,6 +230,9 @@
 The following is a list of all classes that are available when the document
 supports the KTextEditor::SmartInterface:
 
+\warning All Smart interfaces were deprecated and not implemented anymore in
+KDE >= 4.6. They were replaced by the \ref kte_group_moving_classes
+
 <!-- The classes are defined by the \ingroup doxygen command -->
 */
 
@@ -237,6 +240,26 @@
 
 
 
+/** \defgroup kte_group_moving_classes MovingCursors and MovingRanges
+\ingroup kte_group_doc_extensions
+
+If the KTextEditor implementation supports the KTextEditor::MovingInterface,
+there are several \e moving classes available.
+
+Instances of the \e moving classes are bound to a specific Document, and
+maintain their position in that document regardless of changes to the text.
+Changes to MovingRange%s can be caught by using the class MovingRangeFeedback.
+
+The following is a list of all classes that are available when the document
+supports the KTextEditor::MovingInterface:
+
+<!-- The classes are defined by the \ingroup doxygen command -->
+*/
+
+
+
+
+
 /** \defgroup kte_group_view_extensions View Extension Interfaces
 A KTextEditor implementation may implement a View extension interface, but
 it does not \e need to. So as a KTextEditor user you have to cast the View
--- trunk/KDE/kdelibs/interfaces/ktexteditor/movinginterface.h #1197942:1197943
@@ -33,8 +33,9 @@
 {
 
 /**
- * \short A class which provides the interface to create MovingCursors and MovingRanges.
+ * \brief Document interface for for MovingCursor%s and MovingRange%s.
  *
+ * \ingroup kte_group_document_extension
  * \ingroup kte_group_moving_classes
  *
  * This class provides the interface for KTextEditor::Documents to create MovingCursors/Ranges.
--- trunk/KDE/kdelibs/interfaces/ktexteditor/recoveryinterface.h #1197942:1197943
@@ -25,17 +25,22 @@
 namespace KTextEditor
 {
 /**
-  * An interface that allows controlling the crash recovery functionality of the
-  * underlying editor component.
+ * \brief Document extension interface to control crash recovery.
   * 
-  * When the editor crashed previously with some modifications, and the same document
-  * is opened again, a recovery will be available:
-  *   RecoveryInterface::haveRecovery() will return true
+ * \ingroup kte_group_document_extensions
   * 
-  * When executing RecoveryInterface::doRecovery(), the recovery will be applied.
+ * When the system or the application using the editor component crashed
+ * with unsaved changes in the Document, the View notifies the user about
+ * the lost data and asks, whether the data should be recovered.
   * 
-  * When executing RecoveryInterface::discardRecovery(), the recovery will be discarded.
-  * */
+ * This interface gives you control over the data recovery process. Use
+ * isDataRecoveryAvailable() to check for lost data. If you do not want the
+ * editor component to handle the data recovery process automatically, you can
+ * either trigger the data recovery by calling recoverData() or discard it
+ * by discardDataRecovery().
+ *
+ * \since 4.6
+ */
 class KTEXTEDITOR_EXPORT RecoveryInterface
 {
   public:
@@ -53,11 +58,30 @@
     
     /**
      * Returns whether a recovery is available for the current document.
-     * */
-    virtual bool haveRecovery() const = 0;
-    virtual void doRecovery() = 0;
-    virtual void discardRecovery() = 0;
+     *
+     * \see recoverData(), discardDataRecovery()
+     */
+    virtual bool isDataRecoveryAvailable() const = 0;
 
+    /**
+     * If recover data is available, calling recoverData() will trigger the
+     * recovery of the data. If isDataRecoveryAvailable() returns \e false,
+     * calling this function does nothing.
+     *
+     * \see isDataRecoveryAvailable(), discardDataRecovery()
+     */
+    virtual void recoverData() = 0;
+
+    /**
+     * If recover data is available, calling discardDataRecovery() will discard
+     * the recover data and the recover data is lost.
+     * If isDataRecoveryAvailable() returns \e false, calling this function
+     * does nothing.
+     *
+     * \see isDataRecoveryAvailable(), recoverData()
+     */
+    virtual void discardDataRecovery() = 0;
+
   private:
     class RecoveryInterfacePrivate* const d;
 };
--- trunk/KDE/kdelibs/kate/document/katedocument.cpp #1197942:1197943
@@ -2454,18 +2454,20 @@
   return true;
 }
 
-bool KateDocument::haveRecovery() const
+bool KateDocument::isDataRecoveryAvailable() const
 {
   return m_swapfile->shouldRecover();
 }
 
-void KateDocument::doRecovery()
+void KateDocument::recoverData()
 {
+  if (isDataRecoveryAvailable())
   m_swapfile->recover();
 }
 
-void KateDocument::discardRecovery()
+void KateDocument::discardDataRecovery()
 {
+  if (isDataRecoveryAvailable())
   m_swapfile->discard();
 }
 
--- trunk/KDE/kdelibs/kate/document/katedocument.h #1197942:1197943
@@ -1053,9 +1053,10 @@
   //
   // KTextEditor::RecoveryInterface
   //
-     virtual bool haveRecovery() const;
-     virtual void doRecovery();
-     virtual void discardRecovery();
+  public:
+    virtual bool isDataRecoveryAvailable() const;
+    virtual void recoverData();
+    virtual void discardDataRecovery();
      
   //
   // KTextEditor::TemplateInterface + KTextEditor::TemplateInterface2
[prev in list] [next in list] [prev in thread] [next in thread]