Final Report of Project « The Eraser » Olivier Girardot Aude Quintana

2008/2009

Table of contents I.Context of the Project.................................................................................................................... 3 I.1The HP contest........................................................................................................................3 I.2The last project's results .........................................................................................................3 I.3The technical environnement (Tablet PC).............................................................................. 4 I.4Subject and Specifications...................................................................................................... 5 The Goals............................................................................................................................... 5 Product of the projects............................................................................................................5 Product features :....................................................................................................................5 Quality assurance and criteria to validate the work............................................................... 6 II.Project Management.....................................................................................................................7 II.1The project itself :..................................................................................................................7 II.2Interface with the rest of the world......................................................................................11 III.Specifications and goals :......................................................................................................... 14 III.1Expected features :............................................................................................................. 14 III.2Adding components to OOo User interfaces..................................................................... 14 III.3Coding and language good practices ................................................................................ 14 III.4Futur and community......................................................................................................... 15 IV.Coding and issues faced............................................................................................................ 18 IV.1Setting up the developpment environment for OOo.......................................................... 18 IV.2Debugging, Xcode and Gdb............................................................................................... 18 IV.3How does it really works ?................................................................................................. 20 IV.4Full erasing of the screen....................................................................................................21 IV.5Eraser handling...................................................................................................................22 IV.6The graphical user interface modification .........................................................................23 V.Futur of the source code and the project as a whole...................................................................26 V.1Compatibility with the second project................................................................................. 26 V.2Maintainability.....................................................................................................................26 V.3Performances and enhancements......................................................................................... 26 VI.Conclusion................................................................................................................................ 28

I. I.1

Context of the Project The HP contest

The Tablets PC we decided to improve OpenOffice for were won by the Ecole Centrale de Nantes at a contest by Hp on the theme Technology for Teaching. The Operating System of the Tablets PC is Ms Windows Vista but we intented to set up an environnement mainly composed of free softwares under Linux usable by both teachers and students, those being the main end-users. The goal was to be independent from Windows Vista when using the tablet pc. The last project we realised was all about setting up this environnement in a proper way under Linux ensuring at the same time to keep a lot of the functionnalities the end-users could have under Windows Vista for them to be in a friendly and familiar environnement. Therefore we pointed out that there two main points that we should improve under Linux for the tablet pc, improve the way annotations were dealt with under OpenOffice Impress and a better support from the Operating System (Linux/Ubuntu) for OCR ( Optical Caracter Recognizer ) possibilities. We finally chose to improve the first point which leaded us to the following results.

I.2

The last project's results

The last project ended up well and in an encouraging way for the rest because our goals were reached, as we got closer from the OpenOffice.org community : Frédéric Gelot and Olivier Girardot became Domain Developpers. Moreover, using the project as a opportunity the Ecole Centrale de Nantes joint the Project of OpenOffice.

Education

To sum up this last project : – We added functionnalities to OpenOffice.org : We added the possibility to change size and colors of the annotations one can draw on a slide of a diaporama, during the diaporama. – We learned a lot : We harnessed a part of the code of OpenOffice.org Impres and we learned a lot about C++ as we were mainly Java developper at first. We learned a lot with Thorsten Behrens about the standards of coding in OpenOffice and with C++ as a whole. And we learned a lot communicating in english with the community of OpenOffice using IRC and the channel #education.openoffice.org on irc.freenode.net. All these results were all the more reasons for us to keep on working on OpenOffice.org and with it we knew what we could achieve and what we would have to face to reach our goals.

I.3

The technical environnement (Tablet PC)

Our technical environnement was mainly composed of Tablets PC as it was a project to improve Tablets PC under Linux at first. Moreover our programming efforts had to be done using C++ language and had to be compatible with all plateforms that OpenOffice could be used one. And OpenOffice.org is a very complex software using its own system of plugin, with a language to be able to interact with the heart of the software (C++ Based), using other languages like Java/Python/... using this precise way :

Java, C++, Python...

UNO C+ +

Noyau Interface Universelle Extensions

