Menu with information used to allow merging. More...

#include <owl/menu.h>

Inheritance diagram for owl::TMenuDescr:

Public Types
enum	TGroup { FileGroup , EditGroup , ContainerGroup , ObjectGroup , WindowGroup , HelpGroup , NumGroups }
	Used by TMenuDescr, the TGroup enum describes the following constants that define the index of the entry in the GroupCount array. More...

Public Member Functions
	TMenuDescr ()
	Default constructor for a TMenuDescr object.

	TMenuDescr (const TMenuDescr &original)
	Copies the menu descriptor object specified in the other parameter.

	TMenuDescr (TResId id, int fg, int eg, int cg, int og, int wg, int hg, TModule *module=&GetGlobalModule())
	Constructs a menu descriptor from the resource indicated by id.

	TMenuDescr (TResId id, TModule *module=&GetGlobalModule())
	Creates a menu descriptor from the menu resource specified in the id parameter.

	TMenuDescr (HMENU hMenu, int fg, int eg, int cg, int og, int wg, int hg, TModule *module=&GetGlobalModule())
	Constructs a menu descriptor from the menu handle indicated in the hMenu parameter.

	~TMenuDescr ()

TMenuDescr &	operator= (const TMenuDescr &original)

HMENU	GetHandle () const
	Gets the handle to the menu, possibly causing any deferred menu acquisition to occur.

TModule *	GetModule () const
	Returns a pointer to the module object.

void	SetModule (TModule *module)
	Sets the default module object for this menu descriptor.

TResId	GetId () const
	Gets the menu resource ID used to construct the menu descriptor.

int	GetGroupCount (int group) const
	Gets the number of menus in a specified group within the menu bar.

void	ClearServerGroupCount ()
	Not implemented?

void	ClearContainerGroupCount ()
	Not implemented?

bool	Merge (const TMenuDescr &sourceMenuDescr)
	Merges the functional groups of another menu descriptor into this menu descriptor.

bool	Merge (const TMenuDescr &sourceMenuDescr, TMenu &destMenu)
	Merges the functional groups of this menu descriptor and another menu descriptor into an empty menu.

Public Member Functions inherited from owl::TMenu
	TMenu (TAutoDelete autoDelete=AutoDelete)
	Creates an empty menu and sets autoDelete, by default, so that the menu is automatically deleted when the object is destroyed.

	TMenu (const TMenu &original, TAutoDelete autoDelete=AutoDelete)
	Creates a deep copy of an existing menu and sets autoDelete, by default, so that the menu is automatically deleted when the object is destroyed.

	TMenu (HMENU handle, TAutoDelete autoDelete=NoAutoDelete)
	Creates a menu object from an already loaded menu and sets autoDelete, by default, so the menu is not automatically deleted when the object is destroyed.

	TMenu (HWND hWnd, TAutoDelete autoDelete=NoAutoDelete)
	Creates a menu object representing the window's current menu and sets autoDelete, by default, so that the menu is not automatically deleted when the object is destroyed.

	TMenu (const void *menuTemplate)
	Creates a menu object from a menu template in memory.

	TMenu (HINSTANCE instance, TResId resId)
	Creates a menu object from a specified resource ID.

virtual	~TMenu ()

TMenu &	operator= (const TMenu &)
	Copies an existing menu onto this menu, using DeepCopy.

void	CheckValid (uint redId=IDS_MENUFAILURE)
	Throws a TXMenu exception if the menu object is invalid.

	operator TMenuItem () const
	Returns the menu's handle.

	operator HMENU () const
	Returns the menu's handle.

bool	IsOK () const
	Returns true if the menu has a valid handle.

bool	AppendMenu (uint flags, TMenuItem newItem=static_cast< unsigned int >(-1), LPCTSTR newStr=nullptr)
	Adds a text menu item to the end of the menu.

bool	AppendMenu (uint flags, TMenuItem newItem, const tstring &newStr)

bool	AppendMenu (uint flags, TMenuItem newitem, const TBitmap &newBmp)
	Adds a bitmap menu item at the end of the menu.

bool	CheckMenuItem (uint item, uint check)
	Checks or unchecks the menu item.

