Grouping Menu Items

Menu Separators

As we will see in later sections, there are various ways you can make a menu look good and you have many options to configure menu items. One of the ways you can manage menu items is to group them.

A menu separator is a horizontal line among some menu items to visually divide them. Here is an example:

There are two reasons you would use a separator. You can use a separator just for aesthetic reasons, to make your menu look good. Another, more valuable reason, is to create groups of menu items and show their belonging together by showing a line separating one group from another.

To create a separator, set the caption of its menu item to a simple -. To do this visually, insert a new item in the Menu Designer and, in the Object Inspector, set its Caption to -. To do this programmatically, create a TMenuItem object and specify its caption as -. Here is an example:

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

	TMenuItem *mnuTools = new TMenuItem(mnuMain);
	TMenuItem *mnuToolsOptions = new TMenuItem(mnuTools);

	mnuFile->Caption = L"&File";
	mnuFileNew->Caption = L"&New";
	mnuFileNew->ShortCut = ShortCut(Word(L'N'), TShiftState() << ssCtrl);
	mnuFile->Add(mnuFileNew);

	mnuSeparator->Caption = L"-";
	mnuFile->Add(mnuSeparator);

	mnuFileOpen->Caption = L"&Open";
	mnuFileOpen->ShortCut = ShortCut(Word(L'O'), TShiftState() << ssCtrl);
	mnuFile->Add(mnuFileOpen);

	mnuMain->Items->Add(mnuFile);

	mnuTools->Caption = L"&Tools";
	mnuToolsOptions->Caption = L"&Options...";
	mnuTools->Add(mnuToolsOptions);

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

This would produce:

1. Start Embarcadero RAD Studio
2. To create a new application, on the main menu, click File -> New -> VCL Forms Application - C++Builder
3. In the Tool Palette, expand the Standard section if necessary. Click the TMainMenu control and click the form
4. While the main menu object is still selected on the form, in the Object Explorer, click Name and type mnuMain
5. On the form, right-click mnuMain and click Menu Designer

1. 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, type - and press Enter
9. Click Name
10. Type mnuSeparator1 and press Enter
11. In the Menu Designer, click the box under New Property
12. In the Object Inspector, click Caption and type E&xit
13. Click ShortCut, click the arrow of its combo box and select Ctrl+X
    
14. In the Menu Designer, click the box on the right side of File
15. In the Object Inspector, click Caption and type &View
16. Click Name
17. Type mnuView and press Enter
18. In the Menu Designer, click the box under View
19. In the Object Inspector, click Caption and type &Toolbars
20. Click Name
21. Type mnuViewToolbars and press Enter
22. In the Menu Designer, click the box under Toolbars
23. In the Object Inspector, click Caption and type - and press Enter
24. Click Name
25. Type mnuSeparator1 and press Enter
26. In the Menu Designer, click the box under the line separator
27. In the Object Inspector, click Caption and type &Status Bar
28. Click Name
29. Type mnuViewStatusBar and press Enter

If you have menu items that perform similar tasks, you can put them in a group, which you can do using line separators. Another option is to create the menu items in their own group. The group of menu items that are created as children of a parent menu is referred to as a sub-menu. Here is an example of a sub-menu in Microsoft Paint:

To visually create a sub-menu, in the Menu Designer:

• Click the menu that will use the sub-menu. Press and hold Ctrl, then press the right arrow key. This would add a new menu object to the right, waiting for you to configure it:

• Right-click the menu item that will hold the sub-items and click Create Submenu:

You can also create a sub-menu for a menu item that itself is a sub-menu.

To programmatically add a sub-menu to a menu item, call the Add() method on that item and pass the TMenuItem object of the sub-menu to it. Here are examples:

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

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

	mnuFileNewForm->Caption = L"Fo&rm";
	mnuFileNew->Add(mnuFileNewForm);
	mnuFileNewUnit->Caption = L"&Unit";
	mnuFileNew->Add(mnuFileNewUnit);
	mnuFileNewFrame->Caption = L"Fr&ame";
	mnuFileNew->Add(mnuFileNewFrame);

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

