Martin Gruner wrote:
> Will this be a part of Sword?
>
> Troy, what do you say?
Since most of our frontends have some type of verse list functionality,
I would like for us to have something common in the engine we can all
use. This will also benefit our users, allowing them to share these
between applications. We would all have to agree on an interface
though, so I'd appreciate hearing from other frontend developers on the
proposed functionality and interface. I would be particularly
interested in whether you think a 'list' concept meets enough needs to
warrant a mechanism. BibleCS has basic verse lists, and also bookmark
trees. The bookmark trees seem more useful to me, but I would not have
a straight forward path to modify BibleCS to use a 'PassageList'
mechanism for trees.
I have some other comments below.
SWMgr is probably not the best place for this functionality. SWMgr was
our first 'manager' create 15+ years ago, and now that the engine has
grown considerably, this should probably be renamed to something like
SWModuleMgr, as its main purpose is to be a factory to hand back virtual
base SWModule * objects.
Are we planning to handle any type of key lists with this interface?
e.g., both Verse and GenBook references?
We also try to keep the std namespace out of the public interfaces the
best we can. It makes bindings easier to implement, thus, where the
interface methods accept std::string, they should accept const char * or
SWBuf if they are intentionally non-const.
I would suggest something like:
class KeyListMgr {
public:
KeyListMgr(cont char *configPath);
}
modeled after the LocaleMgr.
This would add a new subdirectory to our config root (along with
mods.d/, modules/, locales.d/), something like keylists.d/, and I'm sure
everyone would like to honor a ~/.sword/keylists.d/ as well.
If we are planning to go all out and extend the list interface to a tree
interface, maybe a more generic name like BookmarkMgr would be better
suited.
I realize this doesn't map directly to the purpose that Jonathan
intended. I don't know if there is an easy delineation to give us
multiple uses.
Just my initial thoughts. Looking forward to the conversation.
-Troy.
>> PassageList API:
>> typedef PassageListMap std::map<std::string, sword::PassageList>;
>>
>> /**
>> Returns the passage list map, which maps unique names to passage lists.
>> */
>> PassageListMap SWMgr::getPassageLists();
>>
>> /**
>> Creates a new passage list with the given name, and adds it to the
>> passage list map.
>> There must not already be a passage list with the given name.
>> */
>> PassageList SWMgr::addPassageList(std::string name);
>>
>> /**
>> Creates a new passage list with the given name, and initialises it with the
>> given list of passages.
>> */
>> PassageList SWMgr::addPassageList(std::string name, ListKey passages);
>>
>> /**
>> Removes the given passage list.
>> Returns true on success, and false on failure.
>> */
>> bool SWMgr::removePassageList(PassageList);
>>
>> /**
>> Removes the passage list with the given name.
>> Returns true on success, and false on failure.
>> */
>> bool SWMgr::removePassageList(std::string name);
>>
>> /**
>> A passage list must have a unique name to identify itself.
>> It may also have a description of the list, which can be used by the user.
>> */
>> PassageList
>> ===========
>> PassageList::get/setName()
>> PassageList::get/setDescription()
>>
>> /**
>> Adds the given passage to the end of the passage list.
>> */
>> PassageList::addPassage(PassageEntry passage);
>> PassageList::addPassage(VerseKey passage);
>> PassageList::moveUp(int index);
>> PassageList::moveDown(int index);
>>
>> /**
>> Removes the given passage entry from the list.
>> */
>> PassageList::removePassage(PassageEntry passage)
>> PassageList::removePassage(int index)
>>
>> /**
>> Sorts the passage list. At present, this will only support sorting it in
>> canonical order, but in the future, other sort orders may be supported.
>> */
>> void PassageList::sort(PassageListSortOrder order)
>>
>> /**
>> Gets a list key with all the passages in the passage list.
>> */
>> ListKey PassageList::getListKey();
>>
>> /**
>> Creates a new passage list with the same passages as this passage list, but
>> with the given new name.
>> */
>> PassageList PassageList::clone(std::string newName)
>>
>> /**
>> Returns true if the given verse is contained in the passage list.
>> */
>> boolean PassageList::containsVerse(VerseKey verse)
>>
>> /**
>> This class wraps around a VerseKey to allow additional attributes to be
>> attached to an entry in a passage list. At present, the main addition that
>> is planned is attaching comments to passage entries.
>> */
>> PassageEntry
>> ============
>> /**
>> Creates a passage entry from the given verse.
>> */
>> PassageEntry(VerseKey verse)
>>
>> /**
>> VerseKey PassageEntry::get/setPassage()
>>
>> /**
>> For later extension.
>> */
>> std::string PassageEntry::get/setComment()
>>
>> _______________________________________________
>> sword-devel mailing list: sword-devel@crosswire.org
>> http://www.crosswire.org/mailman/listinfo/sword-devel
>> Instructions to unsubscribe/change your settings at above page
>
>
>
> _______________________________________________
> sword-devel mailing list: sword-devel@crosswire.org
> http://www.crosswire.org/mailman/listinfo/sword-devel
> Instructions to unsubscribe/change your settings at above page
_______________________________________________
sword-devel mailing list: sword-devel@crosswire.org
http://www.crosswire.org/mailman/listinfo/sword-devel
Instructions to unsubscribe/change your settings at above page
