BibleTime1Refactoring

From BibleTime

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

Moving from KDE4 to QT4 only

We are currently trying to get less and less dependend on KDE and move to pure Qt. Here is a list of remaining components that need to be discussed/ported.

Actions

I have suggested elsewhere that we could write our own BtAction class. It could inherit KAction now and QAction later.

  • we can probably move straight to QAction. We might lose hotkey configuratbility for now, but that is ok. --mgruner
    • another reason for using BtAction was that we could simplify creating the actions greatly if we rewrote the configuration system. But it's not for this moment.
  • cinfodisplay has kstandardaction copy, display windows use kactions.
    • I ported all other classes where kaction was used, I think. Eelik 00:39, 10 January 2008 (CET)

Accelerator (shortcut) settings

Accelerator editor is quite important in KDE world. It is good to have configurable shortcuts anyways. We could write our own KActionCollection which provides Actions to the KDE shortcut editor widget. Later we could reimplement the relevant parts of the API and and use our own shortcut editor. We will loose the automatic checking of global shortcuts etc., but that is the price.

Dialogs

Configuration Dialog

Config dialog is a KPageDialog. There is the new BtConfigDialog to which it should be ported using Bookshelf Manager as model. Not difficult.

Search Dialog

CSearchDialog is a KDialog. Should be easy to port.


Widgets

Font chooser

This is quite important widget which comes from KDE. Eventually we have to replace this with our own widget. Maybe we can take code from the KDE library?

  • needs to be evaluated. We should not copy larger amounts of code. --mgruner

Commentary editor font chooser

Commentary editor uses KDE classes for choosing font, size and color.

KHistoryComboBox

Editable combo box with history, in search dialog. Must be replaced with a QComboBox subclass. Maybe some code could be taken from the KDE library but it's not trivial.

KHTML > Webkit

The only remaining big part of KDE that cannot yet be replaced. This needs to be evaluated. I suppose that only after a QT 4.4 release (which will contain webkit) we can try to switch. We also need to evaluate the API (DOM access etc.). --mgruner

  • The WebKit API will be more complete in Qt 4.5, 4.4 lacks DOM access. Eelik 01:13, 12 April 2008 (CDT)

Platform independence: dirent.h etc.

CSwordBackend uses dirent.h which may be unix dependend. CSWordModuleInfo uses some header files which may be unix dependend.

  • The Sword library seems to use getenv("HOME") internally. Maybe it's part of the platform independent POSIX?. These have to be checked case by case. We have to be sure that we use the same $HOME which Sword uses. Is it possible that QDir::homePath() is not the same as getenv("HOME") in some cases? Maybe we should just use getenv and wrap it in our code. I have already created DirectoryUtil::getUserHomeDir(). Eelik 19:31, 23 March 2008 (CET)

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)

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

Bookmarks

  • Bookmarks index need code refactoring. It comes from the old one where there were 9 (sic!) classes for bookshelf/bookmark items but only three should now be needed IMO. Creating the tree and view is unnecessarily complex and it still includes functionality for the module tree which is now in other directory/classes.


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

  • I hate modal dialogs
    • For example I want to change font for some module. Now I have to close the config dialog or move it away to see the changes. Also when installing modules or doing anything which takes time: I don't want to just wait but do something else with the application.
    • Config dialog is easy to make nonmodal. KDE4 HIG says nonmodal config dialog is good.
  • Threaded, non-blocking indexing
  • 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
  • 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.
  • How about my suggestion regarding the BT2 navigation widget?
  • 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).
  • 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.
  • 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.


  • "Help" and "Search" buttons are in weird places in Search dialog. Usually in dialogs Help is next to Close/Ok/etc. Search could be next to search terms editor, it feels more logical to start searching from there.
  • 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.
    • We had this before, and decided against this. We wanted a system that is simple for the user (one syntax), fast, and powerful. Using CLucene directly will offer us much more possibilities than the very limited sword interface. With Sword we had a lot of problems in this area, which is why we made this decision. We can talk about improving the search facilities and indexing, but I strongly disagree with your suggestion here. Please discard this point. --mgruner
    • I won't do it against your will but I would like to know more about the problems. As far as I can see they can be avoided. I take your word about the clucene search, there is no need to use Sword indexed search, I'm talking about the nonindexed search. Eelik 17:24, 24 May 2008 (UTC)
    • 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.

Ideas from Martin, explanation needed

  • B: Mainindex refactoring
    • put a box above it that allows to input a filter string which limits the items displayed
      • I'll write something on this, read on... Eelik 18:39, 7 November 2007 (CET)
      • What do you think, does the grouping and hiding abilities help so much with a plethora of modules that this becomes unnecessary? I find these features quite handy, it's now much more easy to find wanted modules. Eelik 13:59, 10 January 2008 (CET)
        • I still think that a filter box would be cool. Switching to flat view once you enter some chars is ok for me. --mgruner
Retrieved from "http://devel.bibletime.info/wiki/BibleTime1Refactoring"
Personal tools