OWLNext    7.0
Borland's Object Windows Library for the modern age
Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | Static Protected Member Functions | List of all members
owl::TMenu Class Reference
Menus

The TMenu class encapsulates window menus. More...

#include <owl/menu.h>

Inheritance diagram for owl::TMenu:
owl::TMenuDescr owl::TPopupMenu owl::TSystemMenu

Public Member Functions

 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.
 
virtual HMENU GetHandle () const
 Returns the handle to the menu.
 
 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.
 
HMENU encapsulated functions
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.
 
Encapsulation of new functionality introduced with Win95
uint GetDefaultItem (bool getPos, uint flags) const
 
bool SetDefaultItem (uint posOrId, bool isPos)
 
bool CheckRadioItem (uint first, uint last, uint check, uint flags)
 
MENUITEMINFO related API
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 menu functions
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.
 

Static Public Member Functions

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

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

The TMenu class encapsulates window menus.

You can use TMenu member functions to construct, modify, query, and create menu objects. You can also use TMenu to add bitmaps to your menu or to specify if a menu item is checked or unchecked. TMenu includes two versions of a helper function, DeepCopy , designed to make copies of menus and insert them at a specified position on the menu bar. See the ObjectWindows Programmer's Guide for information about how to create menu objects.

Definition at line 77 of file menu.h.

Constructor & Destructor Documentation

◆ TMenu() [1/6]

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.

Definition at line 67 of file menu.cpp.

References CheckValid(), and WARNX.

◆ TMenu() [2/6]

owl::TMenu::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.

Definition at line 80 of file menu.cpp.

References CheckValid(), DeepCopy(), and WARNX.

◆ TMenu() [3/6]

owl::TMenu::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.

Definition at line 94 of file menu.cpp.

◆ TMenu() [4/6]

owl::TMenu::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.

Definition at line 106 of file menu.cpp.

References CheckValid(), PRECONDITION, and WARNX.

◆ TMenu() [5/6]

owl::TMenu::TMenu ( const void * menuTemplate)

Creates a menu object from a menu template in memory.

This constructor is not available under Presentation Manager.

Definition at line 120 of file menu.cpp.

References CheckValid(), PRECONDITION, and WARNX.

◆ TMenu() [6/6]

owl::TMenu::TMenu ( HINSTANCE instance,
TResId resId )

Creates a menu object from a specified resource ID.

Definition at line 132 of file menu.cpp.

References CheckValid(), PRECONDITION, and WARNX.

◆ ~TMenu()

owl::TMenu::~TMenu ( )
virtual

Definition at line 160 of file menu.cpp.

Member Function Documentation

◆ AppendMenu() [1/3]

bool owl::TMenu::AppendMenu ( uint flags,
TMenuItem newItem,
const TBitmap & newBmp )
inline

Adds a bitmap menu item at the end of the menu.

See TMenu::GetMenuState for a description of the flag values that specify the attributes of the menu; for example, menu item is checked, menu item is disabled, and so on.

Definition at line 352 of file menu.h.

References PRECONDITION.

◆ AppendMenu() [2/3]

bool owl::TMenu::AppendMenu ( uint flags,
TMenuItem newItem,
const tstring & newStr )
inline

Definition at line 100 of file menu.h.

References AppendMenu().

◆ AppendMenu() [3/3]

bool owl::TMenu::AppendMenu ( uint flags,
TMenuItem newItem = static_cast<unsigned int>(-1),
LPCTSTR newStr = nullptr )
inline

Adds a text menu item to the end of the menu.

See TMenu::GetMenuState for a description of the flag values that specify the attributes of the menu, for example, menu item is checked, menu item is a a bitmap, and so on.

Definition at line 342 of file menu.h.

References PRECONDITION.

◆ CheckMenuItem()

bool owl::TMenu::CheckMenuItem ( uint item,
uint check )
inline

Checks or unchecks the menu item.

By combining flags with the bitwise OR operator (|) check specifies both the position of item (MF_BYCOMMAND, MF_BYPOSITION) and whether item is to be checked (MF_CHECKED) or unchecked (MF_UNCHECKED).