bool	DeleteMenu (uint item, uint flags)
	Removes the menu item (item) from the menu or deletes the menu item if it's a pop-up menu.

bool	EnableMenuItem (uint item, uint enable)
	Enables, disables, or grays the menu item specified in the item parameter.

uint	GetMenuItemCount () const
	Returns the number of items in a top-level or pop-up menu.

uint	GetMenuItemID (int posItem) const
	Returns the ID of the menu item at the position specified by posItem.

uint	GetMenuState (uint item, uint flags) const
	Returns the menu flags for the menu item specified by item.

int	GetMenuString (uint item, TCHAR *str, int count, uint flags) const
	Returns the label (str) of the menu item (item).

tstring	GetMenuString (uint item, uint flags) const
	String-aware overload.

HMENU	GetSubMenu (int posItem) const
	Returns the handle of the menu specified by posItem.

bool	InsertMenu (uint item, uint flags, TMenuItem newItem=-1, LPCTSTR newStr=nullptr)
	Inserts a new text menu item or pop-up menu into the menu after the menu item specified in item.

bool	InsertMenu (uint item, uint flags, TMenuItem newItem, const tstring &newStr)

bool	InsertMenu (uint item, uint flags, TMenuItem newItem, const TBitmap &newBmp)
	Adds a bitmap menu item after the menu item specified in item.

bool	ModifyMenu (uint item, uint flags, TMenuItem newItem=-1, LPCTSTR newStr=nullptr)
	Changes an existing menu item from the item specified in item to newItem.

bool	ModifyMenu (uint item, uint flags, TMenuItem newItem, const tstring &newStr)

bool	ModifyMenu (uint item, uint flags, TMenuItem newItem, const TBitmap &newBmp)
	Changes an existing menu item into a bitmap.

bool	RemoveMenu (uint item, uint flags)
	Removes the menu item from the menu but does not delete it if it is a submenu.

bool	SetMenuItemBitmaps (uint item, uint flags, const TBitmap bmpUnchecked=nullptr, const TBitmap bmpChecked=nullptr)
	Specifies the bitmap to be displayed when the menu item is checked and unchecked.

uint	GetDefaultItem (bool getPos, uint flags) const

bool	SetDefaultItem (uint posOrId, bool isPos)

bool	CheckRadioItem (uint first, uint last, uint check, uint flags)

bool	GetMenuItemInfo (uint posOrId, bool isPos, TMenuItemInfo &mi) const

bool	SetMenuItemInfo (uint posOrId, bool isPos, TMenuItemInfo &mi)

bool	InsertMenuItem (uint posOrId, bool isPos, TMenuItemInfo &mi)

virtual void	MeasureItem (MEASUREITEMSTRUCT &measureItem)
	MeasureItem is used by owner-drawn controls to store the dimensions of the specified item.

virtual void	DrawItem (DRAWITEMSTRUCT &drawItem)
	DrawItem responds to a message forwarded to a drawable control by TWindow when the control needs to be drawn.

Protected Member Functions
bool	ExtractGroups ()
	Extracts the group counts from the loaded menu bar by counting the number of menus between separator items.

Friends
ipstream &	operator>> (ipstream &is, TMenuDescr &m)

opstream &	operator<< (opstream &os, const TMenuDescr &m)

Additional Inherited Members
Static Public Member Functions inherited from owl::TMenu
static bool	GetMenuCheckMarkDimensions (TSize &size)
	Gets the size of the bitmap used to display the default check mark on checked menu items.

static TSize	GetMenuCheckMarkDimensions ()
	Return the dimensions of the check mark bitmaps.

Static Protected Member Functions inherited from owl::TMenu
static void	DeepCopy (TMenu &dst, const TMenu &src, int srcOffset=0, int itemCount=-1)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

static void	DeepCopy (TMenu &dst, int dstOffset, const TMenu &src, int srcOffset=0, int itemCount=-1)
	Copies menu items from the `src` menu to the `dst` menu.

Detailed Description

Menu with information used to allow merging.

Derived from TMenu, TMenuDescr describes your menu bar and its functional groups.

