LMenu

LMenu is a PowerPlant class that is used for managing a Mac OS menu. This class maintains a mapping between Menu items and Command numbers.

Methods :

The methods in this class are:

LMenu()	~LMenu()
CommandFromIndex()	FindNextCommand()
GetMacMenuH()	GetMenuID()
GetNextMenu()	IndexFromCommand()
InsertCommand()	IsInstalled()
IsUsed()	ItemIsEnabled()
ReadCommandNumbers()	RemoveCommand()
RemoveItem()	SetCommand()
SetInstalled()	SetNextMenu()
SetUsed()	SyntheticCommandFromIndex()

Data Members:

The data members in this class are:

mNextMenu	mMacMenuH
mMENUid	mNumCommands
mCommandNums	mIsInstalled
mUsed

Operation:

To learn more about effectively using the LMenu class, refer to The PowerPlant Book for a lengthy discussion on the topic.

Source Files:

(Support Classes)

LMenu.h

LMenu.cp

LMenu()

Purpose:

The constructors create objects from the passed-in parameters.

Access:

Public

Prototypes:

LMenu();

LMenu( ResIDT inMENUid);

LMenu( SInt16 inMENUid,Str255 inTitle );

The parameters for these constructors are:

ResIDT	inMENUid	The resource ID for the menu.
SInt16	inMENUid	The resource ID for the menu.
Str255	inTitle	The string to use for a title.

~LMenu()

Purpose:

The destructor destroys the LMenu object.

Access:

Public

Prototype:

~LMenu();

CommandFromIndex()

Purpose:

Return the command number for a particular Menu item.

Access:

Public

Prototype:

CommandT CommandFromIndex( SInt16 inIndex ) const;

The parameter for this method is:

SInt16

inIndex

The index to use to retrieve the command number.

Return:

The command number.

FindNextCommand()

Purpose:

Retrieve the next command.

Access:

Public

Prototype:

Boolean FindNextCommand( SInt16 &ioIndex,

CommandT &outCommand ) const;

The parameters for this method are:

SInt16&	ioIndex	The index to use to retrieve the command.
CommandT&	outCommand	The command.

Return:

Returns true if the command is found.

GetMacMenuH()

Purpose:

Retrieve OS menu handle.

Access:

Inline, Public

Prototype:

MenuHandle GetMacMenuH() const;

None

Return:

A handle to the menu.

GetMenuID()

Purpose:

Retrieve the menu ID.

Access:

Inline, Public

Prototype:

ResIDT GetMenuID() const;

None

Return:

The resource ID of the menu.

GetNextMenu()

Purpose:

Retrieve the next menu.

Access:

Inline, Protected

Prototype:

LMenu* GetNextMenu() const;

None

Return:

A pointer to the LMenu object.

IndexFromCommand()

Purpose:

Return the Menu item index number for a particular command number Return 0 if the command number is not used for this Men

Access:

Public

Prototype:

SInt16 IndexFromCommand(

CommandT inCommand ) const;

The parameter for this method is:

CommandT&

inCommand

The command.

Return:

SInt16 containing the index.

InsertCommand()

Purpose:

Insert an item with the specified text and command number afterparticular item.

Access:

Public

Prototype:

void InsertCommand( ConstStringPtr inItemText,

CommandT inCommand,

SInt16 inAfterItem );

The parameters for this method are:

ConstStringPtr	inItemText	The index to use to retrieve the command.
CommandT&	inCommand	The command.
SInt16	inAfterItem	The item to insert after.

Return:

None

Remarks:

This function does not support adding multiple menu items using "Return" or "Semicolon" characters within inItemText.

IsInstalled()

Purpose:

Retrieves the value of mIsInstalled.

Access:

Inline, Public

Prototype:

Boolean IsInstalled() const;

None

Return:

The value of mIsInstalled.

IsUsed()

Purpose:

Retrieves the value of mUsed.

