[kln2-devel] new code structure

[Marek W. <Mar...@fu...>]

Hi e-body,

I have just committed new version of two more exercises:
piano-key-to-note-name (functional) and note-name-to-piano-key
(almost working ;).

Now, in terms of code structure this is a MAJOR update. Please,
find some time to go through (or at least glimpse at) the
following description. I used piano keyboard as an example. I
know, we were to move toward the guitar fret asap, but this is a
real reconstruction of foundations of kln2 and I thought making
it work on an easier example (which the piano keyboard is) was
really needed.

==========================

All objects have been separated into few types (the separation
is not complete, because I kept the old staff2name exercise
untouched for now):
* KLearnNotes2 class - should be responsible for mainWidget,
  general setup [like note naming convention ('notation')],
  menus, help, input handling (keyboard, voice recognition, in
  future: pitch recognition, midi kbd input etc.), choosing a
  type of an exercise
* different graphical test widgets which are collections
  randomObjects: for now there is a NameButtonsBox and
  PianoKeyboard; once the staff code will be extracted in the
  analogous way we will have easy to setup "piano-to-staff,
  staff-to-piano, name-to-staff and staff-to-name"  exercises
  (the last one was the only kln2_v1.1 exercise)
* Exercise class which binds everything together.

Now, the idea is that to recycle widgets and use e.g.
PianoKeyboard for different kinds of exercises it should
communicate with other widgets by signals, not direct function
calls. This way it is up to Exercise class which slots will be
connected to which widgets, and thus how the particular exercise
is setup.

Example in piano2name exercise:
There are two widgets, NameButtonsBox and PianoKeyboard. When
user clicks on name checkboxes (and, say, deactivates one of the
buttons) the NameButtonsBox emits activeNotesChanged() signal.
Now, piano2name exercise connects it to PianoKeyboard
setupActiveQuestions() slot. This way PianoKeyboard knows it
should check which keys should be considered active. But
NameButtonsBox doesn't know to what it is connected to - in
future it could be e.g. connected to a Staff or a
GuitarFretboard etc. It's up to Exercise. The same widgets can
be used in different types of exercise without changing its
code. :) Similarly, "PianoKeyboard knows it should check which
keys should be considered active" [cite from above] but it
doesn't know which widgets are its partners at the moment - it
will call Exercise methods to check which key should be
considered active, and the Exercise (which knows what are the
parts of the test) will check this of the PianoKeyboard.

***
* It may look messy at first, but, believe me, it isn't. The rule
* is quite simple: PianoKeyboard sees only things connected to it
* by its exercise and the exercise itself. The same for
* NameButtonsBox. The same for the main kln2 window (which has its
* currentExercise). Exercise-inheriting classes are what set up
* all the communication.
***

That is also, why after putting together a pianoKey2noteName
exercise it was so easy to write a noteName2pianoKey one - the
widgets can be used both as question widgets and answer widgets.

Another thing is abstracting some common features. All
collections of RandomObjects (for now NameButtonsBox is a group
of FancyButtons and PianoKeyboard is a group of
PianoKeyboardKeys) inherit RandomObjectsContainer class which
handles all the random features: checking which RandomObjects
are active for test, during a test selecting a random question
etc.


==========================

Plans for future:
1. Well, I'm using the long May weekend to get out of town. :)
 So not much will be done by me during next two weeks (a really
 long w/e, isn't it ;).
2. Many little things in the new exercises need correcting - I
 will write an e-mail about this in a moment.
3. Once I'm back, I plan to extract all the staff code to
 another RandomObjectsContainer class; this means lots of code
 from klearnnotes2.{h,cpp} and KLNcanvasitems.{h,cpp} will be
 rearranged or even moved to a different file!!! IF YOU ARE
 WORKING ON THINGS INVOLVING THESE FOUR FILES, PLEASE COMMIT
 YOUR CHANGES WITHIN NEXT TWO WEEKS, even if your code is not
 fully functional yet. Otherwise it may be very hard and time
 consuming to understand how your changes fit into rearranged
 code. :(

Once it is done we'll have 6 exercises (staffnote-2-notename,
staffnote-2-pianokeyboard etc... I don't know if there is a
point in providing all 6), new midi outputs (timidity works ; I
hope tse3/alsa can be worked out too), Solfeggio, some new
translations. It certainly does amount to a new big release! :)

But there are at least two other things that I really fancy: the
game (which is a really cute idea, believe me) and new clefs. I
hope this could emerge in time for this new release too. :)
We'll see about it.

Another possibility (which, frankly speaking, I do like) would
be to make a release asap, just when the piano exercises start
working (leaving the old staff2note without a change and
changing it only after the next release). We'll see about it.

Anyway, it will still take some time and meanwhile I am very
much open to new ideas. Any small improvements are very much
welcome!

Regards,
Marek

-- 

     \/   /|\  Marek Wieckowski
  #####  | | |
 = . . =  \|/  Institute of Theoretical Physics
    U      |   Warsaw University
  / ~ \___ |
 <|   |    |
  > . <    |   http://www.fuw.edu.pl/~wiecko
 <<___>>   |   http://klearnnotes2.sourceforge.net