Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdelibs@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 71 insertions, 0 deletions

diff --git a/kspell2/README b/kspell2/README
new file mode 100644
index 000000000..6dfbc1601
--- /dev/null
+++ b/kspell2/README
@@ -0,0 +1,71 @@
+This is KSpell 2 beta implementation. KSpell 2 is completely in
+process and is plugin based.  
+
+The main class in the KSpell 2 is the KSpell::Broker. Broker is
+responsible for loading all the plugins and creating the actual
+dictionaries.
+
+Dictionaries are abstracted in the KSpell::Dictionary object which
+encapsulates all spell-checking functionality.
+
+You'll notice that the Broker is being created via the 
+Broker::Ptr Broker::openBroker( KSharedConfig *config =0 );
+call. The Broker is a shared object and the reason for this construct
+is very simple:
+- most application would need to have a few Broker objects (one for
+the dialog dictionaries, one for the background spell checking, one
+for the suggestion dictionaries) and because Broker loads plugins on
+creation it would be ineffective to have a few redundant Broker
+objects in one application,
+- each Broker maps to a configuration file. If one Broker would change
+in the application, all others would have to reparse and repopulate
+the options, which would be really inefficient.
+
+Due to the above you deal with the broker via the Broker::Ptr
+interface. 
+
+Once you have the Broker object in your application, you can ask it
+for a Dictionary of some language. If such a dictionary is available
+you get it back as a Dictionary class and you use that class to do the
+actual spell checking.
+
+Broker on construction checks for available KSpell::Client's which are
+loaded as dynamic plugins. It's the actual KSpell::Client that gives
+the broker the KSpell::Dictionary. 
+One can specify a default client and the default language for a Broker
+theough the settings() method and the KSpell::Settings class which it
+returns. 
+
+Also note that you can have dictionaries for multiple languages in
+your application.
+And most importantly the interface to KSpell::Dictionary is
+synchronous so once you pass a word to check you don't have to wait
+for any signals - you get corrections right back.
+Sample usage of KSpell 2 looks like follows:
+
+#include <kspell_broker.h>
+#include <kspell_dictionary.h>
+using namespace KSpell;
+
+
+Broker::Ptr broker = Broker::openBroker( someKSettingsObject );
+Dictionary *enDict = broker->dictionary( "en_US" );
+Dictionary *deDict = broker->dictionary( "de_DE" );
+
+void someFunc( const QString& word )
+{
+    if ( enDict->check( word ) ) {
+        kdDebug()<<"Word \""<<word<<"\" is misspelled." <<endl;
+        QStringList suggestion = enDict->suggest( word );	
+        kdDebug()<<"Suggestions: "<< suggestions <<endl;
+    }
+
+    QStringList suggestions;
+    if ( deDict->checkAndSuggest( word, suggestions ) ) {
+       kdDebug()<<"Wort \""<<word<<"\" ist fehlbuchstabiert." <<endl;
+       kdDebug()<<"Vorschlage: "<< suggestions <<endl;
+    }
+}
+
+delete enDict;
+delete deDict;