Access:

Inline, Public

Prototype:

Boolean IsUsed() const;

None

Return:

The value of mUsed.

ItemIsEnabled()

Purpose:

Return whether an item at the specified position is enabled.

Access:

Public

Prototype:

Boolean ItemIsEnabled( SInt16 inIndex ) const;

The parameter for this method is:

SInt16

inIndex

The index to check.

Return:

Returns true if enabled, else false.

ReadCommandNumbers()

Purpose:

Get command numbers from the 'Mcmd' resource. A 'Mcmd" resource with the same ID as the 'MENU' resource contains a list of command numbers. The format of a 'Mcmd' resource is:

• Number of Commands: n (2 bytes)
• Command Num for Item 1 (4 bytes)
• Command Num for Item n (4 bytes) Access:

Protected

Prototype:

void ReadCommandNumbers();

None

Return:

None

RemoveCommand()

Purpose:

Remove the Menu item with the specified command.

Access:

Public

Prototype:

void RemoveCommand( CommandT inCommand );

The parameter for this method is:

CommandT

inCommand

The command for the menu item to remove.

Return:

None

RemoveItem()

Purpose:

Remove the Menu item at the specified position.

Access:

Public

Prototype:

void RemoveItem( SInt16 inItemToRemove );

The parameter for this method is:

SInt16

inItemToRemove

The menu item to remove.

Return:

None

SetCommand()

Purpose:

Set the command number for a Menu item.

Access:

Public

Prototype:

void SetCommand(

SInt16 inIndex,

CommandT inCommand );

The parameters for this method are:

SInt16	inIndex	The index to use to set the command.
CommandT&	inCommand	The command.

Return:

None

SetInstalled()

Purpose:

Sets the value of the mIsInstalled data member.

Access:

Public

Prototype:

void SetInstalled(Boolean inInstalled);

The parameter for this method is:

Boolean

inInstalled

The value to set.

Return:

None

SetNextMenu()

Purpose:

Set the next Menu.

Access:

Inline, Protected

Prototype:

void SetNextMenu( LMenu *inMenu );

The parameter for this method is:

LMenu*

inMenu

The pointer to the Menu to set.

Return:

None

SetUsed()

Purpose:

This method sets the value of the mUsed data member.

Access:

Public

Prototype:

void SetUsed( Boolean inUsed );

The parameter for this method is:

Boolean

inUsed

The value to set the data member to.

Return:

None

SyntheticCommandFromIndex()

Purpose:

Retrieve the synthetic command number for a particular Menu item. A synthetic command number has the MENU id in the high 16 bits and the item number in the low 16 bits, and the resulting 32-bit number is negated (to distinguish it from regular command numbers). The synthetic command number is the negative of the value that would be returned by the Toolbox trap MenuSelect() for the menu item.

Access:

Public

Prototype:

CommandT SyntheticCommandFromIndex(

SInt16 inIndex ) const;

The parameter for this method is:

SInt16

inIndex

The index for the Menu item.

Return:

The command for the Menu item.

mNextMenu

Purpose:

Storage for the next menu.

Access:

Protected

Prototype:

LMenu *mNextMenu;

mMacMenuH

Purpose:

The Mac OS menu handle.

Access:

Protected

Prototype:

MenuHandle mMacMenuH;

mMENUid

Purpose:

The menu ID.

Access:

Protected

Prototype:

ResIDT mMENUid;

mNumCommands

Purpose:

The number of commands.

Access:

Protected

Prototype:

SInt16 mNumCommands;

mCommandNums

Purpose:

The commadn numbers.

Access:

Protected

Prototype:

CommandT **mCommandNums;

mIsInstalled

Purpose:

Storage for detecting installation.

Access:

Protected

Prototype:

Boolean mIsInstalled;

mUsed

Purpose:

Indicates whether used or not.

Access:

Protected

Prototype:

Boolean mUsed;