Drawing directly in the document window

Question

Can anybody provide sample code showing the basics of drawing directly in the document window? I'm thinking of something along the lines of the measure tool (pardon the pun).
It looks like I'm supposed to use either the Annotator Suite or the Document View Suite to "invalidate" a rectangle in the document, followed by doing the actual drawing with the ADMDrawer Suite. But the documentation in this area is pretty sparse (for example GetDocumentViewInvalidRect and SetDocumentViewInvalidRect refer to a "fudged" invalid rect without explaining what that is) and I don't see anything in the Sample Code folder that explains this feature.
Are the little text annotations ("path" "anchor") that pop up when using Smart Guides done using this method?
Thanks,
John

Answer 1

(Sound of crickets chirping...)
Boy, this forum is awfully dead in comparison to the InDesign SDK forum. Is no one writing Illustrator plug-ins anymore?
But hey, I'll keep posting, if only for my own amusement, about my saga of writing a plug-in.
I figured out some of the annotation stuff, but I'm still puzzled by some things.
I started by simply trying to create a tool which would carry a 100x100 box around with it when moved on the screen -- no clicking or dragging yet -- much as the symbol sprayer, for example, has a nice circle (albeit of varying size) around it. I created the tool and added it as an annotator. When it receives a kSelectorAITrackToolCursor message, it simply captures the cursor location in a global and sets the PlatformCursor. When the tool receives a kCallerAIAnnotation message, I have this code:
extern AIErr toolAnnotate( AIAnnotatorMessage *message ) {
    AIErr error = kNoErr;
    error = sView->ArtworkPointToViewPoint( message->view, &g->cursorPoint, &g->cursorPointScreen );
    g->annoBoundsScreen.top = g->cursorPointScreen.v - 50;
    g->annoBoundsScreen.bottom = g->cursorPointScreen.v + 50;
    g->annoBoundsScreen.left = g->cursorPointScreen.h - 50;
    g->annoBoundsScreen.right = g->cursorPointScreen.h + 50;
    ADMDrawerRef dr = sADMDrawer->Create(message->port, &g->annoBoundsScreen, kADMPaletteFont);
    ASRect myRect;
    myRect.top = 0;
    myRect.bottom = 100;
    myRect.left = 0;
    myRect.right = 100;
    sADMDrawer->SetDrawMode( dr, kADMXORMode );
    sADMDrawer->SetADMColor( dr, kADMBlackColor );
    sADMDrawer->DrawRect( dr, &myRect );
    sADMDrawer->Destroy( dr );
    sAnnotator->InvalAnnotationRect ( message->view, &g->annoBoundsScreen );
This (should) convert the cursor location (in artwork coordinates) to screen coordinates, set the annotation boundaries based on this location, create the drawer reference, and draw the 100x100 rectangle within this reference. Finally, it invalidates this rectangle as per the Annotation suite documentation.
I fired up the tool in Illy 10 and saw a single box created down at the 0, 0 point on the page. No box followed the cursor. Hmm. I added an sADMBasic->Beep() to the annotation code and realized what was happening -- my tool was getting an annotation message when first selected, but none when it was merely moved around the screen.
After some futzing around I discovered that if I added a call to sView->SetDocumentViewInvalidDocumentRect in the TrackToolCursor code, I got an annotate message every time the mouse was moved! I captured the previous cursor position and invalidated the rectangle 50 points on all sides from it. and tried again. Success -- partially.
At this point, the cursor could be moved around with the box following it. It suffers, however, from the following bugs:
1) The SetDocumentViewInvalidDocumentRect is in artwork coordinates and so only works at 100% or greater. If I zoom out, my little box leaves trails all over the screen. In addition, if I zoom in, the cursor stutters noticeably -- I assume because Illustrator is forcing a redraw on large portions of the document. I think I can fix both these bugs by recalculating the SetDocumentViewInvalidDocumentRect into screen coordinates. However I note that the circle of the symbol sprayer can be made huge -- as large as the screen -- and it still moves smoothly. So maybe calling sView->SetDocumentViewInvalidDocumentRect is not the way to force annotations. But I haven't been able to discover another way.
2) When the mouse moves into a palette, the square remains "hung up" at the last position where the cursor was in the document window. I think I can fix this by utilizing the Suspend and Resume notifiers and doing one last InvalAnnotationRect when I get the Suspend notification.
3) For fun I tried clicking and dragging. Bad news. If I do this, thereafter the entire Illustrator window only redraws iself in the small rectangle that was set when I created the drawer port. By chance I found that if I use another tool that annotates such as the pencil *before* I use my tool, then everything is fine (although of course the box doesn't follow the cursor around anymore because my toolMouseDrag code is empty). How is using a previous tool "fixing" my code? I don't understand this one at all.
Anyway, I suppose I could fork over a wad of cash and join the ADN and purchase a support case -- but hey, I'm just a hobbyist messing around at this point and facing some rather crappy documentation. Any tips will be much appreciated.
John