This would produce:

1. In the Menu Designer, click View and click Toolbars
2. Right-click Toolbars and click Create Submenu
3. While the new sub-menu is still selected, in the Object Inspector, click Caption
4. Type &Standard and press Enter
5. Click Name and type mnuViewToolbarsStandard
6. In the Menu Designer, click the box under Standard
7. In the Menu Designer, click Caption
8. Type  &Formatting and press Enter
9. Click Name, type mnuViewToolbarsFormatting and press Enter
10. Close the Menu Designer

Some applications are meant to display more than one form at the same time, or to optionally display and dismiss some forms some time to time. With this type of application, you may need a menu "witness" that can indicate whether the optional form is currently displaying or not. Some other applications may change their view some time to time. For these reasons and others, you can use the menu to assist the user with identifying an option that is currently available or not. You can do this through a check box or a radio button on a menu item.

To assist you with displaying a check box on a menu item, the TMenuItem class is equipped with a property named Checked. If you are visually creating a menu, to show a check mark on a menu item, in the Object Inspector, use its Checked field. The default value of this property is False, which means the menu item is not meant to display a check box. To show a check box, you can set this property to True. When the user has clicked the menu item, you can then programmatically change its value from true to false and vice-versa.

When the application is running, to put a check mark on it, the user can click the menu item. If an item is displaying a check mark and the user clicks it, the check mark disappears. In reality, this is not an automatic functionality and it doesn't happen at random: you must configure it.

1. On the form, click the panel you had previously added
2. In the Object Inspector, click Align and select alTop
3. Click Caption and type Standard
4. Click the check box of Checked
5. Click Name and type pnlToolbarStandard
6. In the Standard section of the Tool Palette, click Panel and click the form
7. In the Object Inspector, click Align and select alTop
8. In the Object Inspector, click Caption
9. Type Formatting and press Enter
10. Click the check box of Checked
11. Click Name and type pnlToolbarFormatting
12. On the form, double-click mnuMain
13. In the Menu Designer, click View, click Toolbars, and double-click Standard
14. Implement the event as follows:

    //---------------------------------------------------------------------------
    void __fastcall TForm1::mnuViewToolbarsStandardClick(TObject *Sender)
    {
    	// If the Standard is displaying, hide it, and vice-versa
    	if( pnlToolbarStandard->Visible == True )
    	{
    		pnlToolbarStandard->Visible = False;
    		mnuViewToolbarsStandard->Checked = False;
    	}
    	else
    	{
    		pnlToolbarStandard->Visible = True;
    		mnuViewToolbarsStandard->Checked = True;
    	}
    }
    //---------------------------------------------------------------------------
    

15. In the Menu Designer, double-click Formatting
16. Implement the event as follows:

    //---------------------------------------------------------------------------
    void __fastcall TForm1::mnuViewToolbarsFormattingClick(TObject *Sender)
    {
    	if( pnlToolbarFormatting->Visible == True )
    	{
    		pnlToolbarFormatting->Visible = False;
    		mnuViewToolbarsFormatting->Checked = False;
    	}
    	else
    	{
    		pnlToolbarFormatting->Visible = True;
    		mnuViewToolbarsFormatting->Checked = True;
    	}
    }
    //---------------------------------------------------------------------------

17. To execute the application, on the main menu, click Run -> Run

You can make two or more menu items behave like a mutual-exclusive group. When one of the menu items is selected, it displays a round button but the other items in the same group don't. In other words, at one time, only one of the menu items in the group is equipped with a radio button. This behavior is not automatic. There are some steps (really easy) you must follow to configure to get this behavior.

To support the behavior of a radio button, the TMenuItem class is equipped with a Boolean property named RadioItem. Its default value is False. Therefore, to apply a scenario of radio buttons on a group of menu items, set each RadioItem property to True. To put a radio mark of a menu item, set its Checked property to True. When you do this, the other menu items of the same group lose their radio mark.