L'UNO, stands for Universal Network Object, and allows a developperto create extensions that will be understood correctly by the kernel of OpenOffice.org. Using files its symbolized, in the heart of OpenOffice, by a lot of .idl files : Interface Definition Language , and the associated compiler Idlc. These files are used as descriptor files for the programs that needs to create interfaces using this way :

But our project was mainly about modifying the heart of OpenOffice and we didn't really have to directly interact with UNO but we had to abide by some coding standards in order for our code to be compatible with UNO.

I.4

Subject and Specifications

The Goals Our project consist in improving the way Tablets PC are dealt with by OpenOffice. It's deeply linked with the other project dealing with the way annotations are saved temporarily and permanently in OpenOffice Impress. This team will be working closely with the other team and with the development teams of OpenOffice.org. The following features appeared to be needed for an day to day basis utilisation under a free environment : • •

Erasing functionnality in the different modules of OpenOffice, Automatic recognition of the position of the screen to rotate the screen

Product of the projects 1. 2. 3. 4.

Report about this project and the realised tests Patch of OpenOffice.org allowing these features Report on how to set up the environment for rotating the screen automatically Blog articles on the progress of the project each two week

Product features : 1. Eraser handling module : •

•

Possibility to erase polygons using two different modes : ◦

as a whole;

◦

partially, by splitting the interesected polygon;

specifying different sizes using a contextual menu.

2. Automatically rotate the screen

•

Study if this feature is feasible

Quality assurance and criteria to validate the work The source code should be documented, compilable and tested. We should demonstrate how it works The amount of work should be at least equal to 60 hours for each members of the group.

II.

Project Management

II.1

The project itself : Initial goals

Our goals was to create a new module to handle the eraser just like we created to annotation module during the first project and to finalize the configurations in order to be able to detect the rotation of the screen automatically. We separated our work like that in order to split the work : creation and design the new feature create the user interface to access this feature from Impress detection and handling of the rotation of the screen To detect the rotation of the screen, it was clear that we had to look after a driver and conigure the computer for the screen to be correctly recognized and handled.

Evolution of the project and goals Firstly the eraser module was the part we took the most care of because we even talked about it the most during our meetings with M. Magnin, and he agreed that it clearly was the heart of our project. Why we gave up the configuration part of the screen ? During our specification process we discovered no clue about an OpenSource driver usable in this context compatible with this TabletPC. Therefor in order to realize this part we had to code a driver. It was clearly impossible considering our skills and the time we had. Therefor in the next parts of this report we will talk of the project as : Te Eraser. Results of the implementation of the eraser module : – Adding total erasing features; – Adding partial erasing features;

– Ensuring the compatibility as much as possible with the project « The Saving Machine »; – Document for the project Specification ; Gantt diagram of the project Week 1 :

Week 3 :

The first weeks went quite well and with no particulier issue. Week 5 :

Week 7 :

Week 9 :

It's the the 2 weeks before the end of the project and M. Magnin added the fusion of the two patchs created by the two projects. So there is some delays concerning the parts where we had to code. The project itself between us We kept the same work environement than the last time using both Subversion and Trac. The SVN Repository allowed us to share data and work documents and the Trac plateform was mainly used for project management to keep a trace of what we did.

To end up this part, we will give a estimation of the time spent by both of us on this project : Aude Quintana : 50 hours 5 hours to write the specifications 10 hours of project management (including the reports) 15 hours of coding 5 hours of brainstorming for the specifications 10 hours to prepare the final presentation (final report and presentation) 5 hours of meeting Olivier Girardot : 90 hours 2 hours to write the specifications 10 hours of management (including the blog articles and video) 35 hours of coding 3 hours of brainstorming for the specifications 25 hours for the merge of both group's patch 10 hours to prepare the final presentation (final report and presentation) 5 hours of meeting The project itself with the « client » : M. Magnin Our meetings were every two weeks in order for him to be aware of our progress and change our goals if it was necessary. During these meetings it was decided that we would give up the second part of the project about the rotation of the screen in order to be fully focus on the first part. It was clearly pointed out that we had to have the best communication as possible with the OOo Community. This point is developed in the following part.

II.2

Interface with the rest of the world