TMenuDescr provides an easy way for you to group menus on your menu bar and to add new groups to an existing menu bar. It uses a resource ID to identify the menu resource and an array of count values to indicate the number of pop-up menus in each group on the menu bar.

The TGroup enum enumerates the six basic functional groups on a menu bar: File, Edit, Container, Object, Window, and Help. TMenuDescr's constructors simply initialize the members based on the arguments passed.

TFrameWindow::MergeMenu actually performs the real work of merging the menu groups.

For a single document application (SDI), the menus are merged as soon as you load the application. However, for a multiple-document application (MDI), you do not see the final menu until you invoke a child menu. See the sample program, mdifile.cpp, for an example of MDI menu merging.

One technique you can use to create a menu involves invoking the TMenuDescr constructor and passing the number of group counts for each menu selection.

For example, if your original menu groups included these items:

you might use the following group counts:

Group	Count	Menu
FileGroup	1	File
EditGroup	2	Edit Search
ContainerGroup	1	View
ObjectGroup	3	Page Paragraph Word
WindowGroup	1	Window
HelpGroup	1	Help

You would then invoke the constructor this way:

TMenuDescr(IDM_MYMENU, 1, 2, 1, 3, 1, 1)

VarType

Definition safearray.h:14

owl::TMenuDescr::TMenuDescr

TMenuDescr()

Default constructor for a TMenuDescr object.

Definition menudesc.cpp:164

You can build the previous menu by merging two menus. When a zero is passed in the parent menu's constructor, the group indicated by the zero is filled in by the child menu's group, if an item is specified, when the menu merging occurs. Set your application's parent frame menu bar by specifying these menu groups:

and passing these group counts in the constructor:

TMenuDescr(IDM_FRAME, 1, 0, 1, 0, 1, 1)

Set the word-processor child menu bar this way:

and pass these values in the constructor:

TMenuDescr(IDM_WPROC, 0, 2, 0, 3, 0, 1)

If no child is active, only the frame menu will be active. When the word processor's child window becomes active, the child menu bar is merged with the frame menu. Every group that is 0 in the child menu bar leaves the parent's group intact. The previous example interleaves every group except for the last group, the Help group, in which the child replaces the frame menu.

By convention, the even groups (File, Container, Window) usually belong to the outside frame or container, and the odd groups (Edit, Object, Help) belong to the child or contained group.

If a -1 is used in a group count, the merger eliminates the parent's group without replacing it. For example, another child menu bar, such as a calculator, could be added to your application in this way:

TMenuDescr(IDM_WCALC, 0, 1, -1, 1, 0, 1)

In this example, the child's menu group contributes nothing from the container group, and the parent's container group is removed. This produces a merged menu (with the View menu selection eliminated as a result of the -1) that looks like this:

If you want to merge the following parent menu groups

with these paint window menu groups,

pass the following group counts in the constructor:

TMenuDescr(IDM_WPAINT, 0, 1, 0, 2, 0, 1)

This produces the following merged menu:

The simplest way to add groups to a menu bar involves defining the menu groups and adding separators in a resource file. Insert the term MENUITEM SEPARATOR between each menu group and an additional separator if one of the menu groups is not present. For example, the resource file for Step 14 of the ObjectWindows tutorial defines the following menu groups and separators:

IDM_MDICMNDS MENU
{
// Display a grayed File menu
 MENUITEM "File",   0,GRAYED  ;placeholder for File menu from DocManager
 MENUITEM SEPARATOR
 MENUITEM "Edit",   CM_NOEDIT ;placeholder for Edit menu from View
 MENUITEM SEPARATOR
 MENUITEM SEPARATOR
 MENUITEM SEPARATOR
 POPUP "&Window"
{
// Options within the Window menu group
  MENUITEM  "&Cascade",       CM_CASCADECHILDREN
  MENUITEM  "&Tile",          CM_TILECHILDREN
  MENUITEM  "Arrange &Icons", CM_ARRANGEICONS
  MENUITEM  "C&lose All",     CM_CLOSECHILDREN
  MENUITEM  "Add &View",      CM_VIEWCREATE
 }
 MENUITEM SEPARATOR
 POPUP "&Help"
 {
  MENUITEM "&About",   CM_ABOUT
 }
}

