|
Code review application - technical documentation
The technical documentation for this apps consists of a description of the tree structure and other basic information; a sample script (given mainly to illustrate the tree structure); and a list of the network messages used to implement communication among clients. We have also listed, at the end, some suggestions for useful enhancements that we have not gotten around to.
Tree structure
The tree structure for this application is:
Slice CurrentFileName=... UserName=...
Frames
... Frame nodes for main window, signon window, and global comments window
Panel Id=sign_in_display
... sign-in display items. IP address igiven as Text attr. of nodes ip_1, ..., ip_4
Global Type=Panel
Panel
... four Button nodes ...
Pages
InkPanel ... (one InkPanel node per page)
Main Type=Panel Id=main_display
Panel Id=toolbar_panel
... Button nodes ...
Panel Id=file_tab_panel
... Button for each loaded file
Panel Id=file_text_boxes
InkPanel Filename=...
Contents Type=Label Text=...
Lines Type=Label Text="1\n2\n3\n..."
... one InkPanel per file ...
The following Python variables are defined for all scripts: Global (the node named Global), Main (the node named Main), Files (the node with id file_text_boxes), and Tabs (node with id file_tab_panel).
For example, the following function is invoked when the "close file" button is clicked. It finds the current file name in the root, finds the file node with that name, and removes the node, the tab for that file, and the CurrentFileName attribute (from the Root). It then calls a function defined in Init242.py called ResizeTabs, which moves tabs and resizes them if necessary. Finally, if the list of open files is not empty, it makes the first one the current one.
def CloseFile():
# First, remove current filename and node
currentfilename = Root["CurrentFileName"]
currentfilenode = Files.FindChildByAttribute("Filename", currentfilename)
Root.RemoveAttribute("CurrentFileName")
currentfilenode.Remove()
currentfiletab = Tabs.FindChildByAttribute("Filename", currentfilename)
currentfiletab.Remove()
ResizeTabs()
# Then choose another file, if any.
thefiles = Files.GetChildren()
if thefiles.Count == 0:
return
newfilename = thefiles[0]["Filename"]
SwitchToFile(newfilename)
return
The tree for each file is an InkPanel with subtrees Lines giving the line numbers (left side of the display) and Contents giving the actual text of that file. Separate portions of the tree give the main toolbar buttons and the file tabs - the buttons created each time a file is loaded.
Messages
The message format is, as usual, a tree named NetworkMessage with an attribute MsgType. Messages in this application may also have one of two "location" attributes, Filename or Global. Filename gives the full path name of a file in the sender's application; as noted in the user guide, all user's should have the identical information, so in particular should have a node containing this file. Global gives an integer which is the page number in the Global comments tree, indexed from 1. Messages also include a Sender attribute.
The message types in this application are:
AddStroke: Sent when any user enters a stroke; goes to all other users. Message includes Author and NodeNum. The latter is a number unique to this stroke node (within this session), which is used to delete the stroke. The child is the stroke node itself.
DeleteStroke: Sent when any user deletes a stroke; goes to all other users. Message includes Author and NodeNum. Note that NodeNum and Author are both needed to identify the stroke.
OpenFile: Sent when any user loads a file; goes to all other users. The child of the message is the InkPanel node containing the line numbers and contents of the file. Note that this node also contains its dimensions, which may be different on the receiving machine, so adjustments have to be made there.
AddGlobalCommentPage: Tells recipient to add page to the global comments pages. The page is added just after the current (visible) page. (This does not work correctly at present; the page should be added in such a way that the order of pages on all machines is the same; currently, the position of the new page depends upon the current page on the recipient's machine.)
SendState: This message is sent by a client to the server as soon as the client establishes a network connection. (Recall that the server must start before any client.) It is sent in StartTcpClientWithAddress.py, and passes the user's name (UserName attribute). The server responds by sending a complete current copy of the state.
InitWithState: Message sent by server to new client in response to the SendState message. It provides the entire state to the child. The children of this message are copies of the Files subtree, the Tabs subtree, and the Page subtree of Global.
Enhancements
Here are some enhancements we would like to see (and are hoping to implement):
Printing. Currently, we print every file, with its annotations. However, it is likely that most parts of most files will have no annotations, and printing these parts will be wasteful. An alternative is to print only sections that have ink; this will require some work.
Participant identification. It would be useful if inkstrokes were identified by user, perhaps using colors. Another possibility is to have the author's name printed when the user hovers on an ink stroke, but we cannot implement that at present because we do not implement a hover event. (In any case, this would probably not work well, because it would identify only one stroke at a time.) Yet another possibility is to let users use whatever color they want, but have a button that locally re-colors strokes by user. (Note that each stroke node is identified by author internally; the issue here is how to communicate that information visually.)