The Main Menu

Introduction

A menu of a computer program is a list of actions that can be performed on that application. To be aware of these actions, the list must be presented to the user upon request.

A menu is considered a main menu, when it carries most of the actions the user can perform on a particular application. Such a menu is positioned on the top section of the form in which it is used. By design, although a main menu is positioned on a form, it actually belongs to the application.

A main menu is divided in categories of items and each category is represented by a word. Here is an example:

There is no strict rule on how a menu is organized. There are only suggestions. For example, actions that are related to file processing, such as creating a new file, opening an existing file, saving a file, printing the open file, or closing the file usually stay under a category called File. In the same way, actions related to viewing documents can be listed under a View menu.

To enhance the functionality of a graphical application, also to take advantage of the mouse and the keyboard, there are various types of menus. A main menu is divided in categories of items and each category is represented by a word. To use a menu, the user first clicks one of the words that displays on top. When clicked, the menu expands and displays a list of items that belong to that category.

1. Start Embarcadero RAD Studio
2. To create a new application, on the main menu, click File -> New -> VCL Forms Application - C++Builder

To create a main menu, you can use the TMainMenu class. The TMainMenu class derives from a class named TMenu where it inherits some of its early behaviors.

To visually create a main menu, use the TMainMenu control . To get it, on the Standard section of the Tool Palette, click the TMainMenu button and click on the form. It does not matter where you drop the MainMenu icon because it will not be seen what the program runs.

To programmatically create a main menu, create a pointer to TMainMenu. When initializing the variable, specify its owner which normally is the form on which it will display. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
    TMainMenu *mnuMain = new TMainMenu(this);
}
//---------------------------------------------------------------------------

If you visually add a TMainMenu object to a form, it automatically equipped the form with a main menu. If you programmatically create a main menu, you must also add it to the form, This also is done automatically by passing the form to the constructor of the TMainMenu variable.

1. In the Tool Palette, expand the Standard section if necessary. Click the TMainMenu control and click the form
2. While the main menu object is still selected on the form, in the Object Explorer, click Name and type mnuMain

A menu is actually made of menu items that represent the necessary actions. To visually create the list of items that belong to the mani menu:

• Double-click the TMainMenu1 object on the form
• Right-click the TMainMenu1 object on the form and click Menu Designer...

 This would display a window specially equipped for creating a main menu:

To add a menu item, click the selected item and specify its characteristics in the Object Inspector. To add a new item:

• Rright-click the Menu Designer and click Insert
• Press Ins

Then use the Object Inspector to define the new menu item.

A menu item is an object of type TMenuItem. Therefore, to programmatically create one, declare a variable of type TMenuItem and specify its owner. Ths owner can be the form that will display the menu. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
	TMainMenu *mnuMain = new TMainMenu(this);
	TMenuItem *mnuFile = new TMenuItem(this);
}
//---------------------------------------------------------------------------

The owner can also be the main menu. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
	TMainMenu *mnuMain = new TMainMenu(this);
	TMenuItem *mnuFile = new TMenuItem(mnuMain);
}
//---------------------------------------------------------------------------

IIn the same way, you can create as many menu items as necessary.

• On the form, right-click mnuMain and click Menu Designer

We mentioned that a VCL main menu is of type TMainMenu. This class gives you a lot of information about a menu. Sometimes it will not be enough, in which case you will need help from Win32. To give you information about a menu item, Microsoft Windows provides a structure named MENUINFO that is defined as follows:

typedef struct tagMENUINFO {
  DWORD   cbSize;
  DWORD   fMask;
  DWORD   dwStyle;
  UINT    cyMax;
  HBRUSH  hbrBack;
  DWORD   dwContextHelpID;
  ULONG_PTR  dwMenuData;
} MENUINFO, FAR *LPMENUINFO;
typedef MENUINFO CONST FAR *LPCMENUINFO;