1. In the Menu Designer, click the box on the right side of View
2. In the Object Inspector, click Caption and type &Show
3. Click Name and type mnuShow and press
4. In the Menu Designer, click the box under Show
5. In the Object Inspector, click Caption
6. Type &All and press Enter
7. Click the check box of Checked
8. Click Name and type mnuShowAll
9. Click the check box of RadioItem
10. In the Menu Designer, click the box under All
11. In the Object Inspector, click Caption
12. Type &Apartments and press Enter
13. Click Name and type mnuShowApartments
14. Click the check box of RadioItem
15. In the Menu Designer, click the box under Apartments
16. In the Object Inspector, click Caption
17. Type &Townhouses and press Enter
18. Click Name and type mnuShowTownhouses
19. Click the check box of RadioItem
20. In the Menu Designer, click the box under Townhouses
21. Type &Single Families and press Enter
22. Click Name and type mnuShowSingleFamilies
23. Click the check box of RadioItem
24. Double-click All
25. Implement the event as follows:

    //---------------------------------------------------------------------------
    void __fastcall TForm1::mnuShowAllClick(TObject *Sender)
    {
    	mnuShowAll->Checked = True;
    }
    //---------------------------------------------------------------------------

26. In the Menu Designer, double-click Apartments
27. Implement the event as follows:

    //---------------------------------------------------------------------------
    void __fastcall TForm1::mnuShowApartmentsClick(TObject *Sender)
    {
    	mnuShowApartments->Checked = True;
    }
    //---------------------------------------------------------------------------

28. In the Menu Designer, double-click Townhouses
29. Implement the event as follows:

    //---------------------------------------------------------------------------
    void __fastcall TForm1::mnuShowTownhousesClick(TObject *Sender)
    {
    	mnuShowTownhouses->Checked = True;
    }
    //---------------------------------------------------------------------------

30. In the Menu Designer, double-click Single Families
31. Close the Menu Designer
32. Implement the event as follows:

    //---------------------------------------------------------------------------
    void __fastcall TForm1::mnuShowSingleFamiliesClick(TObject *Sender)
    {
    	mnuShowSingleFamilies->Checked;
    }
    //---------------------------------------------------------------------------

33. To test the application, press F9
34. Close the form and return to your programming environment

A main menu can be recognized by the number of menu categories it contains. To get you this information, the Items property of the TMenu class is equipped with an integer property named Count. Here is an example of using it:

//---------------------------------------------------------------------------
void __fastcall TForm1::mnuCountClick(TObject *Sender)
{
	ShowMessage(L"Number of Menu Items: " + String(mnuMain->Items->Count));
}
//---------------------------------------------------------------------------

After creating a few menu categories or a few menu items, you may find out that an item is missing in the sequence. You can then create a new menu before one of your choice:

• In the Menu Designer, click the menu item that will come after the new one and press Ins
• To create a new menu category that would precede an existing one, in the menu designer, right-click a menu item and click Insert. A placeholder for a new menu category would be added with a default caption and a default name. You can then customize it as you see fit

To assist you with programmatically inserting a new menu, the TMenuItem class is equipped with a method named Insert. Its syntax is:

void __fastcall Insert(int Index, Menus::TMenuItem * Item);

This first argument is an index that specifies the position that the new menu will occupy among the child items. The first position is 0. The second is 1, and so on. Here is an example:

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

	mnuFile->Caption = L"&File";

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

	mnuFileSave->Caption = L"&Save";
	mnuFile->Add(mnuFileSave);

	mnuFileOpen->Caption = L"&Open";
	mnuFile->Insert(1, mnuFileOpen);

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

This would produce:

You can also use the TMenuItem::Insert() method to create new menu items.

You can visually copy a main menu or a popup menu from one (RAD Studio) application to another. To do this, on the form of the application that holds the desired main menu:

• Click the TMainMenu object to select it:
  • Press Ctrl + C
  • On the main menu, click Edit -> Copy
• Right-click the TMainMenu object, position the mouse on Edit, and click Copy

In the other application, click the form that will use the menu:

