Sprocket Menus, Part 2

By Dave Mark, MacTech Magazine Regular Contributing Author

Last month, we explored Sprocket’s menu handling mechanism. We took advantage of the ‘CMNU’ resource to create menus with command numbers attached to each menu item. We loaded the ‘CMNU’ menus and registered the commands by calling the TMenuBar classes’ GetMenuFromCMNU() method. We edited the routine HandleMenuCommand() in the file SprocketStarter.cp to dispatch these commands. If any of this seems a little hazy, you might want to take a few minutes to review last month’s column.

Two months ago, we built a TPictureWindow class that implemented a Drag Manager-friendly PICT window. This month, we’re going to add a new class to our Drag Manager example. We’ll add a TTextWindow class that is also Drag Manager friendly. In addition to supporting two different window types, the application will place a different menu in the menu bar, depending on the type of the front-most window.

Let’s get started...

Sprocket Resources

We’ll base this month’s program on the Sprocket labeled “Sprocket.02/01/95” and the SprocketStarter labeled “SprocketDragger.02/01/95”. First make sure you have both of these folders. Now make a copy of the SprocketDragger folder, calling it “SprocketPicText.03/25/95”. Since we won’t be making any changes to Sprocket, there’s no need to make a copy of the Sprocket folder.

Launch your favorite resource editor and open the file StandardMenus.rsrc inside your Sprocket folder. Copy the ‘CMNU’ resource with an ID of 129 (the one that implements the File menu), then close StandardMenus.rsrc.

Now go into the SprocketPicText folder and open the resource file SprocketStarter.rsrc. You’ll be creating all your Sprocket resources in SprocketStarter.rsrc. If you can avoid it, try not to modify any other Sprocket resources. At the very least, keep those changes to a minimum. If you can avoid changing your master Sprocket folder, you’ll be able to get by with a single, Sprocket folder shared by all your Sprocket applications.

Paste the ‘CMNU’ you copied from StandardMenus.rsrc into SprocketStarter.rsrc. Change the resource ID from 129 to 1000. Be sure to change the ID in both places (Get Resource Info from the Resource menu and Edit Menu & MDEF id from the MENU menu). Wherever possible, you’ll number all your resource Ids starting at 1000.

Change the first item in this ‘CMNU’ from New to New Text Window and change the item’s command number (Cmd-Num) to 1000. Insert a new, second item reading New Picture Window with a command number of 1001. Figure 1 shows a ResEdit screen shot of the File ‘CMNU’.

Figure 1. The 0 File 0‘CMNU’ resource.

Edit ‘MBAR’ 128, changing the second entry from 129 to 1000. We’ll be including our own copy of the File ‘CMNU’ in the menu bar instead of the original. Notice that we did this without making a change to any of the Sprocket resource files.

Duplicate ‘WIND’ 1028, change its ID to 1029 and its window title from Picture Window to Text Window. This ‘WIND’ will serve as the template for new text windows.

Create a new ‘STR’ resource with an ID of 1000 and containing the text “<Default Text>” (without the quotes). This text will appear in the text window before any text has been dragged into it.

Create two new ‘CMNU’ resources, one with an ID of 1001 and the other with an ID of 1002. Be sure to change the Ids in both places. ‘CMNU’ 1001 has a title of Picture and contains two items. Item 1 is Centered, has a check mark next to it and has a command number of 1001. Item 2 is Upper Left, has no mark next to it, and has a command number of 1002.

‘CMNU’ 1002 has a title of Text and contains three items. Each of these items has a submenu. Item 1 is Font, has a command number of 1003, and uses submenu 131. Item 2 is Size, has a command number of 1004, and uses submenu 132. Item 3 is Style, has a command number of 1005, and uses submenu 133. You can find all three of these submenus in StandardMenus.rsrc. We’ll use them as is.

Source Code: TextWindow.cp

Create a new source code window, save it in the SprocketPicText.03/25/95 folder, inside the SprocketStarter subfolder, as TextWindow.cp (you’ll find the file PictWindow.cp in this same folder). Add TextWindow.cp to the project. Here’s the source code:

const short kTextWindowTemplateID = 1029;
const short kDefaultSTRResID = 1000;