To use this structure, declare a variable of type MENUINFO and initialize it with the size of the structure. This can be done as follows:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnMenuInformationClick(TObject *Sender)
{
    MENUINFO mnuInfo;
    mnuInfo.cbSize = sizeof(MENUINFO);
}
//---------------------------------------------------------------------------

To support menu items, Microsoft Windows provides a structure named MENUITEMINFO that is defined as follows:

typedef struct tagMENUITEMINFO {
  UINT    cbSize; 
  UINT    fMask; 
  UINT    fType; 
  UINT    fState; 
  UINT    wID; 
  HMENU   hSubMenu; 
  HBITMAP hbmpChecked; 
  HBITMAP hbmpUnchecked; 
  ULONG_PTR dwItemData; 
  LPTSTR  dwTypeData; 
  UINT    cch; 
  HBITMAP hbmpItem;
} MENUITEMINFO, *LPMENUITEMINFO;

To support menus, the Win32 library provides a handle named HMENU. To give you access to menus in the Win32 library, the TMenu class (the parent of TMenuItem) is equipped with a property named Handle that is of type HMENU:

__property HMENU__ * Handle = {read=GetHandle};

This is handle is very useful if you want to use one of the functions provided by the operating system to deal with menus.

The most fundamental visual aspect of a menu item is the text a user reads on it. If you are visually creating a menu, after displaying the Menu Designer, click its item on it and, in the Object Inspector, click Caption and type the desired string.

To programmatically specify the caption of a menu, access its Caption property and assign the desired string to it. Here is an exampe:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
    TMainMenu *mnuMain = new TMainMenu(this);
    TMenuItem *mnuFile = new TMenuItem(this);

    mnuFile->Caption = L"File";
}
//---------------------------------------------------------------------------

In the same way, to find out the string of a menu item, get the value of its Caption property.

Embarcadero RAD Studio greatly simplifies the creation of a menu by providing menu templates. A menu template is an already created menu that you can simply select and add to your application. To use one of these, right-click the Menu Designer window and click Insert From Template:

C++Builder provides already made menus for file, edit, and help processing:

To hold and identify the items on the main menu, the TMainMenu class is equipped with a property named b>Items, which is a collection. To support the ability to add a menu category to the main menu, the Items collection is equipped with the Add() method. Therefore, to add a menu category, call the Add() method of the Items collection and pass the TMenuItem object. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
	TMainMenu *mnuMain = new TMainMenu(this);
	TMenuItem *mnuFile = new TMenuItem(this);

	mnuFile->Caption = L"File";

	mnuMain->Items->Add(mnuFile);
}
//---------------------------------------------------------------------------

This would produce:

If you visually create your main menu, the Menu Designer takes care of many details behind the scenes. For example, each menu item is automatically added to its parent menu category. If you programmatically create your main menu, you must associate each menu item to its parent menu category.

After creating a menu item, you must add it to its parent. To support this operation, the TMenuItem class provides a method named Add that takes a TMenuItem as argument. This method is overloaded with two versions whose syntaxes are:

void __fastcall Add(Menus::TMenuItem * Item);
void __fastcall Add(Menus::TMenuItem * const * AItems, int AItems_Size);

The first version takes a TMenuItem object. Therefore, to specify that a menu item will be part of a menu category, call the Add() method and pass a TMenuItem object. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
	TMainMenu *mnuMain = new TMainMenu(this);
	TMenuItem *mnuFile = new TMenuItem(this);
	TMenuItem *mnuFileNew = new TMenuItem(this);

	mnuFile->Caption = L"File";
	mnuFileNew->Caption = L"New";

	mnuFile->Add(mnuFileNew);

	mnuMain->Items->Add(mnuFile);
}
//---------------------------------------------------------------------------

To support menu categories, the TMenuItem class is equipped with a property named Items, which is a collection.

1. In the Menu Designer, make sure an item is selected. Otherwise, click the dark blue box in the top-left section.
   In the Object Explorer, click Caption