Definition at line 364 of file menu.h.

References PRECONDITION.

◆ CheckRadioItem()

bool owl::TMenu::CheckRadioItem ( uint first,
uint last,
uint check,
uint flags )

Definition at line 299 of file menu.cpp.

References PRECONDITION.

◆ CheckValid()

void owl::TMenu::CheckValid ( uint redId = IDS_MENUFAILURE)

Throws a TXMenu exception if the menu object is invalid.

Definition at line 248 of file menu.cpp.

References owl::TXMenu::Raise().

◆ DeepCopy() [1/2]

void owl::TMenu::DeepCopy ( TMenu & dst,
const TMenu & src,
int srcOffset = 0,
int itemCount = -1 )
staticprotected

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 338 of file menu.cpp.

References DeepCopy().

◆ DeepCopy() [2/2]

void owl::TMenu::DeepCopy ( TMenu & dst,
int dstOffset,
const TMenu & src,
int srcOffset = 0,
int itemCount = -1 )
staticprotected

Copies menu items from the src menu to the dst menu.

If itemCount is negative (the default), all of the source menu items from srcOffset onward are copied.

Note
The function isn't doing a truly deep copy. Only a recursive shallow copy is made of the menu items and submenus. In particular, a deep copy of bitmaps is not made. The function only copies the handles as part of the menu item structure, which means that bitmaps are in effect shared between the src and dst menus after the copy.

Definition at line 354 of file menu.cpp.

References _T, COUNTOF, DeepCopy(), owl::NoAutoDelete, PRECONDITION, and WARNX.

◆ DeleteMenu()

bool owl::TMenu::DeleteMenu ( uint item,
uint flags )
inline

Removes the menu item (item) from the menu or deletes the menu item if it's a pop-up menu.

flags is used to identify the position of the menu item by its relative position in the menu (MF_BYPOSITION) or by referencing the handle to the top-level menu (MF_BYCOMMAND).

Definition at line 375 of file menu.h.

References PRECONDITION.

◆ DrawItem()

void owl::TMenu::DrawItem ( DRAWITEMSTRUCT & drawItem)
virtual

DrawItem responds to a message forwarded to a drawable control by TWindow when the control needs to be drawn.

Definition at line 271 of file menu.cpp.

◆ EnableMenuItem()

bool owl::TMenu::EnableMenuItem ( uint item,
uint enable )
inline

Enables, disables, or grays the menu item specified in the item parameter.

If a menu item is enabled (the default state), it can be selected and used as usual. If a menu item is grayed, it appears in grayed text and cannot be selected by the user. If a menu item is disabled, it is not displayed. Returns true if successful.

Definition at line 387 of file menu.h.

References PRECONDITION.

◆ GetDefaultItem()

uint owl::TMenu::GetDefaultItem ( bool getPos,
uint flags ) const

Definition at line 279 of file menu.cpp.

References PRECONDITION.

◆ GetHandle()

HMENU owl::TMenu::GetHandle ( ) const
inlinevirtual

Returns the handle to the menu.

Reimplemented in owl::TMenuDescr.

Definition at line 310 of file menu.h.

◆ GetMenuCheckMarkDimensions() [1/2]

TSize owl::TMenu::GetMenuCheckMarkDimensions ( )
inlinestatic

Return the dimensions of the check mark bitmaps.

Definition at line 536 of file menu.h.

References GetMenuCheckMarkDimensions().

◆ GetMenuCheckMarkDimensions() [2/2]

bool owl::TMenu::GetMenuCheckMarkDimensions ( TSize & size)
inlinestatic

Gets the size of the bitmap used to display the default check mark on checked menu items.

Always returns true. The size reference stores the dimensions of the checkmark bitmaps.

Definition at line 527 of file menu.h.

References GetMenuCheckMarkDimensions().

◆ GetMenuItemCount()

uint owl::TMenu::GetMenuItemCount ( ) const
inline

Returns the number of items in a top-level or pop-up menu.

Definition at line 395 of file menu.h.

References PRECONDITION.