#include "TextWindow.h"
#include <ToolUtils.h>

MenuHandleTTextWindow::fgMenu;
unsigned long    TTextWindow::fgWindowTitleCount = 0;


TTextWindow::TTextWindow()
{
 fDraggedTextHandle = nil;

 TTextWindow::fgWindowTitleCount++;
 this->CreateWindow();
}


TTextWindow::~TTextWindow()
{
}


WindowPtr
TTextWindow::MakeNewWindow( WindowPtr behindWindow )
{
 WindowPtraWindow;
 Str255 titleString;
 GrafPtrsavedPort;
 
 GetPort(&savedPort);
 
 aWindow = GetNewColorOrBlackAndWhiteWindow( kTextWindowTemplateID,
 nil, behindWindow );
 
 if (aWindow)
 {
 GetWTitle(aWindow,titleString);
 if (StrLength(titleString) != 0)
 {
 Str255 numberString;
 
 NumToString( fgWindowTitleCount, numberString );
 BlockMove(&numberString[1],&titleString[titleString[0]+1],
 numberString[0]);
 titleString[0] += numberString[0];
 }
 SetWTitle(aWindow,titleString);

 SetPort(aWindow);

 ShowWindow(aWindow);
 }
 SetPort(savedPort);

 return aWindow;
}


void
TTextWindow::Draw(void)
{
 Rect   r;
 char   *textPtr;
 long   textLength;
 Handle stringH;
 
 r = fWindow->portRect;
 EraseRect( &r );

 if ( fDraggedTextHandle == nil )
 {
 stringH = (Handle)GetString( kDefaultSTRResID );
 
 if ( stringH == nil )
 return;
 
 HLock( stringH );
 
 textPtr = &((*stringH)[1]);
 textLength = (long)((*stringH)[0]);
 TETextBox( textPtr, textLength, &r, teFlushLeft );
 
 HUnlock( stringH );
 }
 else
 {
 HLock( fDraggedTextHandle );
 
 TETextBox( *fDraggedTextHandle, 
 (long)GetHandleSize(fDraggedTextHandle), 
 &r, teFlushLeft );
 
 HUnlock( fDraggedTextHandle );
 }
}


void
TTextWindow::Activate( Boolean activating )
{
 if ( activating )
 {
 InsertMenu( fgMenu, 0 );
 gMenuBar->Invalidate();
 }
 else
 DeleteMenu( mText );
}

void
TTextWindow::Click( EventRecord * )
{
 this->Select();
}

void
TTextWindow::ClickAndDrag( EventRecord *eventPtr )
{
 OSErr  err;
 DragReference   dragRef;
 RgnHandle       dragRegion, tempRgn;
 Rect   itemBounds;
 char   *textPtr;
 long   textLength;
 Handle stringH;
    
    err = NewDrag( &dragRef );
    if ( err != noErr )
 return;

 if ( fDraggedTextHandle == nil )
 {
 stringH = (Handle)GetString( kDefaultSTRResID );
 if ( stringH == nil )
 return;
 
 HLock( stringH );
 
 textPtr = &((*stringH)[1]);
 textLength = (long)((*stringH)[0]); 
 
 err = AddDragItemFlavor( dragRef,
                              (ItemReference)fWindow,
                              (FlavorType) 'TEXT',
                              textPtr,
                              textLength,
                              (FlavorFlags)0 );
 
 HUnlock( stringH );
 }
 else
 {
 HLock( fDraggedTextHandle );
 
 err = AddDragItemFlavor( dragRef,
                              (ItemReference)fWindow,
                              (FlavorType) 'TEXT',
                              *fDraggedTextHandle,
                 (long)GetHandleSize(fDraggedTextHandle),
                 (FlavorFlags)0 );
 
 HUnlock( fDraggedTextHandle );
 }
    if ( err != noErr )
 {
 DisposeDrag( dragRef );
 return;
 }
 
 itemBounds = (**((WindowPeek)fWindow)->contRgn).rgnBBox;
 
 err = SetDragItemBounds( dragRef, (ItemReference)fWindow, 
 &itemBounds );
 if ( err != noErr )
 {
 DisposeDrag( dragRef );
 return;
 }
 
    dragRegion = NewRgn();
 RectRgn( dragRegion, &itemBounds );
 tempRgn = NewRgn();
 CopyRgn( dragRegion, tempRgn );
 InsetRgn( tempRgn, 1, 1 );
 DiffRgn( dragRegion, tempRgn, dragRegion );
 DisposeRgn( tempRgn );
 
    err = TrackDrag( dragRef, eventPtr, dragRegion );
    DisposeRgn( dragRegion );
    DisposeDrag( dragRef );
    return;
}


