BibleTime1Refactoring

From BibleTime
Revision as of 10:44, 16 July 2011 by Jotik (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Because of lack of human resources, we decided not to start BibleTime2 but instead try to improve BibleTime 1.x slowly by a) refactoring of code and UI and b) adding of features. This page collects the relevant ideas for refactoring. Please post detailed descriptions of what has to be done, and if you can suggest how it can be done effectively.

Contents

Approved refactoring items, to be done

Code refactoring discussion

General code refactoring ideas

Ideas from Eeli

Class naming convention

Starting a class name with "C" is the old convention. There were some "BT" classes also and I have added a couple of them. For some reason I hate the C. I would like "Bt" with capital B and small t (having more than one capital together is bad, even common names like Xml, Html and Dom should be written with small letters because it enhances readability and is easier to write). It shouldn't be too hard to do semiautomatic replacement throughout the code. Eelik 13:45, 10 January 2008 (CET)

  • Existing classes shouldn't be changed unless there are major refactoring/rewriting going on. The reason is UI translations: If the class name changes, it must be retranslated because Qt Linguist isn't intelligent enough to know about it. If you overhaul a class so that many UI strings are changed anyways, please change the class name to Bt*. --Eelik 14:31, 3 December 2009 (UTC)

Config system

  • Configuration system does not feel very sound
    • I have been thinking about an alternative...
      • This is a major change and needs careful planning and discussion. --mgruner
    • I've been thinking about using QSettings (or some subclass or specific singleton instance of it) directly, since doing so would allow us to skip this whole magic. We would just need to formalize the format of the configuration file. -- jotik

File and directory names

There are some file and directory names spread across the code files, like "/.sword/sword.conf". These should all be in one place, either in directoryutil or in config backend.

Ideas from Martin, explanation needed

  • B: We have much hand-crafted UI code. It would be desirable, but a lot of work, to transform that into using QT designer for UI creation.
    • Actually, I am not so sure any more if this would be a good idea. Wizard code can also be problematic. Perhaps we should aim at doing all NEW ui stuff with designer, but not try to convert existing code? What do others think?
    • Designer is good for designing the interface from scratch. But when most of it is done changing or adding new features is easier by writing the code directly into the c++ files. --Eeli
    • I rewrote some search dialog code this way:
      • use qtdesigner to design a new widget from scratch (using the old layout)
      • take the code from the generated .h file and put it into the handmade .cpp file
      • I noticed that "wizard code" really was problematic.
      • Designer is good for fast design but not for serious careful UI development. This is my opinion. --Eeli
  • C: Rewrite filters, the code is rotten; increase OSIS support
    • OSIS support is very important after we have finished the port. Eelik 15:07, 28 November 2007 (CET)
  • C: Introduce unit testing, at least for the backend
  • more to follow...

Feature refactoring/additions