• Press Ctrl + V
• On the main menu, click Edit -> Paste
• Right-click the form, position the mouse on Edit, and click Paste

While designing your menu, you may find out that a menu category or a menu item is in the wrong position. You can then move the menu category or the menu item.

To visually move a menu category, in the Menu Designer, click and hold the mouse on the menu category. Drag left or right in the desired direction. While moving the mouse, the cursor would display a small white rectangle:

When the mouse gets to the item that will succeed the new one, release the mouse. When you move a menu category, it moves with all its menu items.

To move a menu item, in the Menu Designer, click and hold the mouse on the item. Drag up or down. While moving the mouse, the cursor would display a small white rectangle:

When the mouse gets to the item that will succeed the new one, release the mouse.

A menu item is said to be disabled if the user can see it but cannot use it. The caption of such a menu appears gray. Here are examples:

When a menu item is disabled, the user can position the mouse on it and click but nothing would happen. This indicates that the action of that menu item is not available at that time. The reverse to a disabled menu item is that it is enabled. The user cannot directly enable or disable a menu. You as the application developer decides when (and why) the item would be enabled or disabled.

To support the ability to enable or to disable a menu item, the TMenuItem class is equipped with a Boolean property named Enabled. By default, a new menu item you have just created is enabled. This is because the default value of this property is true.

To visually enable or disable a menu item, in the Menu Designer, click the menu item. In the Object Inspector, clear the Enabled field to set it to False. To programmatically enable or re-enable it, you can set the value to True. In the same way, to find out the enabled status of a menu item, you can check the value of its Enabled property.

A menu is said to be hidden if it is available behind the scenes but the user cannot see. Since the user cannot see it, he or she cannot use it. The reverse to a hidden menu item is that it is shown to the user. The user cannot directly hide or show a menu item. You as the application developer create a menu item and then decides when, how, and where (and why) the item would be hidden or shown.

To support the ability to enable or to disable a menu item, the TMenuItem class is equipped with a Boolean property named Visible. After you have just created a new menu, by default, it is made visible to the user. This is because the default value of the Visible property is set to True. To hide a menu item, you can set its Visible property to false. To show or to reveal it, you can set the value to True. In the same way, to find out whether a menu item is currently displaying, you can check the status of its Visible property.

Instead of disabling or hiding a menu you don't want use anymore, you can simply delete it. If you do this, you cannot programmatically refer to it anymore, unless you re-create it.

To visually delete a menu category or a menu item:

• In the Menu Designer, click the menu category and press Delete
• In the Menu Designer, click the menu category to give it focus
  • Right-click the selected menu category click Delete
  • On the main menu, click Edit -> Cut
  • On the main menu, click Edit -> Delete

In the same way, you can keep deleting one item at a time.

To assist you with programmatically deleting a menu item, the TMenuItem class is equipped with a method named Remove. Its syntax is:

void __fastcall Remove(Menus::TMenuItem * Item);

To call this method, use the menu item that is the parent and pass the menu item as argument. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnDeleteMenuItemClick(TObject *Sender)
{
    mnuShow->Remove(mnuShowTownhouses);
}
//---------------------------------------------------------------------------

To visually delete the whole main menu or a popup menu, on the form

• Click the TMainMenu object or the TPopupMenu object and press Delete
• Right-click the TMainMenu object or the TPopupMenu object, position the mouse on Edit, and click Cut
• Right-click the TMainMenu object or the TPopupMenu object, position the mouse on Edit, and click Delete
• Click the TMainMenu object or the TPopupMenu object to select it:
  • On the main menu, click Edit -> Cut
  • On the main menu, click Edit -> Delete

To help you delete all items, the TMenuItem class is equipped with a method named Clear. Its syntax is:

void __fastcall Clear(void);

When called, this method will get rid of all the child menu items of the menu item. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnDeleteMenuItemClick(TObject *Sender)
{
    mnuShow->Clear();
}
//---------------------------------------------------------------------------

1. On the main menu, click File -> Close All
2. When asked whether you want to save, click No