OSErr
TTextWindow::DragEnterWindow( DragReference dragRef )
{
 fCanAcceptDrag = IsTextFlavorAvailable( dragRef );
 fIsWindowHighlighted = false;
 
 if ( fCanAcceptDrag )
 return noErr;
 else
 return dragNotAcceptedErr;
}


OSErr
TTextWindow::DragInWindow( DragReference dragRef )
{
 DragAttributes  attributes;
 RgnHandletempRgn;

 GetDragAttributes( dragRef, &attributes );
 
 if ( (! fCanAcceptDrag) || (! (attributes & 
 dragHasLeftSenderWindow)) 
 || (attributes & dragInsideSenderWindow) )
 return dragNotAcceptedErr;
 
 if ( this->IsMouseInContentRgn( dragRef ) )
 {
 if ( ! fIsWindowHighlighted )
 {
 tempRgn = NewRgn();
 RectRgn( tempRgn, &fWindow->portRect );
 
 if ( ShowDragHilite( dragRef, tempRgn, true ) == noErr )
 fIsWindowHighlighted = true;
 
 DisposeRgn(tempRgn);
 }
 }
 
 return noErr;
}


OSErr
TTextWindow::DragLeaveWindow( DragReference dragRef )
{
 if ( fIsWindowHighlighted )
 HideDragHilite( dragRef );
 
 fIsWindowHighlighted = false;
 fCanAcceptDrag = false;
 
 return noErr;
}


OSErr
TTextWindow::HandleDrop( DragReference dragRef )
{
 OSErr  err;
 Size   dataSize;
 ItemReference item;
 FlavorFlagsflags;
 DragAttributes  attributes;

 GetDragAttributes( dragRef, &attributes );
 
 if ( attributes & dragInsideSenderWindow )
 return dragNotAcceptedErr;

 err = GetDragItemReferenceNumber( dragRef, 1, &item );
 if ( err == noErr )
 err = GetFlavorFlags( dragRef, item, 'TEXT', &flags );

 if ( err == noErr )
 {
 err = GetFlavorDataSize( dragRef, item, 'TEXT', &dataSize);
 if  (err == noErr )
 {
 fDraggedTextHandle = TempNewHandle( dataSize, &err );
 
 if ( fDraggedTextHandle == nil )
 fDraggedTextHandle = NewHandle( dataSize );

 if ( fDraggedTextHandle == nil )
 err = dragNotAcceptedErr;
 else
 {
 HLock( fDraggedTextHandle );
 err = GetFlavorData( dragRef, item, 'TEXT',
 *fDraggedTextHandle, &dataSize, 0L );
 HUnlock( fDraggedTextHandle );

 if ( err != noErr)
 {
 err = dragNotAcceptedErr;
 DisposeHandle( fDraggedTextHandle );
 fDraggedTextHandle = nil;
 }
 else
 {
 SetPort( fWindow );
 InvalRect( &(fWindow->portRect) );
 }
 }
 }
 }
 
 return( err );
}


void
TTextWindow::SetTextFont( short newFont )
{
 GrafPtroldPort;
 
 GetPort( &oldPort );
 SetPort( fWindow );
 
 TextFont( newFont );
 
 SetPort( oldPort );
}


Boolean
TTextWindow::IsTextFlavorAvailable( DragReference dragRef )
{
 unsigned short  numItems;
 FlavorFlagsflags;
 OSErr  err;
 ItemReference item;
 
 CountDragItems( dragRef, &numItems );
 
 if ( numItems < 1 )
 return( false );
 
 err = GetDragItemReferenceNumber( dragRef, 1, &item );
 if ( err == noErr )
 err = GetFlavorFlags( dragRef, item, 'TEXT', &flags );
 
 return( err == noErr );
}


