ConversationListBox-approach.md

@@ -43,6 +43,8 @@ The view performs the following functions:
 
 The `HtmlTextview` adds a single function to the above: parsing the provided content for `xhtml-im` content (and cleaning non-compliant content).
 
+In addition to `ConversationTextview` and `HtmlTextview`, `GroupChatControl` also influences rendering of messages by selectively passing into the ConversationTextview the fact that a message has an XHTML-IM presentation.
+
 ### Technical overview
 
 `ConversationTextview` maintains the following API to achieve the formatting functions:
@@ -126,27 +128,24 @@ In a chat with @lovetox, the following requirements were mentioned as well:
 
 ### Responsibilities of roles
 
-The role of the presentation (`HtmlTextview`) is to:
-* print_empty_line
-* print_conversation_line
-* print_encryption_status
-* print_real_text
-* print_time
-* print_name
-* print_subject
+The role of the presentation is to:
+* Render chat lines coming in from the server
+* Render chat lines going out to the server
+* Render status updates from the client, server and chat channel (join/leave/etc)
+* Update rendered lines when instructed to do so (corrected messages)
 
-which means that the `HtmlTextview` will also need to:
-* get_end_mark
-* get_insert_mark
-* (creation and updates of `HtmlTextview.get_buffer()`-tags in various places)
+which means that the presentation will also need to:
+* map message IDs to buffer regions
+  * get_end_mark
+  * get_insert_mark
 
-The role of the model (`ConvensationTextview` -- at least for now) is to:
-* correct_message [function]
+The role of the model (`ConversationContentModel`) is to:
 * add_message [function], to maintain:
   * message_list [attribute]
   * last_received_message_id [attribute]
+* correct_message [function]
 
-The role of the controller (also `ConversationTextview` -- for now) is to:
+The role of the controller (also `ConversationTextview` -- for now, but might need to be GroupChat/PrivateChat/ChatControl instead?) is to:
 * respond to user interactions
 * (open question: to network interactions as well? alternative: the model gets fed directly from the protocol stream)
 
@@ -155,4 +154,57 @@ The role of the controller (also `ConversationTextview` -- for now) is to:
 The various `print_*` functions will to be moved from ConversationTextview to HtmlTextview. This impacts:
 * gajim/chat_control:ChatControl.restore_conversation()
 * gajim/chat_control_base:ChatControlBase.print_conversation_line()
-* (to be continued)
\ No newline at end of file
+* (to be continued)
+
+
+## Design of the end state
+
+### Functional requirements
+
+In the end state, it should be easy to experiment with various presentations, where it's possible to swap presentations for each type of message ('status', 'error', 'info', 'incoming', 'outgoing', ...) separately. This will allow better future development and adaptation to user expectations.
+
+### Technical requirements
+
+* Presentation of both messages from the server stream as well as (informational) messages originating from the client
+* Separation of management of content of the chat window from rendering of it
+* Separation of presentation and chat management
+* Efficient updating of chat content driven by the chat content management class
+* Presentation layer will be provided *all* required input to determine correct rendering; currently this amounts to:
+  * `delayed`
+  * `kind`
+  * `xhtml`
+  * `correct_id`
+  * `encrypted`
+  * `encryption_details`
+  * `text`
+  * `time`
+  * `contact`
+  * `displaymarking` (what's this about??)
+  * `xep0184` (would have been more conveniently named `message_delivery_confirmed`)
+  * `subject`
+  * `old_kind`
+  * `other_tags_for_name` -- likely needs to move to the view/renderer
+  * `other_tags_for_time` -- likely needs to move to the view/renderer
+  * `other_tags_for_text` -- likely needs to move to the view/renderer
+  * `simple`
+  * `graphics`
+  * `msg_log_id`
+  * `msg_stanza_id`
+  * `count_as_new`
+  * `restored_message`
+
+What do all these mean???
+
+### Required roles/classes
+
+* GroupChatControl/PrivateChatControl/ChatControl  
+  These classes determine which messages are applicable to the current chat; they do nothing more than add the message to the ConversationContentModel.
+* ConversationContentModel  
+  This class is responsible of maintaining the exact content to be shown in the correct order. This means that any messages being corrected, get updated in this content representation. It's the responsibility of this model  indicate to the view it has been updated/appended, including which messages were updated, by stanza_id. It is the responsibility of this class to store and update history of the channel (as this class is the place where it all gets together).
+* ConversationTextview (current presentation)  
+  This class is responsible for showing any content available in the model and updating the display when the content model gets updated. It's up to the view to determine how any given message is to be rendered, meaning that the content model should be able to provide all data that might influence this (see the listed fields above for the current situation). The view maintains a mapping between stanza_ids and regions in the widget to ensure efficient updates. Note that this class and the next don't differ in their responsibilities.
+* ConversationListBoxview (desired presentation)
+  * ConversationStatusListBoxrow
+  * ConversationMessageListBoxrow
+
+Note that this design will allow - when the ContentModel will be connected to a source storing history - browsing back in history, if the content model gets extended to read messages from history upon request.
\ No newline at end of file