You can see the separators by loading Step14.rc into Resource Workshop and disabling the View as Popup Option in the View menu. This resource file defines an Edit group, a File group, a Window group, and a Help group, but no entries for Container or Object groups. Step14.cpp uses these commands from the resource file to set the main window and its menu, passing IDM_MDICMNDS as the parameter to SetMenuDescrfunction, as follows:

SetMainWindow(frame);

GetMainWindow()->SetMenuDescr(TMenuDescr(IDM_MDICMNDS));

It produces the following menu groups:

TMenuDescr's functions let you perform menu merging similar to that of OLE 2. That is, you can merge menus from a container's document (the MDI frame window) with those of an embedded object (the MDI child window). When the embedded object is activated in place by double-clicking the mouse, the menu of the child window merges with that of the frame window.

Definition at line 206 of file menu.h.

Member Enumeration Documentation

◆ TGroup

enum owl::TMenuDescr::TGroup

Used by TMenuDescr, the TGroup enum describes the following constants that define the index of the entry in the GroupCount array.

Enumerator
FileGroup	Index of the File menu group count.
EditGroup	Index of the Edit menu group count.
ContainerGroup	Index of the Container menu group count.
ObjectGroup	Index of the Object group count.
WindowGroup	Index of the Window menu group count.
HelpGroup	Index of the Help menu group count.
NumGroups	Total number of groups.

Definition at line 210 of file menu.h.

Constructor & Destructor Documentation

◆ TMenuDescr() [1/5]

owl::TMenuDescr::TMenuDescr ( )

Default constructor for a TMenuDescr object.

No menu resources or groups are specified. Constructs an empty menu bar.

Definition at line 164 of file menudesc.cpp.

References owl::GetGlobalModule(), and NumGroups.

◆ TMenuDescr() [2/5]

owl::TMenuDescr::TMenuDescr ( const TMenuDescr & original )

Copies the menu descriptor object specified in the other parameter.

Definition at line 177 of file menudesc.cpp.

References NumGroups.

◆ TMenuDescr() [3/5]

owl::TMenuDescr::TMenuDescr	(	TResId	id,
		int	fg,
		int	eg,
		int	cg,
		int	og,
		int	wg,
		int	hg,
		TModule *	module = &GetGlobalModule() )

Constructs a menu descriptor from the resource indicated by id.

Places the pop-up menus in groups according the values of the fg, eg, cg, of, wg, and hg parameters. The fg, eg, cg, of, wg, and hg parameters represent the functional groups identified by the TGroup enum. Calls the function ExtractGroups to extract the group counts based on the separator items in the menu bar.

Definition at line 194 of file menudesc.cpp.

References ContainerGroup, EditGroup, ExtractGroups(), FileGroup, HelpGroup, ObjectGroup, and WindowGroup.

◆ TMenuDescr() [4/5]

owl::TMenuDescr::TMenuDescr	(	TResId	id,
		TModule *	module = &GetGlobalModule() )

Creates a menu descriptor from the menu resource specified in the id parameter.

Calls the function ExtractGroups to extract the group counts based on the separator items in the menu bar.

Definition at line 217 of file menudesc.cpp.

References ExtractGroups().

◆ TMenuDescr() [5/5]

owl::TMenuDescr::TMenuDescr	(	HMENU	hMenu,
		int	fg,
		int	eg,
		int	cg,
		int	og,
		int	wg,
		int	hg,
		TModule *	module = &GetGlobalModule() )

Constructs a menu descriptor from the menu handle indicated in the hMenu parameter.

The menu descriptor can have zero or more pop-up menus in more than one functional group. The fg, eg, cg, of, wg, and hg parameters represent the functional groups identified by the TGroup enum. Calls the function ExtractGroups to extract the group counts based either on the separator items in the menu bar or on the group count parameters specified if there are no separators in the menu bar.

Definition at line 235 of file menudesc.cpp.

References ContainerGroup, EditGroup, ExtractGroups(), FileGroup, HelpGroup, ObjectGroup, and WindowGroup.

◆ ~TMenuDescr()

owl::TMenuDescr::~TMenuDescr ( )