As planned we put in place several “communication plateforms” in order to interact with the community : – the blog “Tablets PC de Centrale Nantes” – and the RMLL (Rencontres Mondiales des Logiciels Libres) The Blog “Tablets PC de Centrale Nantes” In parallel of the progress reports for the school, we were asked to write blog reports every two weeks, in order to show our progress in the project to the community. It was also to confirm our presence and to encourage our users to send us their comments about the project group part already realised, as well as ideas for the requirements in this followig about the eraser. Here is an example of an article posted:

In addition to enhance our production, we have created a video showing the new features offered by our achievement for OpenOffice.org.

As the impact on the distribution and interactivity of the project is obviously stronger through the video, Mr. Magnin was very satisfied with this achievement. Les RMLL (Rencontres Mondiale du Logiciel Libre)

We will underline in this part the role of Mr. Magnin. In fact he went to San Diego to attend a forum on the HP Tablet PC and provide an overview of the use of Tablet PC at Centrale Nantes and more specifically of our work for several months. He could see that our work was followed with the enthusiasm. The results of the involvement of students in the HP Education project have international consequences and justify the donation of the Tablet PC to the school which is good news for future projects.

III. Specifications and goals : III.1 Expected features : This project has the goal to add earsing features to OpenOffice.org, it should allow to erase the traced polygons in OOo Impress in slideshow mode for any presentation. The goals being to operate these two types of changes : – Full erasing of the current slide removing all annotations but keeping its content – The possibility to enter an erasing mode where one can erase polygons by clicking and dragging the mouse on annotations to erase them one step at a time – The erasing pointer size should be changeable specifying a wide (but sufficient) variety of choices from thin to thick.

III.2 Adding components to OOo User interfaces This project couldn't be complete without adding the proper buttons and links in order to access this features by Ooo's interfaces. It was therefor decided during the specification process to foresee how the buttons and links should appear into Ooo Impress's interface, we chose to add those into the contextual menu of OOo Impress during the slideshow.

This organization allows the user to choose the size of eraser he wants and enter directly the erasing mode, clicking once again on a size de-activating this erasing mode. It is also possible just by clicking on « Erase All Ink » to erase all annotations on this slide. These specifications implied to harness Ooo's way of handling user interface. Fortunatly out last experience with the group project made us anticipate this problem by studying thoroughly the existing code.

III.3 Coding and language good practices OpenOffice.org is a huge Open Source project, it's one of the biggest and the most reliable in the world, it's also a project where there's a growing need for developpers and everyday a lot of people are working on it. Sun Microsystems's developper are still realising a lot of useful tasks, like internationalization, but but also world contributors that contributes to this software to improve it without being paid just

like us. It would be impossible for all these people to work altogether without any rules being specified to keep the software in good shape and reliable. So we had to abide by these rules just like everyone else for our contribution to be successfully integrated. Firstly OpenOffice.org's core is programmed using C++, it has its own compilation tools and its own structure. It is necessary to harness C++ and its ways to respect the standards of the language, for example : the separation of header files and coding files. But these standards are not the only thing to take into account, several good practices must be added within this project. The separation of headers files and implementation files is a very good example. In theory, we must respect this law, but within OpenOffice and more generally within projects, this norm is to be almost completely given up. To sum up the separation between a .hxx file and a .cxx of the class only if we must be able to include this file in another program using :

myclass, is necessary if and

#include « myclass.hxx » Therefor even if one would tend to do that for every class, it would be very heavy for the compiler , because it would be forced to parse every header file that we didn't really need. So there is most of the time into OpenOffice many classes defined within .cxx files. This little example is to understand the sum of good practices to take into account for a specified language to join an OpenSource project and contribute to it so that the code may be usable for the community. Communication issues weren't evocated, like the facto to comment one's code in english or to interact in english with the community, considering we're french student. All that we could say is that it wouldn't have been able to realize this project without all of us understanding more or less technical english and asking advices.

III.4 Futur and community The fact to contribute to an OpenSource project so big, made us put all the chances on our side so that our changes are incorporated into a future version of OpenOffice. org. We are thus passed first by the bugs management system of OpenOffice , where it has not been necessary to open tickets, as many applications for improving the management of annotations in OpenOffice Impress had been made already. About our project, the bug was openned in 2006, and is available at: http://www.openoffice.org/issues/show_bug.cgi?id=62972.