Boolean
TTextWindow::IsMouseInContentRgn( DragReference dragRef )
{
 Point  globalMouse;
 OSErr  err;
 
 err = GetDragMouse( dragRef, &globalMouse, 0L );
 
 if ( err == noErr )
 return( PtInRgn(  globalMouse, 
 ((WindowPeek)fWindow)->contRgn ) );
 else
 return( false );
}


void
TTextWindow::SetUpStaticMenu( void )
{
 TTextWindow::fgMenu = gMenuBar->GetMenuFromCMNU( mText );
}

Source Code: TextWindow.h

Save and close TextWindow.cp. Create a second source code window, named TextWindow.h. Here’s the source code:

#ifndef _TEXTWINDOW_
#define _TEXTWINDOW_

#ifndef _WINDOW_
#include"Window.h"
#endif
 
enum
{
 mText  = 1002,
 cFont  = 1004,
 cSize  = 1005,
 cStyle = 1006
};


class TTextWindow : public TWindow
{
  public:
  TTextWindow();
 virtual  ~TTextWindow();

 virtual WindowPtr MakeNewWindow( WindowPtr behindWindow );

 virtual void    Draw(void);
 
 virtual void    Activate( Boolean activating );
 
 virtual void    Click( EventRecord * anEvent );
 
 virtual void    ClickAndDrag( EventRecord *eventPtr );
 
 virtualOSErr    DragEnterWindow( DragReference dragRef );
 virtualOSErr    DragInWindow( DragReference dragRef );
 virtualOSErr    DragLeaveWindow( DragReference dragRef );
 virtualOSErr    HandleDrop( DragReference dragRef );
 
// Non-TWindow methods...
 virtualvoid SetTextFont( short newFont );
 virtualBoolean   IsTextFlavorAvailable( DragReference dragRef );
 virtualBoolean IsMouseInContentRgn( DragReference dragRef );
 static void SetUpStaticMenu( void );

protected:
 static MenuHandle fgMenu;
 static unsigned longfgWindowTitleCount;

 BooleanfCanAcceptDrag;
 Handle fDraggedTextHandle;
 BooleanfIsWindowHighlighted;
};

#endif

Some Thoughts on TTextWindow

So far, we’ve entered the code for a new class, named TTextWindow. As you look through the source code, you’ll notice that this class bears an incredibly strong resemblence to the TPictureWindow class. Exactamundo! There are a few changes to the class worth noting.

First and foremost, we changed the drag flavor that this class deals with from ‘PICT’ to ‘TEXT’. This means that a TTextWindow supports dragging (in both directions - to and from the window) of ‘TEXT’ drag items instead of ‘PICT’ drag items.

As you look through the source code, keep this in mind: The default text for the window is a StringHandle loaded from a ‘STR ’ resource. A StringHandle is a pointer to a pointer to a Pascal string (a length byte, followed by the string itself). The data passed around by the Drag Manager is a pointer to a block of text, without a leading length byte. The length of the text block is passed as a separate parameter. As you make your way through the source code, you’ll occasionally see two cases for dealing with the fDraggedTextHandle data member. If fDraggedTextHandle is nil, we load the StringHandle from the ‘STR ’ resource and are therefore dealing with a Pascal string. Otherwise, we already have a block of text or are about to receive a block of text, neither of which contains a length byte.

In addition to the changes to get us from ‘PICT’ to ‘TEXT’, we’ve added three new member functions to both the TTextWindow and TPictureWindow classes.

Activate() adds that classes’ menu to the menu bar on activation, and removes the menu on deactivation. TTextWindow::Activate() adds and removes the Text menu. TTextWindow::Activate() adds and removes the Picture menu.

Click() gets called when a non-drag click occurs in a window’s content region. We call the inherited Select() method to bring the window to the front. Without the addition of Click(), a click in a non-frontmost window would not bring it to the front (clicking in the window’s drag region would bring it to the front, however).