Definition at line 255 of file menudesc.cpp.

Member Function Documentation

◆ ClearContainerGroupCount()

void owl::TMenuDescr::ClearContainerGroupCount ( )

Not implemented?

References owl::Module.

◆ ClearServerGroupCount()

void owl::TMenuDescr::ClearServerGroupCount ( )

Not implemented?

◆ ExtractGroups()

bool owl::TMenuDescr::ExtractGroups ( )

protected

Extracts the group counts from the loaded menu bar by counting the number of menus between separator items.

After the group counts are extracted, the separators are removed.

Definition at line 279 of file menudesc.cpp.

References owl::TMenu::GetMenuItemCount(), owl::TMenu::GetMenuState(), NumGroups, and owl::TMenu::RemoveMenu().

◆ GetGroupCount()

int owl::TMenuDescr::GetGroupCount ( int group ) const

inline

Gets the number of menus in a specified group within the menu bar.

There are a maximum of six functional groups as defined by the TGroup enum. These groups include FileGroup, EditGroup, ContainerGroup, ObjectGroup, WindowGroup, and HelpGroup.

Definition at line 303 of file menu.h.

◆ GetHandle()

HMENU owl::TMenuDescr::GetHandle ( ) const

inlinevirtual

Gets the handle to the menu, possibly causing any deferred menu acquisition to occur.

Reimplemented from owl::TMenu.

Definition at line 272 of file menu.h.

References owl::TMenu::GetHandle().

◆ GetId()

TResId owl::TMenuDescr::GetId ( ) const

inline

Gets the menu resource ID used to construct the menu descriptor.

Definition at line 293 of file menu.h.

◆ GetModule()

TModule * owl::TMenuDescr::GetModule ( ) const

inline

Returns a pointer to the module object.

Definition at line 279 of file menu.h.

◆ Merge() [1/2]

bool owl::TMenuDescr::Merge ( const TMenuDescr & srcMenuDescr )

Merges the functional groups of another menu descriptor into this menu descriptor.

Popups are DeepCopied and are then owned by this menu Group counts are merged too.

Definition at line 328 of file menudesc.cpp.

References owl::TMenu::DeepCopy(), owl::TMenu::DeleteMenu(), and NumGroups.

◆ Merge() [2/2]

bool owl::TMenuDescr::Merge	(	const TMenuDescr &	srcMenuDescr,
		TMenu &	dstMenu )

Merges the functional groups of this menu descriptor and another menu descriptor into an empty menu.

Popups are DeepCopied and are then owned by the destMenu.

Definition at line 361 of file menudesc.cpp.

References owl::TMenu::DeepCopy(), and NumGroups.

◆ operator=()

TMenuDescr & owl::TMenuDescr::operator= ( const TMenuDescr & original )

Definition at line 263 of file menudesc.cpp.

References NumGroups, and STATIC_CAST.

◆ SetModule()

void owl::TMenuDescr::SetModule ( TModule * module )

inline

Sets the default module object for this menu descriptor.

Definition at line 286 of file menu.h.

Friends And Related Symbol Documentation

◆ operator<<

opstream & operator<<	(	opstream &	os,
		const TMenuDescr &	m )

friend

◆ operator>>

ipstream & operator>>	(	ipstream &	is,
		TMenuDescr &	m )

friend

The documentation for this class was generated from the following files:

include/owl/menu.h
source/owlcore/menudesc.cpp

Public Types

Public Member Functions

Protected Member Functions

Friends

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ TGroup

Constructor & Destructor Documentation

◆ TMenuDescr() [1/5]

◆ TMenuDescr() [2/5]

◆ TMenuDescr() [3/5]

◆ TMenuDescr() [4/5]

◆ TMenuDescr() [5/5]

◆ ~TMenuDescr()

Member Function Documentation

◆ ClearContainerGroupCount()

◆ ClearServerGroupCount()

◆ ExtractGroups()

◆ GetGroupCount()

◆ GetHandle()

◆ GetId()

◆ GetModule()

◆ Merge() [1/2]

◆ Merge() [2/2]

◆ operator=()

◆ SetModule()

Friends And Related Symbol Documentation

◆ operator<<

◆ operator>>