Then once the bug and the demand confirmed, we began the process of specification of OpenOffice, in order to enable the management of fine specifications to implement the best options. This process is very cumbersome and provides for the most extreme cases a competitive study and a market study of what is done in the field, as well as precise schematics of the changes that must be added to OOo's user interface. We have completed this process, for our feature, and sent to the specification teams our document for validation.

Moreover, the branch principle used in Subversion, allowing to separate developpments from the mainstream project, is present in OpenOffice subversion's repository under the name CWS ( Child WorkSpace). Therefor we created a CWS called « eraser01 » with the last version of our modifications, this cws being linked to our specifications and to the bug issue it's resolving. All these steps allowed us to improve our goals and our project as a whole while giving us a visibility within the community. Eric Bachard and Thorsten Behrens helped us a lot during every steps of the process to get the best out of this experience.

IV. Coding and issues faced This part is a little bit more technical and we'll get into the details of the codings and also into the details of the choices that were made and the problems faced, both comprehension problems and bugs that were solved.

IV.1 Setting up the developpment environment for OOo If there was only one thing to learn from this experience, it's that in order to realize good work on a big project like this one, you need to be particuliarly aware of what you need to set up as what will be your plateform, and never under-estimate the stakes around optimizing your daily tasks, like what we will see in the following chapter. Firstly this project was, as a basis, multiplateform, a lot of the preliminary work was made LinuxUbuntu, then the work was made under MacOs because we changed the computer. We therefor needed to set up the developpment environment under both computers, and allow us to realize series of tests once every stable modification was made. It's that last part that was the most complicated, because in fact under Linux, it was easy to generate executable files and test directly the changings copying the library needed once the preliminary full compilated version was done. Under MacOs, the first compilation of OpenOffice makes a .dmg file, the file format used by MacOs for installation files. Without getting in too deep into the way MacOs packages its applications once a .dmg file is mounted, we can then copy the « .app » which is the program itself that will be used into the « Applications » directory of the system. At first we tried to improve the compilation of the .dmg as a whole, but it was still lasting more than 23 minutes to get it all. It's only discovering using the command line that a .app file isn't actually a file but a directory containing the files composing the application, that we could once again find a way to copy the library modified to propagate the modification in about 5.562 seconds, a thing that would never been imaginable compiling the dmg as a whole. Being by nature and teachings more of a Java developper, our first thought was to try to use Eclipse as our one and only IDE for what we had to do. But tests showed us that OpenOffice's project being more than 8.35 Go wide, it wouldn't have been possible to do anything good taking all the source code into account, therefor Eclipse didn't give us any advantages rather than Gedit or Xcode, that were our main tools.

IV.2 Debugging, Xcode and Gdb During the debug phases we had some problem that are noteworthy. We learned at this occasion how to use gdb and face several problems that appeared under MacOs :

This screenshot is pointing out the problem : First we execute the debugger on our program, OpenOffice.org.app, the debugger reads the file and we run it after it's been validated as a properly runnable file, and it works until the program stops... This un-planned stopping was a real problem when we needed to debug an OpenOffice version that runned perfectly when launched normally. However we reached our goal using the following tutorial using Xcode to debug OpenOffice.org : http://wiki.services.openoffice.org/wiki/MacOSX_Debug_OpenOffice.org_using_XCode The principle is this one, Gdb is allowed to run a program itself in order to debug it, or attach to an existing process. So we thought that it was a proper solution to attach gdb to the existing process of OOo launched, but it failed :

Therefor we tested the tutorial attaching soffice process to gdb with Xcode, which was an unplanned success and allowed us to debug properly when we needed :

IV.3 How does it really works ? The following simplified schematics, which doesn't hierarchical data allows everyone to understand how from a user interaction, the differents modules interact to change (in this case) the width of the pointer :

Then when the slideshow mode is entered the class SlideImpl create the slide itself and instanciate, if the mode « Pointer as a Pen » is activated, UserPaintOverlay which instanciate itself PaintOverlayHandler, whose mission is to listen for mouse events on the slide.