Ideas from Eeli, explanation needed

  • Starting editing Personal commentary is not easy
    • Natural way to make a personal commentary is File->New (I think user should have possibility to write many independent personal commentaries, but this may be beyond "refactoring")
    • Changing read/write mode from Bookshelf is not intuitive
    • The Sword library should have API to create new modules. Research this. (Xiphos has ability to create modules, see the code there.)
  • Font dialog:
    • Use some meaningful text in preview area: i18n'ed text is not enough. If I want to use some font for Hebrew text I would like to see how the font looks like with Hebrew text, not with English or Finnish text.
  • Per module/displaywindow display option
    • The reason for this is that the user does not necessarily want the same options for all modules, especially because the modules behave differently even with the same features.
    • User could choose display options for modules in bookshelf index with RMB menu item. Those options could be overridden in a display window.
    • Per module options would be automatically used when modules are opened in a new display window, even if it is a parallel display.
    • User could check "Override module display options" in Display Options menu in the window and after that the different display options would be enabled in the menu. Now they could be checked and they would affect all modules in this display window (but not the same modules in other windows).
    • Some users of Xiphos have said they like this feature in Xiphos, so it's a proved use case.
  • Bookshelf index.
    • Module index could have more RMB menu actions:
      • update (per module/all)
      • per module display options (could be overriden in display window; see above)
    • Module index could have some indicator for "updateable" if there is a newer version in repository
    • The menu should not be bloated, so only reasonable menu structure would be one "Manage works" item and for example "Add works...", "Update", "Remove _module_", "Check for updates" subitems. Then indicating updateable works with color would be reasonable, but not if there is no update menu item.
  • If there are no works installed, show a short help text ("There are no works installed. Install new Bible translations and other works by opening the Bookshelf Manager from Settings menu or clicking this button:") and "Open Bookshelf Manager" button in bookshelf window.
  • Automatic update check for modules, or easily accessible manual check. Currently the user who wants to find if any modules have been updated in repositories has to open the Manager and refresh a source (which is already much better than it has been previously). See Bookshelf index RMB menu above.
    • Another possibility: config option to check the updates (threaded in the background) in startup or periodically.
    • We could also notify about new modules which have been added after the last repository cache update. This means saving the previous cache before the update.


  • Redesigning the search system. BibleTime has taken away the Sword search engines which is not a good decision, IHMO. Search is one of the most important features of a Bible application. Scholars and serious students need reliable results, and even commercial programs are not 100% reliable. Many people want to check the results with more than one program. The Sword library gives more than one search engine for free, why not use it? Also the search methods differ and that is useful. And as someone in sword-devel once said, it's annoying to be forced to index the module if you want to search it once.
    • This has been discussed on the mailing list. We can consider adding e.g. the regexp search using the sword engine. The current engine will stay.
    • A "quick search", immediately available and visible in the main window, would be nice. It should be very simple: widget for the search string, widget for the module(s) (combobox which include only the currently visible modules or something like that), and the result list.
  • Qt has "buddy labels". It means that they can have Alt+letter shortcuts and this shortcut focuses the buddy widget, not the label. Many tree/listviews have now headers acting as labels. It prevents using shortcuts. I have changed Search Range chooser to use buddy labels. Test it to see how it works. The mainindex and mag views could have buddy labels; there would be no need for extra QActions and hard-to-remember shortucts to make them focusable by keyboard. All label shortcuts are clearly visible in GUI.
  • Lexicon keychooser redesign. Some ideas:
    • Create the string list but don't populate the listview with strings. When the list is opened it is populated with only as many strings as there can be visible. (Do this because creating the listview takes time with long list, but creating a long string list is very quick.)
    • The scrollbar must then be overridden, too. It would show as a tooltip the entry range when the user moves mouse over it (e.g. when the mouse pointer is in the middle of the bar it shows "Jordan - journey"; in the upper corner it shows "a - abba"). When the user clicks the bar the slider moves directly to that position and the list view is updated to reflect the position. Clicking the arrow buttons would move page by page, not line by line. Line by line movement is not necessary.
    • These changes would not be radical for the user but might make the keychooser a bit more usable. Technically this seems to be realistic after quickly reading the Qt docs.
    • Another option might be to use model/view. It would be a quick and easy solution if it takes away creating all the items at one pass. Read the docs first.
  • Show larger/smaller section in text view. For Bibles and commentaries: user can select between one verse and one chapter at a time. For genbooks: a section depends on the module. For genbooks it's more difficult than for others because it can be reasonable to show only one level, or some level and all its sublevels. Maybe three actions: Show subsections (true/false), show larger section, show smaller section.
  • Ability to show any verse range (possibly limited to certain amount of chapters though, for the sake of jealous publishers) and even several ranges.

Window system

Please try the e-Sword Window application if you have possibility. It has some ideas which I would like to see in BibleTime. Actually I planned this even before I saw the current e-Sword window system, but it happens to have some similarities.

