← Back to branch summary

~s-cecilio/lenmus/v5.3

« back to all changes in this revision

Viewing changes to docs/drafts/architecture/TextBookController_architecture.txt

  • Committer: cecilios
  • Date: 2007-05-19 11:39:03 UTC
  • Revision ID: svn-v4:2587a929-2f0e-0410-ae78-fe6f687d5efe:trunk:236

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/drafts/architecture/TextBookController_architecture.txt
 
1
ContentsBoxCtrol
 
2
----------------
 
3
    App independent control: html list control with image/description for items, and
 
4
    the items simulate a tree control, but tree control functionality (expand, contract, etc)
 
5
    is not in this control
 
6
 
 
7
BookContentBox
 
8
--------------
 
9
    A tree control with images. It is derived from ContentsBoxCtrol and it is like an
 
10
    abstraction layer to isolate the logical methods from the specific implementation
 
11
    so that, in future, the treeCtrol can be implemented in a different way, instead of
 
12
    deriving from ContentsBoxCtrol.
 
13
    
 
14
    - Display and internal management of the control
 
15
    - Load control data
 
16
 
 
17
    Used in:
 
18
    
 
19
BookData
 
20
---------
 
21
    Isolate books' index and toc format from internal tables structure
 
22
    - Read source books
 
23
    - Build internal data structures
 
24
 
 
25
    Used in:
 
26
    
 
27
TextBookController
 
28
------------------
 
29
    High level API to deal with eMusicBooks
 
30
    
 
31
    - Add books
 
32
    - Request to display a page
 
33
    - Request to search for a word
 
34
        lmBookData *GetHelpData() { return &m_oBookData; }
 
35
 
 
36
    - Deal with book contents (BookData)
 
37
 
 
38
    Used in:
 
39
    
 
40
        lmMainFrame
 
41
        lmHtmlWindow ?  Display() when click on a link
 
42
        lmTheoMusicReadingCtrol ? when click on "Go Back" link
 
43
 
 
44
TextBookFrame
 
45
-------------
 
46
    Frame to display eMusicBooks. Internal use by TextBookController
 
47
    
 
48
    - Manage the controls and keep their info synchronized
 
49
 
 
50
    Used in:
 
51
    
 
52
        lmMainFrame -> To pass toolbar events
 
53
        lmBookContentsBox::ChangePage() -> when clicking on an item it must request
 
54
            to display that page and to synchronize the index (?)
 
55
        lmTextBookController
 
56
 
 
57
 
 
58
 
 
59
 
 
60
 
 
61
 
 
62
App <--> TextBookController
 
63
               |
 
64
               +--> TextBookFrame
 
65
               |             |
 
66
               |             +--> BookContentBox --> ContentsBoxCtrol
 
67
               |             +--> Index
 
68
               |             +--> HtmlWindow
 
69
               |
 
70
               +--> BookData
 
71
               
 
72
         
 
73
         
 
74
         
 
75
               
 
76
Processing details
 
77
-------------------------
 
78
 
 
79
lmBookData processes the TOC file (method ProcessTOCFile) and creates an array
 
80
of lmBookIndexItem with all the book's content, and a lmBookRecord to represent
 
81
the book. This representation is flat.
 
82
 
 
83
This array is then processed by lmBookContentsBox (method CreateContents) and 
 
84
creates the array m_aTree[] with all the tree structure.
 
85
 
 
86
Method lmBookContentsBox::FormatItem() creates the html content for ContentsBoxCtrol.
 
87
The content is a collection of <tocitem> tags:
 
88
 
 
89
<tocitem 
 
90
    expand= + | - | no
 
91
    icon= open_book | open_folder | closed_book | closed_folder | page
 
92
    [img=img_filename.png]
 
93
    level='%d'     //tree level 0..n
 
94
    item='%d'      //num itemin table
 
95
    titlenum = string       //prefix (letter/number) for index title
 
96
> 
 
97
title
 
98
</tocitem>
 
99
 
 
100
 
 
101
At the begining of file ContentsBoxCtrol.cpp there is an html tag handler to process
 
102
the <tocitem> tag and cretae the html content.
 
103
 
 
104
 
 
105
Single page books (leaflets)
 
106
-------------------------------
 
107
It is possible to include single pages at first level. These 'single page' books 
 
108
will be called 'leaflets'. Use <leaflet> tag instead of <book>. It will have a single
 
109
theme but use tag <leafletcontent> instead of <theme>.
 
110
 
 
111
 
 
112
Bookmarks
 
113
--------------------------------
 
114
 
 
115
Combobox will display reference to book and page: 'book_name: title_of_page'
 
116
Array m_BookmarksPages contains the url to thge page.
 
117
Array m_BookmarksNames contains the 'book_name: title_of_page' strings
 
118
 
 
119
- Method: lmTextBookFrame::OnBookmarksSel() will display the page for the bookmark
 
120
    selected in the combobox
 
121
 
 
122
- Bookmarks are added in method lmTextBookFrame::OnToolbar(), case ID_BOOKMARKS_ADD. The
 
123
    name to display in combobox is taken from the html page title.
 
124
 
 
125
- Bookmarks are added in method lmTextBookFrame::OnToolbar(), case ID_BOOKMARKS_REMOVE
 
126
 
 
127
Bookmarks are saved and restored in methods WriteCustomization and ReadCustomization.