◆ GetMenuItemID()

uint owl::TMenu::GetMenuItemID ( int pos) const

Returns the ID of the menu item at the position specified by posItem.

If it's a regular menu item just returns its id. If the menu is a pop-up menu, first attempt to retrieve a user-specified Id via the MENUITEMINFO structure. Otherwise, use the Id of first menuitem minus 1.

Definition at line 174 of file menu.cpp.

References GetMenuItemID(), GetSubMenu(), and TRACEX.

◆ GetMenuItemInfo()

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

Definition at line 309 of file menu.cpp.

References PRECONDITION.

◆ GetMenuState()

uint owl::TMenu::GetMenuState ( uint item,
uint flags ) const
inline

Returns the menu flags for the menu item specified by item.

flags specifies how the item is interpreted, and is one of the following values:

  • MF_BYCOMMAND Interpret item as a menu command ID. Default it neither
  • MF_BYCOMMAND nor MF_BYPOSITION is specified.
  • MF_BYPOSITION Interpret item as the zero-base relative postion of the menu item within the menu.

If item is found, and is a pop-up menu, the low-order byte of the return value contains the flags associated with item, and the high-order byte contains the number of items in the pop-up menu. If itemis not a pop-up menu, the return value specifies a combination of these flags:

  • MF_BITMAP Menu item is a a bitmap.
  • MF_CHECKED Menu item is checked (pop-up menus only).
  • MF_DISABLED Menu item is disabled.
  • MF_ENABLED Menu item is enabled.
    Note
    this constant's value is 0.
  • MF_GRAYED Menu item is disabled and grayed.
  • MF_MENUBARBREAK Same as MF_MENUBREAK except pop-up menu columns are separated by a vertical dividing line.
  • MF_MENUBREAK Static menu items are placed on a new line, pop-up menu items are placed in a new column, without separating columns.
  • MF_SEPARATOR A horizontal dividing line is drawn, which cannot be enabled, checked, grayed, or highlighted. Both item and flags are ingonred.
  • MF_UNCHECKED Menu item check mark is removed (default).
    Note
    this constant value is 0.
    Returns -1 if item doesn't exist.

Definition at line 430 of file menu.h.

References PRECONDITION.

◆ GetMenuString() [1/2]

int owl::TMenu::GetMenuString ( uint item,
TCHAR * str,
int count,
uint flags ) const
inline

Returns the label (str) of the menu item (item).

Definition at line 438 of file menu.h.

References PRECONDITION.

◆ GetMenuString() [2/2]

tstring owl::TMenu::GetMenuString ( uint item,
uint flags ) const

String-aware overload.

Definition at line 235 of file menu.cpp.

References owl::CopyText(), GetHandle(), and GetMenuString().

◆ GetSubMenu()

HMENU owl::TMenu::GetSubMenu ( int posItem) const
inline

Returns the handle of the menu specified by posItem.

Definition at line 446 of file menu.h.

References PRECONDITION.

◆ InsertMenu() [1/3]

bool owl::TMenu::InsertMenu ( uint item,
uint flags,
TMenuItem newItem,
const TBitmap & newBmp )
inline

Adds a bitmap menu item after the menu item specified in item.

The flags parameter contains either the MF_BYCOMMAND or MF_BYPOSITION values that indicate how to interpret the item parameter. If MF_BYCOMMAND, item is a command ID; if MF_BYPOSITION, item holds a relative position within the menu.

Definition at line 469 of file menu.h.

◆ InsertMenu() [2/3]

bool owl::TMenu::InsertMenu ( uint item,
uint flags,
TMenuItem newItem,
const tstring & newStr )
inline

Definition at line 112 of file menu.h.

References InsertMenu().

◆ InsertMenu() [3/3]

bool owl::TMenu::InsertMenu ( uint item,
uint flags,
TMenuItem newItem = -1,
LPCTSTR newStr = nullptr )
inline

Inserts a new text menu item or pop-up menu into the menu after the menu item specified in item.