We could have top-level tabs, like in modern web browsers or many other applications. They could be turned on/off at will. That feature could be added to the current window system (I'm talking about BibleTime's internal window system). It would actually be a kind of replacement for the current Session system - the user could change between "sessions" by switching between the tabs. It would be also possible to keep the Session system so that it would save also the tabs. That would ensure the widest flexibility possible. (This tab feature isn't in e-Sword.) See New Window Arrangement Modes

It's another thing what happens inside the main window area. We now use the default Qt MDI window system. It works quite well but has some drawbacks. One of the biggest problems is that one can't resize the windows effectively. We need splitters (QSplitter) to do that. Maybe it's possible to use the Qt window system with splitters? But I doubt it. At least the automatic window adding/removing wouldn't work. It means that we must create our own layout engine for the cases when the user opens a new window or closes a window.

Now the user has no chance to tell where he wants a new window to be opened. We could add capability to drag and drop a work from the Bookshelf to the window area (or move existing windows). When the user moves the mouse over a work in the Bookself, the window system would show a box (an outline, a shaded/transparent box or whatever) in the place where the work would be opened by default. That would be a small enhancement to the current system. But the user could also drag and drop the work to any place. That feature would require a specific engine to take care of the positioning. See the e-Sword solution for an example. I just don't like the details of the e-Sword implementation. It shows icons over which you can drop the new window. They represent left/right/top/bottom areas of the existing window which will then be resized to give space for the new window. I would rather use some kind of box which shows where the new window would be placed. (The Qt dockable windows have a bit similar feature but I don't like the implementation. It's quite difficult to use.)

But we could go even further. e-Sword has tabs inside the subwindows. We could do the same, like in the Qt dockable windows. If the user drags a work, he could drop it in the middle of an existing window, and the the old and new works would become tabs in one window. The user should of course be able to drag and drop both existing windows and tabs and thereby move them, combine them or separate them. See New Window Arrangement Modes

We should change to use MDI style toolbars. The toolbars would not be shown on each module window, but instead the main window toolbar would show the toolbar items for the current module window. This saves a lot of space and the main window toolbar is wide enough for many items.

Adding all these features together would create the most versatile and flexible system imaginable.

Ideas from Thomas

  • Work on algorithm/sub-routine so serve up some seasonal themes, for instance a Christmas theme, Easter theme, Pentecost, others as we deem fit. We will likely need the services of a real graphic artist to bring this to proper fruition
    • Seasonal bibletime.png, bibletime.svg and startuplogo.png
    • CSS that we can pass on the commandline to override default Qt colour schema
  • More Oxygen-like icons, Raoul has a good grasp on this so far, I would like to also Oxygenify our "corporate logo" for use in the app, website, blog etc
  • With a possible .0 release it may be time for a completely reworked startuplogo.png that matches our Oxygenification

Ideas related to mobile development (Konstantin)

  • Improve bounds calculation for Bible/Commentary modules. It would take up to 40 second to calculate result of this function.
    • Calculate on demand (yet ready in mini branch).
      • Good idea --jotik 05:44, 16 July 2011 (CDT)
    • Store calculated data somewhere in file.
      • Good idea --jotik 05:44, 16 July 2011 (CDT)
    • Maybe calculate scope of present verses as ListKey, and use it to not display empty verses.
      • Maybe you know better than I do. --jotik 05:44, 16 July 2011 (CDT)
  • Refactor Search system, there are several parts of code distributed among backend/frontend. Move BtSearchOptionsArea::SeatchType, BtSearchResultArea::highlightSearchedText and CSearchDialog::prepareSearchText to backend. There should be just one class to which i give all parameters (text, search type, modules for search) and receive results and signals/slots if them are necessary. Maybe i would also select search engine: BibleTime Clucene, Sword CLucene, Sword Plain Search.
    • Good idea --jotik 05:44, 16 July 2011 (CDT)
  • Related to Search Index generation. On mobile device building index for KJV would take up to 5 hours. Not every device would live such time from internal battery on full cpu load and not every user would be so patient. It is better for mobile devices to download built indexes as most of them able to go to the Internet. Afaik Sword can download search indexes for own CLucene engine.
    • Good idea. I hope the format of the indexes is portable across different versions of sword/clucene etc. --jotik 05:44, 16 July 2011 (CDT)
  • Install manager have scattered parts of code too. There should be one object in backend that generates necessary signals (for module installation progress), receives slots and gives information about available repos and modules.
    • Agreed. We haven't had the time to do this ourselves up till now. You're welcome to try. --jotik 05:44, 16 July 2011 (CDT)
  • Bookmarks and other Verse User Related data (maybe history, user annotations because Personal Commentary would not be good for environment with different v11ns, user thematic verse lists, i also would like to color verses or selected verse text) should be on backend side, frontend should only call initialize, get or set this data.
    • I'm not sure on all of these things, but the general idea is fine. Its also the backend which needs to be modularized into parts which communicate with Sword, parts which deal with other BibleTime things, like configuration etc. --jotik 05:44, 16 July 2011 (CDT)
  • Also BibleTime Mini now is more light weighted and can run in BibleTime environment. Maybe add in help menu item like "Try BibleTime Mini". This would also simplify translation process.
    • You mean a menu item which would direct the user to some website? Fine with me after BibleTime mini becomes beta-quality, and a confirmation dialog is shown before directing the user to the website. --jotik 05:44, 16 July 2011 (CDT)
  • CInfoDisplay routines also would be moved to backend (decode* and setInfo-s). Some kind of converter from HitTestResults into descriptive string used in CInfoDisplay.
    • I think the setInfo methods should stay in the frontend. The decode* methods have parts which belong to the backend and to the frontend, and these need to be separated. --jotik 05:44, 16 July 2011 (CDT)
Retrieved from "http://devel.bibletime.info/wiki/BibleTime1Refactoring"