Refines API and documents.

BUG=Can't get candidates on InputContext::Observer::candidatesChanged().

Review URL: https://codereview.appspot.com/6448092

4 files changed, 90 insertions, 9 deletions

diff --git a/configure.ac b/configure.ac
index 3054645..ff33f46 100644
--- a/configure.ac
+++ b/configure.ac
@@ -24,7 +24,7 @@ m4_define([pyzy_released], [1])
 
 m4_define([pyzy_major_version], [0])
 m4_define([pyzy_minor_version], [0])
-m4_define([pyzy_micro_version], [8])
+m4_define([pyzy_micro_version], [9])
 m4_define([pyzy_interface_age], [0])
 m4_define([pyzy_binary_age],
           [m4_eval(100 * pyzy_minor_version + pyzy_micro_version)])
diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in
index 97860a5..58d418f 100644
--- a/docs/Doxyfile.in
+++ b/docs/Doxyfile.in
@@ -574,7 +574,8 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories
 # with spaces.
 
-INPUT                  = @top_srcdir@/src/Const.h \
+INPUT                  = @top_srcdir@/docs/mainpage.txt \
+                         @top_srcdir@/src/Const.h \
                          @top_srcdir@/src/InputContext.h \
                          @top_srcdir@/src/Variant.h
                          
diff --git a/docs/mainpage.txt b/docs/mainpage.txt
new file mode 100644
index 0000000..c3757e4
--- /dev/null
+++ b/docs/mainpage.txt
@@ -0,0 +1,80 @@
+/**
+\mainpage libpyzy - The Chinese PinYin and Bopomofo conversion library.
+
+Sample code
+
+\code
+#include <PyZy/InputContext.h>
+#include <PyZy/Variant.h>
+#include <iostream>
+
+// observer class to get a notification from |InputContext|.
+class SampleObserver : public PyZy::InputContext::Observer {
+public:
+    void commitText (PyZy::InputContext *context,
+                     const std::string &commit_text) {
+        std::cout << "text is commited. [" << commit_text << "]" << std::endl;
+    }
+
+    void inputTextChanged (PyZy::InputContext *context) {
+        std::cout << "input text is changed. [" << context->inputText() << "]"
+                  << std::endl;
+    }
+
+    void preeditTextChanged (PyZy::InputContext *context) {
+        std::cout << "selected text is changed. [" << context->selectedText()
+                  << "]" << std::endl;
+    }
+
+    void auxiliaryTextChanged (PyZy::InputContext *context) {
+        std::cout << "conversion text is changed. ["
+                  << context->conversionText() << "]" << std::endl;
+    }
+
+    void candidatesChanged (PyZy::InputContext *context) {
+        std::cout << "candidates are changed." << std::endl;
+
+        // output first 5 candidates.
+        for (size_t i = 0; i < 5; ++i) {
+            PyZy::Candidate candidate;
+            if (!context->getCandidate(i, candidate)) {
+                break;
+            }
+            std::cout << "  [" << i << "]: " << candidate.text << std::endl;
+        }
+    }
+
+    void cursorChanged (PyZy::InputContext *context) {
+        std::cout << "cursor position is commited. [" << context->cursor()
+                  << "]" << std::endl;
+    }
+};
+
+int main() {
+    PyZy::InputContext::init();
+
+    SampleObserver observer;
+    PyZy::InputContext *context = PyZy::InputContext::create(
+        PyZy::InputContext::FULL_PINYIN, &observer);
+
+    context->setProperty(PyZy::InputContext::PROPERTY_MODE_SIMP,
+                         PyZy::Variant::fromBool (true));
+
+    context->insert('n');
+    context->insert('i');
+    context->insert('h');
+    context->insert('a');
+    context->insert('o');
+
+    if (context->hasCandidate(4)) {
+        context->selectCandidate(4);
+    }
+
+    context->commit(PyZy::InputContext::TYPE_CONVERTED);
+
+    PyZy::InputContext::finalize();
+
+    return 0;
+}
+\endcode
+*/
diff --git a/src/InputContext.h b/src/InputContext.h
index 325c8d6..120527f 100644
--- a/src/InputContext.h
+++ b/src/InputContext.h
@@ -98,7 +98,7 @@ public:
          * This method is triggered by InputContext when conversion result
          * is commited.
          */
-        virtual void commitText (const InputContext * context,
+        virtual void commitText (InputContext * context,
                                  const std::string &commit_text) = 0;
 
         /**
@@ -108,7 +108,7 @@ public:
          * This method is triggered by InputContext when input text is
          * changed.
          */
-        virtual void inputTextChanged (const InputContext * context) = 0;
+        virtual void inputTextChanged (InputContext * context) = 0;
 
         /**
          * \brief Notifies cursor is changed.
@@ -116,7 +116,7 @@ public:
          *
          * This method is triggered by InputContext when cursor is changed.
          */
-        virtual void cursorChanged (const InputContext * context) = 0;
+        virtual void cursorChanged (InputContext * context) = 0;
 
         /**
          * \brief Notifies preedit text is changed.
@@ -125,7 +125,7 @@ public:
          * This method is triggered by InputContext when preedit text is
          * changed.
          */
-        virtual void preeditTextChanged (const InputContext * context) = 0;
+        virtual void preeditTextChanged (InputContext * context) = 0;
 
         /**
          * \brief Notifies auxiliary text is changed.
@@ -134,7 +134,7 @@ public:
          * This method is triggered by InputContext when auxiliary text is
          * changed.
          */
-        virtual void auxiliaryTextChanged (const InputContext * context) = 0;
+        virtual void auxiliaryTextChanged (InputContext * context) = 0;
 
         /**
          * \brief Notifies candidates are changed.
@@ -143,7 +143,7 @@ public:
          * This method is triggered by InputContext when candidates are
          * changed.
          */
-        virtual void candidatesChanged (const InputContext * context) = 0;
+        virtual void candidatesChanged (InputContext * context) = 0;
     };
 
     /**
@@ -164,7 +164,7 @@ public:
     enum CommitType {
         /** Commits a input text directly. */
         TYPE_RAW,
-        /** Commits a selected text and rest input text. */
+        /** Commits a phonetic symbols, mainly used for Bopomofo. */
         TYPE_PHONETIC,
         /** Commits a selected text, focused conversion text and rest text. */
         TYPE_CONVERTED,