2. Type File
3. Click Name and type mnuFile
4. In the Menu Designer, click the box under File
5. In the Object Inspector, click Caption and type New Property
6. Click Name and type mnuFileNewProperty
7. In the Menu Designer, click the box under New Property
8. In the Object Inspector, click Caption and type Exit
9. Click Name
10. Type mnuFileExit and press Enter
11. Click the Close button of the Menu Designer to close it
    
12. On the main menu, click File -> New -> Form - C++Builder
13. In the Object Inspector, click Name
14. Type RealEstateProperty and press Enter
15. To display the first form, in the top section, Unit1.cpp

If you create a menu as we have just done, to write code for one of the menu items, you can double-click the menu item. This would open the OnClick event of the menu item in the Code Editor and you can start writing the desired code for that item.

If you dynamically create a menu item, also define an event for it in the source file of its parent. In the event, pass an appropriate number of argument. Normally, the event of a menu item takes one argument, which is a pointer of type TObject. After defining the event, assign its name to the OnClick event of the menu item. Here is an example:

Header File:

//---------------------------------------------------------------------------

#ifndef Unit1H
#define Unit1H
//---------------------------------------------------------------------------
#include <Classes.hpp>
#include <Controls.hpp>
#include <StdCtrls.hpp>
#include <Forms.hpp>
//---------------------------------------------------------------------------
class TForm1 : public TForm
{
__published:	// IDE-managed Components

private:	// User declarations
	TMainMenu *mnuMain;
	TMenuItem *mnuFile;
	TMenuItem *mnuFileNew;

	void __fastcall FileNewMenuClicked(TObject *Sender);

public:		// User declarations
	__fastcall TForm1(TComponent* Owner);
};
//---------------------------------------------------------------------------
extern PACKAGE TForm1 *Form1;
//---------------------------------------------------------------------------
#endif

Source File:

//---------------------------------------------------------------------------

#include <vcl.h>
#pragma hdrstop

#include "Unit1.h"
//---------------------------------------------------------------------------
#pragma package(smart_init)
#pragma resource "*.dfm"
TForm1 *Form1;
//---------------------------------------------------------------------------
__fastcall TForm1::TForm1(TComponent* Owner)
	: TForm(Owner)
{
	mnuMain = new TMainMenu(this);
	mnuFile = new TMenuItem(mnuMain);
	mnuFileNew = new TMenuItem(mnuFile);
	mnuFile->Caption = L"&File";

	mnuFileNew->Caption = L"&New";
	mnuFileNew->OnClick = FileNewMenuClicked;
	mnuFile->Add(mnuFileNew);

	mnuMain->Items->Add(mnuFile);
}
//---------------------------------------------------------------------------
void __fastcall TForm1::FileNewMenuClicked(TObject *Sender)
{
	ShowMessage(L"a new file will be created");
}
//---------------------------------------------------------------------------

1. On the main menu, click File -> Use Unit...
2. In the Use Unit dialog box, click Unit2.cpp and click OK
3. On the form, double-click mnuMain
4. In the Menu Designer, click File and double-click New Property
5. Implement the event as follows:
   

   //---------------------------------------------------------------------------
   void __fastcall TForm1::mnuFileNewPropertyClick(TObject *Sender)
   {
   	RealEstateProperty->ShowModal();
   }
   //---------------------------------------------------------------------------

6. On the Menu Designer, double-click Exit
7. Close the Menu Designer
8. Implement the event as follows:
   

   //---------------------------------------------------------------------------
   void __fastcall TForm1::mnuFileExitClick(TObject *Sender)
   {
   	Close();
   }
   //---------------------------------------------------------------------------

9. To build and execute, on the main menu, click Run -> Run
10. On the main menu of the form, click File -> New Property
     
    
11. After viewing the form, close it
12. To close the main form, click File -> Exit