Image Markup Tool blog

The writing of the search/replace code goes on and on, ever more complicated, to the point where I wonder if I should have taken a different approach. Still, I can see the light now.

Today's progress:

• Completed the FindNext method of TIMTDocument, which is the heart of the single-shot Find and Replace functions. It's very complicated now, with several embedded functions, much of it in the form of Case statements which branch based on the nature of the container we're currently searching, to find the next container that should be searched.
• Added the following methods to the ufrmMain (main form) GUI object:
  • StashDirtyData. This was complicated, because it threw up a new problem. Normally, when the header or the category data is being edited, that's happening in a modal form. However, the search functionality needs to be able to throw up those forms with selected text, and keep them onscreen while you search again, so they have to be showable as non-modal; and that means they can all have dirty data in them. Working around this involved a lot of changes to the way the header and category editing happens, in a number of different objects.
  • Find, FindAll, Replace, ReplaceAll, and GoToSearchHit. These all implement the function signatures the ufrmReplaceDialog needs to call. Only Find has been implemented so far, and that has bugs (see below).
  • aFindExecute, and action to set up the search dialog and show it.
  • GetCursorLocation, which records the position of the cursor (what container it's in, and the details of any selection) so that this can be used as the starting point for the search.
  • ShowSelection, which should show and select any hit that's found. Again, this is complicated Case statement stuff, depending on where the hit is found.
• Began testing, and discovered two bugs: First of all, the searching fails (a known hit is not found), and secondly, the check to make sure that you don't loop endlessly around the document is also failing, so the search is endless. These shouldn't be too hard to figure out, though.

This has been remarkably complicated, but it's because the document structure is complicated, and it's mapped across lots of different GUI components and forms. I don't seem to have broken any existing functionality so far, but the possibility of having three different components of the document open for editing at the same time, potentially all with dirty data, is going to take some care and attention. We'll have to make sure that the StashDirtyData function is called when saving files, or before closing a file.

Long embedded case function for returning the next container in the document to search is now finished. The actual search function body can now be written, checking document elements one by one till it finds a match.

I'm now about half way through implementing the search/replace. I found some things that needed improving in the code already written. For instance, I was failing to check for well-formedness when writing nodes back to the document which had changed due to string replacements. Then I realized I wasn't tracking successful replacement instances (as opposed to find hits); where replacement would cause a broken doc, the replacements are not done, so find hits are not equal to replacements. That's all fixed now.

Finally, I've mapped out the function for doing a Find Next, which is complicated because it can be upwards or downwards, and has to iterate through the many different document components appropriately. I've not yet added the MatchCase and WholeWordOnly booleans to the function signature -- mustn't forget that. I should be able to call SearchContainer to do the actual search, so that there's the potential for rudimentary regexp functionality in the future.

Another few hours should get me to the working-GUI point, where I can really start hammering it for bugs. It's way more complicated than you would think, especially if you're going to protect the user from destroying their document structure (which I am).

Updated the screenshot and all associated references in the documentation to explain the id editing feature. This also acted as a check to ensure that none of my changes have affected the app's ability to import/export docbook files, or the help file compilation system that exports the docbook to HTML.

Previously, the @xml:id attributes of <zone> elements (and the corresponding @facs attributes of annotation <div>s) were assigned automatically by the program. This is less than ideal, because users (especially sophisticated users) are likely to want to use memorable strings for these attributes, so that they can more easily link to or refer to them from elsewhere in the document, or from other documents. Remedying this deficiency has been on the roadmap for a long time.

I've implemented what I think is the simplest and most reliable approach to editing the ids. First, I had to put in place auto-generation of valid ids when a new annotation is created, so that the id is a property of the annotation itself (rather than just created and used during i/o processes, as before). Next, I added getter and setter routines at the level of TIMTAnnList and TIMTAnnotation, which check for validity and uniqueness. Then I updated the i/o code to ensure that these are being saved and loaded correctly. Finally, I added a simple and unobtrusive GUI method for setting the ids, in the form of a little button on the right of the annotation title. This will not cause much confusion for regular users, and won't change any other functionality, but it's easily accessible when needed.

Initial testing suggests everything is working OK. Now I need to update the screenshots in the documentation.

Implemented a the ReplaceAll bits of FindAll, and tested them. That seems to be working fine. Next is individual find/replace operations.

Progress today:

• Added the SearchContainer functionality to the TimtSearchList object.
• Gave TIMTDocument a TimtSearchList object so it can search itself, and added a FindAll function that populates the search list.
• Did GUI testing and debugging to confirm that the FindAll functionality works. A list of hits, with detailed info about them, is stored correctly.
• Began retro-fitting both these functions with the ability to optionally replace the hits as well. This is slightly complicated because of the effect of replacement on the offsets of hits in the same neighbourhood, combined with the option to search both downwards and upwards. I haven't finished this yet. Also outstanding is the mechanism for ensuring items changed by replacement, which may be currently visible in the GUI edit boxes, get updated.

Once this is done, we'll have handled FindAll and ReplaceAll. The next question is what to do about FindNext. We'll probably have to adapt code from Markin to iterate through the containers in the document, searching each one in turn.

I regularly test IMT on Wine under Ubuntu to see whether the bugs with dialog boxes have been fixed. Testing with the latest version at home, I found that the IMT worked fine using the latest Wine version (0.9.55), set to Windows ME emulation. This morning I tested this thoroughly and confirmed it does indeed work; then we tried running it on OSX under DarWine (also using Wine 0.9.55). The latter failed, unfortunately, but not with all dialog boxes (as used to be the case). The only problem was the Open Picture dialog box, which renders a preview; this seemed to send DarWine into a tailspin.

All this is very hopeful, so I've updated the Website to include detailed instructions for installing Wine/DarWine and running the application under it.

While the blog was down yesterday, I began working on adding find/replace functionality to the application. The Find/Replace dialog box is one I've already created for my Markin program, and which I'll open-source so it can be used in IMT. The key issue is figuring out how to find hits, store info about them, and jump to them. We have to create a special unit to handle this functionality, for clarity/separation, and it should include:

1. An enumerated type for containers: contTypes = [ctHeader, ctAnnTitle, ctAnnText, ctCatId, ctCatDescription].
2. A class which can store our current position/a hit position -- maybe TimtSelection. The data is presumably this:
   • Current container type (header, annotation title, annotation text, category id, or category description))
   • Item index (0 for header, annotation number for anns, cat number for cats).
   • Offset of cursor.
   • Selection length. Obviously this will normally be the same as the length of the search text, but we will presumably also store the original cursor position and selection, and restore it after a search/replace operation; and in the long run, there may be regexp functionality.
   • SelText. This is the text itself, and may help with a sanity check if the document has changed since the text was found.
3. A list class for storing these objects (for when FindAll is used).
4. A method for searching text (taking into account the Down, WholeWord and MatchCase) from the cursor position, and reporting back the correct offset and length (taking into account the preceding text length, if going downwards).
5. A method for finding the next container to search, based on the current container (this can be modelled on my similar code from Markin).
6. A method for making visible a container in which a hit is found, selecting the hit, scrolling it into view, and setting the application and form focus appropriately. This method will have to accept a TimtSelection object, do a sanity check on the data, show the appropriate container, and select the text; if the selection turns out not to match the SelText, it might also show an error message, or try to do another Find to correct the problem.
7. Implementations of all the functions required by the TmdhReplaceDialog Setup routine. Most of these will be wrappers that just call methods detailed above.
8. GUI elements in the Main and AnnDlg forms -- presumably an action, and associated menu and toolbar items.

Spent time working out the details above, then started coding the unit; I've done about a third of it.

Paolo C. provided an updated Italian interface file over the weekend, so I've rebuilt the installer to include it. No version change.