IV.4 Full erasing of the screen The full erasing of the screen wasn't exactly an easy feature to implement and thing because most of the time erasing is reverting the color of a pixel to its original state. But for simple pattern it's only revert it to a simple color like white or blue... And actually it's impossible right now to “erase” a polygon because once they're drawn on the screen, it's once and for all, they are not even drawn on a separate layer that we could drop. In fact a slide is a complex image drawn once and for all on the screen as a bitmap, this bitmap is stored in an instance of SlideImpl, and just like that polygons are drawn on the screen without modifying the stored bitmap on the slide. After analysing the existing source code we decided that the better way to handle the full erasing of the screen was to reload the bitmap containing the data of the slide bitmap. This treatment and all our work is to be done into the class PaintOverlayHandler. (c.f. schematics) The problem was to get the bitmap the less destructive way possible, and to do that we needed to get the instance of SlideImpl, and understanding the last shematics we understand that with the mecanism of instanciation PaintOverlayHandler doesn't possess any direct access to the instance of SlideImpl. One of the first solution found was to add a pointer to the instance into each constructor, but this changing was an heavy on and a more optimized way was found. The following schema is here to help understand the hierarchical ways that allowed this solution to work :

The solution chosen is one of the best because it comes from the static call of the create function of UserPaintOverlay inside of SlideImpl, and this call take as a parameter a CursorManager. But this object is in fact the instance of SlideImpl, just where we want it to be but casted as a CursorManager , however this cast was quite problematic in fact. To sum up the goal of having this instance of SlideImpl, is to call the method : getCurrentSlideBitmap( const UnoViewSharedPtr& rView )

that can give us, using the current view we need to redraw, the corresponding bitmap of the slide . But in order to use it properly we needed to re-cast this CursorManager as a SlideImpl object, and SlideImpl didn't have any .hxx... Fortunately we discovered that the parent class Slide, did have both a header file and the method that we were looking for defined (as purely virtual), all that was left to do was realize the cast itself from CursorManager to Slide. But, as Java developpers, we only knew one type of cast, the use of parenthesis containing the type we want the object to be casted to. And it's not the only one existing in C++, a fact that we ignored. So when we used this type of cast, with no error detected, and that the program did crash without any explanation, Thorsten Behrens and Eric Bachard, helped us a lot, teaching us these facts. – The usual cast « ( …) » is almost deprecated ; – There is a dynamic cast to replace : « dynamic_cast< …. >( variable ) » ; – Or the reinterpreted cast : « reinterpreted_cast< …. >( variable ) » ; This step lasted a bit longer than we expected, but we managed to define efficiently, what was the best solution to put in place to erase all the screen preserving the slide itself, and it helped a lot for the second part.

IV.5 Eraser handling The principle used in this part was defined as pretty simple, but it's clearly not the most efficient one, we will explain what should have been the best solution and what we did. We already explained that the slide itself is stored as an image, as a bitmap, and that the erasing is in fact nothing more than returning a pixel to its original state. However an eraser only restores a small part of the screen, the idea was therefor to redraw only a part of the screen defined by the pointer, using clipping features to improve the drawing. With this idea we had all that we needed to erase the screen, but here's the result of our first test :

To be a little bit more explicit, in the upper left corner, it was possible to erase the entire slide... This bug wasn't clearly the easier to find, and it was necessary to draw annotations on almost all the screen just to detect and understand what was really happenning. But it implies a problem of coordinates with a missing transformation that would allow every coordinates to fit into the right place on the slide. Then once again Thorsten Behrens and Eric Bachard helped us to determine the right transformation matrix to apply on the pointer coordinates, and the modification worked without any noticeable problems of performance.

IV.6 The graphical user interface modification The following graphic is to explain a little more what the SlideshowImpl “uses” ( “utilise”) to do its work and create usable graphical components :

The class SlideshowImpl is designed to deal with the interaction of the user, to be able to respond

to clicks on the contextual menu, or just show it. The way used to make it work is simple, there's a switch taking integer values each one representing a menu item. But before that, we need to take into account all the files that this class uses in order to create the new buttons and define these integer values. Then and only then we can define what behaviour these buttons may have (change width, color etc...). We're going to present three types of files we used and their roles : – Slideshow.src : allows oneself using a modelisation language, the buttons you want to add in a hierarchical way and the variable names that will be used for them. This file is very useful because you don't have to touch any c++ source code to create your own interface or change it as you want, here is an example of usage :

