omer bar-or · The Plan Askew · OpenOffice.org · GSoC 2007

First, some more progress. I have created two more patches and committed all of them to the cws for the address book integration: macaddressbook01. The two new patches are for better commenting and localization support (links are to the accompanying issues in OOo). Please note that I had a lot of help from Patrick Luby on the localization patch. (See our conversation in the issue.)

With localization and commenting done, there is only one more task that I have set myself: moving the address book integration to the Cocoa API. (Of course, there is still testing to be done, and there are probably more bugs to fix.) Since the Cocoa version will likely not replace the Carbon version, at least not for some time, I will probably create a new cws for it that will exist parallel to macaddressbook01. More on this idea as it develops.

Also, now that I have committed several patches, Eric Bachard suggested that I offer directions for testing them. Here they are:

• <h2>To test the address book integration itself:</h2>
  1. In OOo, go to "File"->"Wizards"->"Address Data Source..."
  2. Select "Mac OS X address book" and click "Next."
  3. If you have groups in your address book, choose one as your main table in OOo. (The top option is for your entire address book.) Click "Next."
  4. If you want, rename your address book, and click "Finish."
  5. View your data sources (either press F4, click on the Data Sources button on your toolbar, or click on "View"->"Data Sources"
  6. You might need to expand the data source: expand "Addresses" (unless you named it something different) and then expand "Tables." Click on the table you want to see (e.g., "Address Book" for all records).
  7. You should now see your Mac OS X Address Book in OOo!
• <h2>Test multiple groups of the same name:</h2>
  1. In the Mac OS X Address Book: create two groups and give them the same name (I use "family").
  2. Go into OOo and view the Address Book data source.
  3. One of the groups should be named normally and one should have a " (2)" at the end, e.g., "family" and "family (2)."
  4. If you like, try various things (filtering, sorting, &c.) to each of these tables. They should never conflict with each other.
• <h2>Mail Merge Wizard:</h2>
  1. Open up the address book data source in OOo and click on the Mail Merge button (or go to "Tools"->"Mail Merge Wizard").
  2. Click "Next."
  3. Click "Next" again.
  4. If you opened the mail merge wizard via "Tools," you'll need to click on "Select Address List," choose "Addresses" (or whatever you named your data source) and then the table of your choosing.
  5. Click on "Match Fields."
  6. Match each field, at least until there are no more "not yet matched" lines in the preview. Note that the fields are largely in order and all of them appear (unless your addess book contains no addresses in it) -- this is what the patch fixes.
  7. Click "Next" until the wizard forces you to save, print, or send (step 8).
  8. Save, print, or send, as you like.
  9. Click "Finish."
• <h2>Localization:</h2>
  1. If the language on your Mac is not already something other than English: go into your System Preferences, to "Internationalization" and drag a language other than English to the top of your list. Close the system preferences.
  2. Go into the OpenOffice.org application folder (i.e., don't open the application, but view its contents).
  3. Go into "Contents."
  4. Go into "Resources."
  5. Create two folders, "en.lproj" and an lproj file for your main language. Mine was Spanish, so I created "es.lproj," and for French I would have created "fr.lproj," &c.
  6. Open OOo and view the Mac OS X Address Book data source. The labels should now be in the language of your chosen locale.

If you have any trouble, please let me know! Otherwise, I will soon start on the move to Cocoa. P.S., for those curious, here is the Address Book at work in Spanish:

Progress lately has been moving in bursts. There are times during which I feel like there is not much for me to do at the moment, as I wait for people to look at my code and my patches before I apply them. So far, Patrick Luby (of NeoOffice) has supplied two patches for my code. Then, for one reason or another, a specific task becomes available (e.g., fixing mail merge, for which I got some helpful advice by Florian Heckl that let me start working on it), and I work on it until it is complete. Progress on the Address Book Integration over the past week has been:

1. Patches:
   • Premac/postmac fix (by Patrick Luby, posted to OOo issue 77591) - this patch includes "premac" and "postmac" headers around included Mac OS X headers to fix various conflicts between Mac OS X and OOo (I believe).
   • Null headers patch (originally by Patrick Luby, with a slight modification by me, posted to OOo issue 79512) - this patch creates three crash-preventing checks for NULL values.
   • multiple groups fix (by me, posted to OOo issue 79513) - this patch solves an issue in which groups with the same name in the Address Book don't show up in the OOo data source.
   • mail merge fix (by me, posted to OOo issue 79514) - this patch forces the fields that could appear in an OOo mail mege template to be present and be at the beginning of the OOo data source. Because it modifies the way that the OOo integration sorts fields in the address book, it also includes a much cleaner version of the sorting algorithm.
2. I also created a new version of the ABColumns program (originally presented here) to work with Cocoa instead of Carbon. The new version is called "ABCocoa." You might remember that this program provided the basis for the Mac OS X Address Book integration into OOo, and - although the integrated version is rather different at this point and has solved several bugs in ABColumns - a Cocoa version is still a significant step toward the Cocoa version of the integration into OOo. I decided to move ABColumns to Cocoa before the integration because I am waiting for a relatively stable version of the integration in Carbon before I start this process, but I still wanted to see if the move to Cocoa was possible and what sorts of issues would come up. ABCocoa should make that move, when it comes, a lot easier.

This work, if there are no problems with it, solves half of the issues presented in my last post, just leaving: Cocoa integration, commenting, and localization of labels. And, reading up on how localization of strings works within Mac OS X (specifically this article at MacTech), and testing things like genstrings, it appears that there is no way to specifically invoke Mac OS X's own localized labels directly (e.g., I cannot ask for the localized version of the constant string kABFirstNameProperty, at least not in Cocoa). It might be that there is some way to localize kABFirstNameProperty itself, but if there is, I cannot find it. It also may still be possible to use the Carbon function ABCopyLocalizedPropertyOrLabel, but I have not managed to use it successfully, and it is strictly for Carbon, so it couldn't be included in the Cocoa version. So, after a bit more testing, I might call the goal of localizing labels currently unachievable (for me), which would leave only two more goals (other than testing and debugging) : commenting and creating a Cocoa version. I'll let you know my progress!

File: abcocoa.tar

Open issues: 77591, 79512, 79513, and 75914

I have neglected this blog lately as I've worked through various small bugs and features of the address book code, but there are several interesting new developments (or, at least, interesting for me). Most importantly, earlier today I did a compiled the X11 version of OpenOffice.org for Mac OS X and discovered happily that my address book code not only compiles on it but also works just fine. Other updates: OpenOffice.org no longer crashes on close (in fact, this was a bug outside of my code and was fixed by Frank Schönheit); the address book can now fully handle non-Latin alphabets (thanks to Florian Heckl); all data types from the OS X address book are now stored as the correct data type in OOo (so, for example, timestamps are now stored as timestamps rather than strings); fields from the address book are now displayed in a more logical manner (first name, then middle name, then last name, ...) rather than alphabetically; sorting records now works; and, if you have multiple groups in your address book, they'll each show up as a table in OOo.

I have also (finally) got my work in a presentable form. It is in two files, a patch file and a tarball, the patch for changes to files that already exist in OOo code and the tarball for files that I created. Apply both of them at the root OOo directory. The affected modules are connectivity, dbaccess, extensions, and scp2. Finally, I have created a cws for the address book integration (named "macaddressbook01"), and I am about to request that someone add those modules to the cws and apply the patch and tarball to them.

That said, here is what I think remains for my Google Summer of Code project:

1. Look into optimizing the address book with mail-merge (to get OOo to automatically fill in at least some fields automatically). I've been looking into this a bit already, and I'm not sure how much I'll be able to do (and, I don't believe that other address books, at least KDE, do anything). One of the major issues I want to see if I can help is that OOo current requires the user to supply a column for "title" (e.g., "Mr."), and while the Mac OS X Address Book stores title information, it does not display it in the Mac OS X Address Book application, so many users will likely not have it filled in, which means that it will (currently) not show up in OOo (which I made only show columns that have some information in them). I'm still not sure what I'll do about this...
2. Inernationalization of labels - given that I am using English, the fact that all of the address book's labels are in English has not stood out to me, but I recently discovered that the Address Book Carbon API comes with a localization function that, if I am not mistaken, gives the labels in the user's selected locale. I am not sure if I want to use it yet, depending on exactly what it does, but it at least looks like a promising (and hopefully not too difficult) fix.
3. Handle groups of the same name - the Mac OS X Address Book lets you create groups of the same name (so, I can have two groups named "family"). OOo's address book integration is built on top of its databasing software base, such that requests for information are in the form of SQL queries, meaning that the name of the table really should be unique (so that "Select * From 'family'" makes sense). I've run into this problem before, with the freedom that Mac OS X Address Book users have in creating multiple identical fields (e.g., two home phone numbers). My solution then was to add a new a number at the end of all duplicates, so the first field would be "Phone: Home," while the second would be "Phone: Home (2)," the third "Phone: Home (3)," and so forth. I will likely do the same for groups.
4. Clean up column sorting - as noted earlier, the columns are in a better order, but I am not very happy with the way I did it, since it is a bit ugly. I'll try to think of a better way of handling this.
5. Comment the code better... at least the files that I created from scratch.
6. Finally, the last rather large project I have set for myself is moving the whole address book over to use the Cocoa API, since that is the direction that the OOo porting project is taking. Luckily, I'm not expecting this move to be especially difficult, since I think that all of the changes will be isolated to a few files. We'll see!

Of course, these changes are assuming that others looking at my code are not appalled and demand that I start over or restructure the whole thing. If that happens, they'll all have to go on the backburner, and hopefully I'll have time to look into them later. I guess we'll soon see!

Oh, and finally, a fun screen shot follows of the addressbook working in X11. You'll see that one of the entries is written in Hebrew :)

Files: macaddressbook01_integrate_ab.patch and macaddressbook01_macab_driver.tar

It has been rather a long while since my last post, and I apologize for the delay. I am often fool enough not to backup my work, and I had finally tempted fate one too many: my hard drive failed just as I turned my computer on to back up my work on the address book. Luckily, because of this blog, I only lost a couple of days of work, and while my Macbook was in for repair, I worked on my old Toshiba laptop (Ubuntu Linux/Windows XP dual-boot) to redo the work that I had lost.

Well, after some long days, and specifically a long day today (that resulted in one new line of code, I have an exciting new image for you:

There are several issues to fix with this version. Most obviously:

• Once the Address Book is opened, trying to close OpenOffice.org or hide data sources causes OOo to stop responding.
• Though it can handle UTF-8, only two-to-three characters of the Hebrew I tried to include in my address book showed up in OOo, and when I tried to copy-and-paste them into OOo Writer, they showed up as little squares.
• The driver, right now, considers everything a string, even though the Mac OS X Address Book and OOo can both accept multiple types, the ones that overlap being: string, timestamp, integer and real.
• Right now, all fields from the Mac OS X Address Book appear, in alphabetical order, and without nice labels (e.g., "Phone: _$!<Home>!$_" should probably be "Phone: Home").

These are the main things that I want to change over the rest of the summer, and if I have time, I am also toying with the idea of syncing the Mac OS X Address Book and OOo driver so that changes in one appear in the other (which would allow me to make the OOo fields editable). The framework for doing so is, as far as I can tell, already built into OOo, so I just have to understand it and modify my own code.

Anyway, once I figure out a couple of these (at least the first, so that OOo doesn't stop responding based on my code), I will probably start looking into integrating the code with aquavcl01 (the child workspace for the Aqua port of OpenOffice.org. I am very excited!

I have two major updates for you today. The first is a rather modified version of my test Mac OS X Address Book program. It is called ABColumns because it prints out information about all people in tab-delimited columns. Two notes: first, although this version is specifically designed for people, an earlier version of the program could also easily handle groups, until it became apparent that a "group" in the Mac OS X Address Book is really just a holder of people (which makes sense, given the name) and has all but no other properties to it. So, although it would be pretty nifty to be able to choose a particular group as your data source or to switch to a particular group in OpenOffice.org, it isn't very high priority. Second: this version, in addition to printing columns, can also handle UTF8, rather than simple ASCII. Although I don't know of a way to write UTF8 to a file so that it can be imported into OpenOffice.org (or Excel, or any other program, for that matter), this version of the program, because it is tab-delimited, can be imported into either Excel or OpenOffice.org. I've tested Excel, but have not yet test OpenOffice.org, in order to move to the second, more exciting update.

The second update is that I have begun the process of actually integrating the Mac OS X Address Book into OpenOffice.org. Based on the suggestions of some people at the dev@dba mailing list, I am basing it heavily on the structure of the KDE Address Book code. And, I am including four files from the ABColumns program (everything starting with MacabRecord), though I changed them to handle OUStrings instead of STL strings. Over the past few days, I managed to get the code to compile and now have the following two screenshots. The second, though an error, is exciting because it is an error that comes from my code, which means that my code is being run:

Tomorrow, I will be traveling to Oregon, where I will (finally) once more have a decent Internet connection and be able to lurk on IRC again (my apologies for having disappeared recently), and that's where I'll be for most of the remainder of the summer.

File: abcolumns.tar

As an update to this post on working with the Mac OS X Address Book, I now have another deliverable: a program that prints all of the properties available on the address book. It's still only printing ASCII, and it's not in the correct format to be imported into OOo as a text file, but these issues are hopefully not hard to fix, and since they don't actually involve the Mac OS X Address Book API, I'm not sure that I'll actually take those final steps. I'm also not yet handling groups (the Mac OS X Address Book is split into two databases: groups and people), which is a more important lack and one that I will likely spend some time exploring soon. Anyway, the tarball for the program is available here. A brief description follows.

Basically: the the most important parts of the program are two method, one called printInformationForRecord and the other called getStringRepresentationOfPropertyValue. The former (by using the latter) can print any property in the address book (at least any one that I've been able to create so far). It doesn't assume that it is working with people, though I haven't tested it with groups yet. The latter can turn any type of value into a string (with the exception of "data" values, which are basically byte arrays and thus could be storing any kind of data), where the types are any of the ones listed in Apple's list of possible types. Although these methods only print a property to STDOUT, they are general enough that only a few manipulations would be enough to get them to do more complex things. This might even become the skeleton for handling the Mac OS X Address Book in OOo, though the complexity of OOo code will likely prevent that.

P.S. Thanks to Florian Heckl for correcting errors in the original program that helped me make this new one!

File: abpeople.tar

So, after all of my digging, I've finally managed to get a few meager results out of the Mozilla Address Book (or, more specifically, out of Mozilla's Thunderbird Address Book) inside of OpenOffice.org. The process described in my previous post on the subject let me to change the mozab lines in the "pre" files (see that post for details) and remove the "!defined(MACOSX) &&" in each block. Unfortunately, this solution only led me slightly forward: selecting Thunderbird or Mozilla gave me the error that "No Thunderbird Addressbook Directories Exist" -- see it here. After some more digging, I discovered that OOo was looking for the wrong profile for Thunderbird (looking for a directory called either ".mozilla" or ".thunderbird" in "~/Library/Application Support/" while the correct folder is called "Thunderbird" and is in "~/Library/" -- with this fix and another few tests, I finally have something worthwhile to show you. Here you go! A (somewhat) successful integration of the Thunderbird Address Book into OOo:

The original Thunderbird Address Book:

The Steps to add it to OpenOffice.org:

And, the result (after view->data sources) :

There are still quite a few bugs to figure out. (OpenOffice.org has been freezing a lot more lately, and I'm not sure if it's my new code or not... And, I still get the "No Thunderbird Addressbook Directories Exist" error when I open OOo outside of the debugger...) I'll investigate these more in the future and hopefully soon get started working on the OS X Address Book integration itself. But, this is definitely a happy step in the right direction!

Another development from over the past few days is my first application that interacts with the Mac OS X Address Book. It is available here. Basically, all it does is tell you how many people are in your Mac OS X address book and lists their names. It currently can only handle ASCII values (just so that it can be easily printed to the terminal), and it's an entirely terminal-based application, but it is a first step for interacting with the Address Book. And, perhaps more importantly, it is a first step using the Address Book Carbon API (Carbon is what OOo uses) rather than the Cocoa API. Meaning: it should be possible to integrate the Address Book using Carbon and C (both supported by OOo) rather than Cocoa and Objective-C (which are not). Enjoy!

File: abnames.tar