The flagsparameter contains either the MF_BYCOMMAND or MF_BYPOSITION values that indicate how to interpret the item parameter. If MF_BYCOMMAND, item is a command ID; if MF_BYPOSITION, item holds a relative position within the menu.

Definition at line 458 of file menu.h.

References PRECONDITION.

◆ InsertMenuItem()

bool owl::TMenu::InsertMenuItem ( uint posOrId,
bool isPos,
TMenuItemInfo & mi )

Definition at line 329 of file menu.cpp.

References PRECONDITION.

◆ IsOK()

bool owl::TMenu::IsOK ( ) const
inline

Returns true if the menu has a valid handle.

Definition at line 333 of file menu.h.

References GetHandle().

◆ MeasureItem()

void owl::TMenu::MeasureItem ( MEASUREITEMSTRUCT & measureItem)
virtual

MeasureItem is used by owner-drawn controls to store the dimensions of the specified item.

Definition at line 262 of file menu.cpp.

◆ ModifyMenu() [1/3]

bool owl::TMenu::ModifyMenu ( uint item,
uint flags,
TMenuItem newItem,
const TBitmap & newBmp )
inline

Changes an existing menu item into a bitmap.

The flags parameter contains either the MF_BYCOMMAND or MF_BYPOSITION values that indicate how to interpret the item parameter. If MF_BYCOMMAND, item is a command ID; if MF_BYPOSITION, item holds a relative position within the menu.

Definition at line 491 of file menu.h.

References PRECONDITION.

◆ ModifyMenu() [2/3]

bool owl::TMenu::ModifyMenu ( uint item,
uint flags,
TMenuItem newItem,
const tstring & newStr )
inline

Definition at line 115 of file menu.h.

References ModifyMenu().

◆ ModifyMenu() [3/3]

bool owl::TMenu::ModifyMenu ( uint item,
uint flags,
TMenuItem newItem = -1,
LPCTSTR newStr = nullptr )
inline

Changes an existing menu item from the item specified in item to newItem.

The flags parameter contains either the MF_BYCOMMAND or MF_BYPOSITION values that indicate how to interpret the item parameter. If MF_BYCOMMAND, item is a command ID; if MF_BYPOSITION, item holds a relative position within the menu.

Definition at line 480 of file menu.h.

References PRECONDITION.

◆ operator HMENU()

owl::TMenu::operator HMENU ( ) const
inline

Returns the menu's handle.

Definition at line 326 of file menu.h.

◆ operator TMenuItem()

owl::TMenu::operator TMenuItem ( ) const
inline

Returns the menu's handle.

This function provides compatibility with functions that require a TMenuItem menu parameter.

Definition at line 319 of file menu.h.

◆ operator=()

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

Copies an existing menu onto this menu, using DeepCopy.

Definition at line 145 of file menu.cpp.

References DeepCopy(), DeleteMenu(), and GetMenuItemCount().

◆ RemoveMenu()

bool owl::TMenu::RemoveMenu ( uint item,
uint flags )
inline

Removes the menu item from the menu but does not delete it if it is a submenu.

Definition at line 500 of file menu.h.

References PRECONDITION.

◆ SetDefaultItem()

bool owl::TMenu::SetDefaultItem ( uint posOrId,
bool isPos )

Definition at line 289 of file menu.cpp.

References PRECONDITION.

◆ SetMenuItemBitmaps()

bool owl::TMenu::SetMenuItemBitmaps ( uint item,
uint flags,
const TBitmap * bmpUnchecked = nullptr,
const TBitmap * bmpChecked = nullptr )
inline

Specifies the bitmap to be displayed when the menu item is checked and unchecked.

item indicates the menu item to be associated with the bitmap. flags indicates how the size parameter is interpreted (whether by MF_BYPOSITION or by MF_BYCOMMAND). GetMenuCheckMarkDimensions gets the size of the bitmap.

Definition at line 511 of file menu.h.

References PRECONDITION.

◆ SetMenuItemInfo()

bool owl::TMenu::SetMenuItemInfo ( uint posOrId,
bool isPos,
TMenuItemInfo & mi )

Definition at line 319 of file menu.cpp.

References PRECONDITION.

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