Difference between revisions of "DevTools:Code Examples"
Underlined (talk | contribs) m (→C++) |
Underlined (talk | contribs) m (→Install Manager) |
||
Line 148: | Line 148: | ||
==== Install Manager ==== | ==== Install Manager ==== | ||
− | The [http://www.crosswire.org/~ghellings/svnclassdocs/classInstallMgr.html InstallMgr] class is pretty easy to work with and will manage most of the install sources itself. When instantiated, it will generate the list of sources (which can later be accessed from its public attribute, <tt>sources</tt>) from the InstallMgr.conf located at the path provided in the constructor's first paramater, <tt>privatePath</tt>, if any. If no InstallMgr.conf exists, you can use the method <tt>refreshRemoteSourceConfiguration()</tt> to retrieve a list of sources remotely. <tt>refreshRemoteSourceConfiguration()</tt> will return 0 upon success. | + | The [http://www.crosswire.org/~ghellings/svnclassdocs/classInstallMgr.html InstallMgr] class is pretty easy to work with and will manage most of the install sources itself. When instantiated, it will generate the list of sources (which can later be accessed from its public attribute, <tt>sources</tt>) from the InstallMgr.conf located at the path provided in the constructor's first paramater, <tt>privatePath</tt>, if any. If no InstallMgr.conf exists, you can use the method <tt>refreshRemoteSourceConfiguration()</tt> to retrieve a list of sources remotely. <tt>refreshRemoteSourceConfiguration()</tt> will return 0 upon success. If -1 is returned, you should check to see if <tt>isUserDisclaimerConfirmed()</tt> returns false; <tt>isUserDisclaimerConfirmed()</tt> must return true to get passed the first process when refreshing the remote source. |
When working with the InstallMgr class, it will be useful to have a SWMgr object lying around <i>before</i> installing any new modules and refreshing any remote sources. This is so you can provide some additional module information to the user with the help of <tt>InstallMgr::getModuleStatus()</tt>. You rely on the return value of <tt>InstallMgr::getModuleStatus()</tt> to display the list of modules and whether they are new (not installed) (<tt>InstallMgr::MODSTAT_NEW</tt>), already installed (<tt>InstallMgr::MODSTAT_SAMEVERSION</tt>), an update is available (<tt>InstallMgr::MODSTAT_UPDATED</tt>), et cetera. | When working with the InstallMgr class, it will be useful to have a SWMgr object lying around <i>before</i> installing any new modules and refreshing any remote sources. This is so you can provide some additional module information to the user with the help of <tt>InstallMgr::getModuleStatus()</tt>. You rely on the return value of <tt>InstallMgr::getModuleStatus()</tt> to display the list of modules and whether they are new (not installed) (<tt>InstallMgr::MODSTAT_NEW</tt>), already installed (<tt>InstallMgr::MODSTAT_SAMEVERSION</tt>), an update is available (<tt>InstallMgr::MODSTAT_UPDATED</tt>), et cetera. | ||
+ | |||
+ | To install modules you would of course use the method <tt>installModule()</tt>. Local installs make use of only the first three parameters; remote installs make use of the first and last two while passing 0 to the second parameter. Note, the name of the module you want to install is obtained through <tt>SWModule::Name()</tt>. <tt>installModule()</tt> will return 0 on success. | ||
=== Python === | === Python === | ||
=== Java === | === Java === |
Revision as of 03:12, 20 January 2010
This page was started to provoke developers who know how the SWORD API works to post simple, everyday code examples that anyone can use. By "simple", I mean something that can work within a static function if possible.
Contents
Examples
C++
Get Modules Example(s)
The following example is for obtaining modules that are installed in the user's SWORD repository. This example also makes slight use of the Qt4 GUI library. The following function takes one parameter, the type of the modules you want to retrieve. Unless stated otherwise, there are up to 4 different types to choose from:
- "Biblical Texts"
- "Commentaries"
- "Lexicons / Dictionaries"
- "Generic Books"
Code
#include <QStringList> #include <swmgr.h> #include <swmodule.h> QStringList getModules(const char* modType) { QStringList modules; SWMgr library; ModMap::iterator it; for (it = library.Modules.begin(); it != library.Modules.end(); it++) { SWModule *module = (*it).second; if (!strcmp(module->Type(), modType)) modules << module->Name(); } return modules; }
Example Usage
QStringList bibles = getModules("Biblical Texts");
Note: Map and image modules may potentially employ any of the basic module types (Genbook, LD, Com, or Text). The most consistent way to differentiate between a map or image module and the basic module types is to look for the configuration entry "Feature":
if (QString(module->getConfigEntry("Feature")) == "Images") // do something ...
Get Biblical Book Names Example(s)
Obtaining a list of the canonical books of the Bible doesn't necessarily require any SWORD classes (though in the following example we'll be using SWConfig). A default SWORD installation installs the file abbr.conf at /usr/share/sword/locales.d on a Unix-like system (on Windows it may be located at C:\Program Files\CrossWire\The SWORD Project\locales.d). The syntax of the file is the same as any INI file. Therefore we just need to parse the file for the canonical books; so technically any configuration file parser that can parse INI files will do. The section we want to obtain from abbr.conf is called Text. (Again, the example uses a Qt4 class, QStringList.)
Code #1
#include <QStringList> #include <swconfig.h> QStringList getBiblicalBooks() { QStringList books; SWConfig config("/usr/share/sword/locales.d/abbr.conf"); ConfigEntMap::iterator it; for (it = config["Text"].begin(); it != config["Text"].end(); it++) { books << (*it).first.c_str(); } return books; }
After obtaining all the Bible book names, you can obtain their abbreviations with SWConfig, again:
SWConfig config("/usr/share/sword/locales.d/abbr.conf"); const char *GenAbbr = config["Text"]["Genesis"];
But, of course, since it's not necessarily safe to assume that you would have an abbr.conf file lying around, the above example isn't necessarily practical. Nevertheless, hopefully, its existence provided some insight on SWConfig. The more proper way to obtain a list of Biblical, canonical book names is through the use of VerseKey. VerseKey has a public member that stores the number of books for each testament—BMAX. BMAX[0] has the number of Old Testament books, and BMAX[1] has the number of New Testament books, which will be useful for use in a for loop.
Code #2
QStringList getBiblicalBooks() { QStringList books; VerseKey vk; for (int b = 0; b < 2; b++) { // Set the Testament number to retrieve book names from that Testament. // Add 1 to b since the Testament numbers don't start at 0. vk.setTestament(b+1); for (int i = 0; i < vk.BMAX[b]; i++) { // Add 1 to i since the book numbers don't start at 0. vk.setBook(i+1); books << vk.getBookName(); } } return books; }
Getting Generic Book Table of Contents
TreeKey is necessary for traversing the generic book's tree. I am going to let the comments and function names speak for themselves here. Assume that module points to a SWModule object.
#include <swmodule.h> #include <treekey.h> void getGenBookTOC(sword::TreeKey *tk, Class *parent) { // if no TreeKey, then obtain one from the module if (!tk) tk = dynamic_cast<sword::TreeKey*>(module->getKey()); // Move onto the first child if any if (tk->firstChild()) { // Get the first child's information before moving onto the next do { // Retrieve the name so we can use it to get // the GenBook's content later QString text = tk->getText(); // Keep track of the information for custom implementation Class *item = storeItemInfoForLaterUse(parent, text); // If it has children, dive into it if (tk->hasChildren()) getGenBookTOC(tk, item); } // Move onto the next child if any while (tk->nextSibling()); // Move up one level in case one of the children had children tk->parent(); } }
How you go about in implementing this is up to you.
Install Manager
The InstallMgr class is pretty easy to work with and will manage most of the install sources itself. When instantiated, it will generate the list of sources (which can later be accessed from its public attribute, sources) from the InstallMgr.conf located at the path provided in the constructor's first paramater, privatePath, if any. If no InstallMgr.conf exists, you can use the method refreshRemoteSourceConfiguration() to retrieve a list of sources remotely. refreshRemoteSourceConfiguration() will return 0 upon success. If -1 is returned, you should check to see if isUserDisclaimerConfirmed() returns false; isUserDisclaimerConfirmed() must return true to get passed the first process when refreshing the remote source.
When working with the InstallMgr class, it will be useful to have a SWMgr object lying around before installing any new modules and refreshing any remote sources. This is so you can provide some additional module information to the user with the help of InstallMgr::getModuleStatus(). You rely on the return value of InstallMgr::getModuleStatus() to display the list of modules and whether they are new (not installed) (InstallMgr::MODSTAT_NEW), already installed (InstallMgr::MODSTAT_SAMEVERSION), an update is available (InstallMgr::MODSTAT_UPDATED), et cetera.
To install modules you would of course use the method installModule(). Local installs make use of only the first three parameters; remote installs make use of the first and last two while passing 0 to the second parameter. Note, the name of the module you want to install is obtained through SWModule::Name(). installModule() will return 0 on success.