SetUpStaticMenu() is a static member function. It calls GetMenuFromCMNU() to load either the Text or Picture menu and register all its commands. The loaded menu is stored in the static data member fgMenu. Why use static members? Static members are not tied to objects of a class, but are instantiated once for the entire class. For example, there is only one copy of the data member TTextWindow::fgMenu, no matter how many TTextWindow objects have been created. All the TTextWindow objects share this single copy of fgMenu. The line of code:

MenuHandleTTextWindow::fgMenu;

at the top of TTextWindow.cp actually allocates memory for fgMenu before any TTextWindow objects exist. The same thing is true for TPictureWindow::fgMenu.

As you’ll see, we call both classes’ SetUpStaticMenu() functions in the function SetupApplication() in the file SprocketStarter.cp. This loads the ‘CMNU’ resource and registers all the commands before any TTextWindow or TPictureWindow objects are created. When one of these windows is created, it uses the MenuHandle saved in fgMenu to add the menu to the menu bar without having to reregister the commands then unregister the commands each time a window is activated and deactivated.

Source Code: TPictureWindow.cp and TPictureWindow.h

Here are the rest of the changes you’ll need to make to bring TPictureWindow up to speed, and to tie in the new menus and commands. Edit PictureWindow.cp and PictureWindow.h and add the three new member functions and the new static to both files. As a reminder, you’ll be adding declarations and definitions for Activate(), Click(), the static member function SetUpStaticMenu(), and the static data member fgMenu. Here’s the code for TPictureWindow::Activate():

void
TPictureWindow::Activate( Boolean activating )
{
 if ( activating )
 {
 InsertMenu( fgMenu, 0 );
 gMenuBar->Invalidate();
 }
 else
 DeleteMenu( mPicture );
}

Here’s the code for TPictureWindow::Click():

void
TPictureWindow::Click( EventRecord * )
{
 this->Select();
}

Since we don’t use the parameter to Click(), we don’t give it a name. This keeps us from getting the annoying warning about an unused parameter.

Here’s the code for TPictureWindow::SetUpStaticMenu():

void
TPictureWindow::SetUpStaticMenu( void )
{
 TPictureWindow::fgMenu = gMenuBar->GetMenuFromCMNU( mPicture );
}

Finally, here’s the line of code you should place at the top of PictureWindow.cp. Place it just before or after the definition of fgWindowTitleCount:

MenuHandleTPictureWindow::fgMenu;

Here’s the newly updated TPictureWindow.h. Notice the enumeration toward the top of the file. Be sure to add this to your version. It contains the Picture menu ID and command numbers. There a corresponding enum in TTextWindow.h:

#ifndef _PICTUREWINDOW_
#define _PICTUREWINDOW_

#ifndef _WINDOW_
#include"Window.h"
#endif


enum
{
 mPicture = 1001,
 cCentered= 1002,
 cUpperLeft = 1003
};


class TPictureWindow : public TWindow
{
  public:
 TPictureWindow();
 virtual  ~TPictureWindow();

 virtual WindowPtr MakeNewWindow( WindowPtr behindWindow );

 virtual void    Draw(void);
 
 virtual void    Activate( Boolean activating );
 
 virtual void    Click( EventRecord * anEvent );
 
 virtual void    ClickAndDrag( EventRecord *eventPtr );
 
 virtualOSErr    DragEnterWindow( DragReference dragRef );
 virtualOSErr    DragInWindow( DragReference dragRef );
 virtualOSErr    DragLeaveWindow( DragReference dragRef );
 virtualOSErr    HandleDrop( DragReference dragRef );
 
// Non-TWindow methods...
 virtual PicHandle LoadDefaultPicture();
 virtual void    CenterPict(  PicHandle      picture, 
 Rect   *destRectPtr );
 virtual Boolean IsPictFlavorAvailable( DragReference dragRef );
 virtual Boolean IsMouseInContentRgn( DragReference dragRef );
 static  void    SetUpStaticMenu( void );

protected:
 static MenuHandle fgMenu;
 static unsigned longfgWindowTitleCount;

 BooleanfCanAcceptDrag;
 PicHandlefDraggedPicHandle;
 BooleanfIsWindowHighlighted;
};

#endif

Source Code: SprocketStarter.h

Next, add this enum to SprocketStarter.h. It contains the command numbers we added to the File menu:

enum
{
 cNewTextWindow  = 1000,
 cNewPictureWindow = 1001
};