–

Slideshow.hrc : allows oneself to associate the variable names to an integer value so that the variable may be usable into the switch part of Slideshow.cxx

– Finally localize.sdf to deal with all the internationalization of the application, because every button. This step is not exactly mandatory because it's a part of the process that is still done almost entirely by Sun Microsystems contributors. All the work about the UI properly was made very quickly with this system, but the real point was to deal the propagation of the modification from one part of the application to another this is where the concept of EventMultiplexer is at stake. It allows us to register who wants to be notified of changes concerning a precise variable, and be able to change it from any part of the application (Sd module) and notify another part (slideshow module).

V. V.1

Futur of the source code and the project as a whole Compatibility with the second project

The second project was more focused on saving features for the annotations, and this project is a bout handling the erasing of these annotations. So there was naturally at the beginning some conflictual interests between the two project, and our goal was also to work altogether in a common direction. But in fact, without getting into the subject too deep the work of Frédéric Gelot and Pierre-Jean Parot, stores in a vector everytime a polygon is drawn, this polygon to recreate the polygon on the slide once it is needed. Therefor we had to improve our code in order to allow the erasing even if the polygon is stored, there was then two cases we could imagine : During the full erasing, you just have to clear the vector that contained the polygons and redraw the screen. But during the partial erasing, it's slightly more difficult to take into account because the vector stores the polygons themselves but we are dealing with coordinates... One can easily imagine thatit's not that easy and fluid to try to find with a vector of polygons, those that are intersecting a precise set of coordinates and then treat it in order to erase only small parts of it... The problem was basically that in order for us to move on with our work and debug our projects we decided to code into two different CWS but it was almost impossible for us to create patchs and merge our works every time we needed. So we only did it at the end of our projects, where we add to merge manually more than 4000 lines of code into more than 150 000 lines of source code... The partial erasing problem is still unsolved nowadays, because there are still too much problems and the structure used for polygons isn't usable as it is, if we want to be able to realize it all with good performances.

V.2

Maintainability

The issue of maintainability has always been present in our minds considering the volume of source code in which our project had to take its place. But we took the best of the situation in order to create good and maintainable source code. Thorsten Behrens told us what he expected to face and what he considered was a good source code, within OOo. Furthermore we realized reguliar tests with Eric Bachard and Thorsten Behrens to be sure we were going into the right direction, and we never stopped documenting our source code. During the developpment time of the projects Frédéric Gelot and Olivier Girardot even became Domain Developpers, therefor they will always be able to answer any questions on these projects.

V.3

Performances and enhancements

It is clear that even by using the principle of clipping and redrawing only a small part of the it's not the most efficient way to deal with this problem.

slide,

The fact that we are used to using several graphical software like Inkscape, GIMP, made is think that it was useful to define several layers when you work on graphical problems. Then we would be able to define a specified layer for the polygons to be drawn, and another one for the slide itself. But our modifications had to be the less intrusive, so we didn't change hierarchical organization and

methods signatures in order to limit the problems that may appear aftewards. Also as it was impossible to know the full dependancy and the choices that were made in termes of hierarchy by the full-time contributors of Sun Microsystems.

VI. Conclusion This project was very stimulating and allowed us to harness a little bit more OpenOffice.org source code, to take contact with a dynamic community that helped us any time we needed and shared its experience with us and we shared our motivation with it. We learned a lot from this project both in terms of developpment and in terms of collaborative work and its possibilities. The interest that was stimulated by our work reached the RMLL (Rencontres Mondiales des Logiciels Libres), and the network of the Centrales grandes ecoles and other universities members of the contest Technology For Teaching – HP, and motivated us all the more showing us how the work we were doing was important. Therefor we would like thank M. Magnin and M. Moreau for their help and support. We will keep on working on these projects to make this work usable by other people and would like to thank Eric Bachard and Thorsten Behrens for their help that we needed greatly and that was always welcomed.