Sprocket Menus 2
Volume Number: | | 11
|
Issue Number: | | 6
|
Column Tag: | | Getting Started
|
Sprocket Menus, Part 2
By Dave Mark, MacTech Magazine Regular Contributing Author
Note: Source code files accompanying article are located on MacTech CD-ROM or source code disks.
Last month, we explored Sprockets 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 months column.
Two months ago, we built a TPictureWindow class that implemented a Drag Manager-friendly PICT window. This month, were going to add a new class to our Drag Manager example. Well 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.
Lets get started...
Sprocket Resources
Well base this months 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 wont be making any changes to Sprocket, theres 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. Youll 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, youll 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, youll number all your resource Ids starting at 1000.
Change the first item in this CMNU from New to New Text Window and change the items 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 0CMNU resource.
Edit MBAR 128, changing the second entry from 129 to 1000. Well 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. Well 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 (youll find the file PictWindow.cp in this same folder). Add TextWindow.cp to the project. Heres 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. Heres 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, weve entered the code for a new class, named TTextWindow. As you look through the source code, youll 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, youll 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, weve 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 windows 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 windows 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 youll 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 youll 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, youll be adding declarations and definitions for Activate(), Click(), the static member function SetUpStaticMenu(), and the static data member fgMenu. Heres the code for TPictureWindow::Activate():
void
TPictureWindow::Activate( Boolean activating )
{
if ( activating )
{
InsertMenu( fgMenu, 0 );
gMenuBar->Invalidate();
}
else
DeleteMenu( mPicture );
}
Heres the code for TPictureWindow::Click():
void
TPictureWindow::Click( EventRecord * )
{
this->Select();
}
Since we dont use the parameter to Click(), we dont give it a name. This keeps us from getting the annoying warning about an unused parameter.
Heres the code for TPictureWindow::SetUpStaticMenu():
void
TPictureWindow::SetUpStaticMenu( void )
{
TPictureWindow::fgMenu = gMenuBar->GetMenuFromCMNU( mPicture );
}
Finally, heres 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;
Heres 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();
Heres 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;
}
}
Well add the command handling code in next months 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;
}
Heres 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
Youve just made a bunch of changes to your source code, so chances are, youll 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 well try to help. Of course, if you dont 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. Dont bother with the Text menu yet. Well 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, dont bother with the Picture menu items. Well get to them next month as well. Click on the text window to bring the Text menu back.
A correction from a few months 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. Its just that once you start playing with Sprocket, its hard to stop. Next month, well 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. Well 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.