Source Code: SprocketStarter.cp

Next, edit the file SprocketStarter.cp. In the routine SetupApplication(), add these two lines just before the call to InitCursor():

 TTextWindow::SetUpStaticMenu();
 TPictureWindow::SetUpStaticMenu();

Here’s the new version of the routine HandleMenuCommand(), with our new command number constants. Notice that we lost the command cNew:

void
HandleMenuCommand(MenuCommandID theCommand)
 {
 switch (theCommand)
 {
 case cAbout:
 AboutBox();
 break;
 
 case cNewTextWindow:
 CreateNewTextWindow();
 break;
 
 case cNewPictureWindow:
 CreateNewPictureWindow();
 break;
 
 case cCentered:
 SysBeep( 20 );
 break;
 
 case cUpperLeft:
 SysBeep( 20 );
 break;
 
 case cOpen:
 OpenExistingDocument();
 break;
 
 case cPreferences:
 TPreferencesDialogWindow * prefsDialog = 
 new TPreferencesDialogWindow;
 break;
 
#ifqAOCEAware
 case cNewMailableWindow:
 TMailableDocWindow *aWackyThing = new TMailableDocWindow;
 break;
#endif
 
 default:
 break;
 }
 }

We’ll add the command handling code in next month’s column. For now, we are only concerned that the proper menu appears when the appropriate window is in front and that the text dragging code works.

Next, add these two function prototypes to the file:

OSErr CreateNewTextWindow(void);
OSErr CreateNewPictureWindow(void);

Add these two routines after the routine SetupApplication():

OSErr
CreateNewPictureWindow(void)
 {
 TPictureWindow  *aNewWindow = new TPictureWindow();
 
 if (aNewWindow)
 return noErr;
 else
 return memFullErr;
 }

OSErr
CreateNewTextWindow(void)
 {
 TTextWindow*aNewWindow = new TTextWindow();
 
 if (aNewWindow)
 return noErr;
 else
 return memFullErr;
 }

Here’s a new version of CreateNewDocument(). Notice that instead of creating a TPictureWindow object in line, we call one of the object creation routines we just created:

OSErr
CreateNewDocument(void)
 {
 return CreateNewTextWindow();
 }

Finally, add the #include for TextWindow.h at the top of the file:

#include "TextWindow.h"

Running the Program

You’ve just made a bunch of changes to your source code, so chances are, you’ll probably have a few kinks to iron out before you get your code to compile. As always, if you run into problems, send email to sprocket@hax.com and we’ll try to help. Of course, if you don’t feel like typing in all these changes, you can find the source code at all the usual on-line places. Just remember, if you are downloading the project, be sure you end up with the folders “SprocketPicText.03/25/95” and “Sprocket.02/01/95”. The files I uploaded were named “SprocketPicText.03/25/95.sit” and “Sprocket.02/01/95.sit”.

OK. When you run your project, a text window will appear, along with a Text menu. Don’t bother with the Text menu yet. We’ll fill all that in next month. For now, open the Scrapbook, then click back on the text window to bring it back to the front. Click and drag from the text window to the Scrapbook. The text <Default Text> should appear in the Scrapbook. Find some text and paste it into the Scrapbook. Drag the text from the Scrapbook into the text window. Love that Drag Manager!

Next, create a new picture window. Notice that the Text menu disappears and that a Picture menu appears. Once again, don’t bother with the Picture menu items. We’ll get to them next month as well. Click on the text window to bring the Text menu back.

A correction from a few month’s ago. Faithful reader Joe Kaufman wrote in to point out that in the ListTester application, we never delete the link in the routine DeleteLink(). That is a problem! Add the line

delete linkPtr;

just before the return at the bottom of TLinkedList::DeleteLink(). Thanks for the eagle-eyes, Joe.

’Til Next Month

Hmmm... This column ran a lot longer than I anticipated. Sorry about that. It’s just that once you start playing with Sprocket, it’s hard to stop. Next month, we’ll add the font-oriented submenus to our Text menu and use them to change the font, size, and style of the text displayed in each window. We’ll also implement the commands listed in the Picture window. Until then, take a look through the source, especially at the static data members and member functions.