4.3.10 Menus

Menus

People expected menus to be objectified in the last couple of versions of Visual FoxPro. However, it hasn't happened yet, and even the foundation classes don't offer real object menus but they're close.

Navigation Shortcut Menu

Class	_navmenu
Base class	Container
Class library	_table2.vcx
Parent class	_container
Sample	...\Samples\Vfp98\Solution\Ffc\datasort.scx
Dependencies	_base.vcx, _table2.h

The Navigation shortcut menu provides data navigation, manipulation, sorting and filtering functionality through a right-click. Figure 28 shows an example.

Figure 28. The Navigation shortcut menu.

To use this shortcut menu in your own forms, simply drop the object on the form and invoke it from the RightClick() event like so (substitute your menu object name for "oNavMenu"):

THISFORM.oNavMenu.DoMenu()

The Menu object checks to see whether a valid alias is selected. This is the only precondition that must be fulfilled. If no table is selected, the menu is not displayed.

You can easily add your own menu items by overwriting the SetMenu() method like so:

DoDefault()
THIS.oMenu.AddMenuSeparator

THIS.oMenu.AddMenuBar("My menu bar","oTHIS.MyMethod")

The Navigation shortcut menu uses a regular Shortcut Menu object. The object reference to this object is called "oMenu". You can simply call the AddMenuBar() method to add a new menu item (see below). The first parameter is the caption of the new item, while the second one is a valid Visual FoxPro expression that can be evaluated and executed.

Shortcut Menu Class

Class	_shortcutmenu
Base class	Custom
Class library	_menu.vcx
Parent class	_custom
Sample	...\Samples\Vfp98\Solution\Ffc\newmenu.scx
Dependencies	_base.vcx

The Shortcut Menu foundation class makes it easy to create and manage right-click menus. The object provides a number of methods you can use to add menu items and submenus to your right-click menu. You can simply drop the shortcut menu object on your form and invoke it from the form's RightClick() event like so:

THISFORM.oMenu.ShowMenu()

In this example, we activate a menu object called "oMenu". You can activate a menu from wherever you want.

Before you can actually use your menu, you have to define all the menu items and submenus. The following example shows how to add a couple of regular menu items as well as an entire submenu to your right-click menu. The following code is located in the SetMenu() method of the Shortcut Menu object:

LPARAMETERS loObject
DoDefault(loObject)

LOCAL loMenu2

loMenu2= THIS.NewMenu()

loMenu2.AddMenuBar("First Record","oTHISFORM.GoTop")

loMenu2.AddMenuBar("Previous Record","oTHISFORM.GoPrevious")

loMenu2.AddMenuBar("Next Record","oTHISFORM.GoNext")

loMenu2.AddMenuBar("Last Record","oTHISFORM.GoBottom")

THIS.AddMenuBar("Navigate",loMenu2)

THIS.AddMenuSeparator()

THIS.AddMenuBar("Save","oTHISFORM.Save")

THIS.AddMenuBar("Save & New","oTHISFORM.SaveNew")

THIS.AddMenuBar("Cancel","oTHISFORM.Cancel")

THIS.AddMenuSeparator()

THIS.AddMenuBar("Refresh","oTHISFORM.Refresh")

THIS.AddMenuBar("Auto Refresh","oTHISFORM.ToggleAutoRefresh";
,,, THISFORM.lAutoRefresh)

Figure 29 shows the resulting right-click menu. As you can see, the menu has a submenu that allows navigation. In the code above, we first create this menu by calling the NewMenu() method. This method returns an object reference to the new menu, which is basically another instance of the Shortcut Menu object. We then use the AddMenuBar() method to add new menu items. In the example above we pass two parameters. The first is the caption for the new menu item, and the second is a string that can be evaluated or executed by Visual FoxPro. So there has to be an object reference called "oTHISFORM". This object must have all methods we reference, such as GoTop(). The AddMenuBar() method can handle a number of parameters. See below for a more complete description of those parameters.

Once we've decorated the submenu with four menu items, we continue to create the regular menu by adding its first menu item, which links to the submenu we created previously. Again, we use the AddMenuBar() method to add this item, but this time the second parameter is an object reference to the submenu we created previously. Now you also know the reason why we created the submenu before we created the actual menu. Obviously we need an object reference to a valid submenu whenever we add the menu item that opens the submenu.

After creating the Navigate menu, we add a separator to add some organization to our menu. This can be done easily using the AddMenuSeparator() method. The next couple of items are added in the same manner as the ones before. Only the last one is special because it has a checkmark next to it. We added this checkmark by passing parameter 5 to the AddMenuBar() method. This parameter must be of type logical, and it determines whether the checkmark must be set or not. In my example, I use a property of the current form to decide whether or not I want the checkmark.

As you might have noticed (and as I have mentioned), the above example requires an object reference called "oTHISFORM". This is a reference we have to provide ourselves. A good place to do this is in the RightClick() event we already use to activate the menu. Here's the new code for this event:

PRIVATE oTHISFORM
oTHISFORM = THISFORM
THISFORM.oMenu.ShowMenu()

Note that I create the object reference as a private variable. This means that the reference is visible from now until the menu is deactivated.

Figure 29. A sample right-click menu.

Let's have a closer look at the methods of the Shortcut Menu object. You've already learned how to add menu items and separators as well as entire submenus. You've also seen how to activate the menu using the ShowMenu() method. Alternatively, we could use the ActivateMenu() method. In fact, ShowMenu() just calls ActivateMenu() without taking any further action. Once a menu is activated, it typically gets deactivated when the user picks one of the menu items or when he clicks outside the menu boundaries. However, you can also deactivate a menu programmatically by calling the DeactivateMenu() method.

Once you've specified items for a menu, you can activate and deactivate the menu as often as you want. The same items will remain in the menu. If you want to start over, you have to clear the menu items first, by calling the ClearMenu() method.

Let's have a closer look at the methods we've already used to add items to a menu. The simpler one was AddMenuSeparator(). So far, we've called it without parameters, but you can pass a single numeric parameter that specifies the position of the separator. So if you want to add a separator between items 2 and 3 of an existing menu, you can do it like so:

oMenu.AddMenuSeparator(3)

The AddMenuBar() method, on the other hand, is a little more complex and powerful. As you've seen, menu items can be links to submenus, they can be disabled, they can have bold fonts (which typically highlight a default option) or they can have checkmarks. Let's go through the parameters one by one.

The first parameter specifies the item caption. This is a simple string. Parameter 2 defines the action to be taken when the user selects the item. This can either be a string that is a valid FoxPro expression or an object reference to a submenu (see above). Parameter 3 is a little confusing at first. It specifies additional clauses for the menu item. This is a lot easier to understand than it first sounds. Keep in mind that the Shortcut Menu object internally has to use regular DEFINE BAR commands to build the menu. The clause parameter allows you to add whatever you want at the end of this command. This allows you to use all the features the DEFINE BAR command supports, and that cannot be accessed through the Shortcut Menu object interface. A good example would be font settings for menu items.

Parameter 4 represents the element number. This allows you to insert menu items at a certain position. It's basically the same as the first parameter of the AddMenuSeparator() method (see above).

We've already used parameter 5. It is a logical parameter that specifies whether the item should have a checkmark (.T.) or not (.F.). You can pass a straight .T. or .F., or you can pass a variable or a property to dynamically set this property. Note that those variables are evaluated only on instantiation, so if that variable or property changes its value later on, it will not be reevaluated. If you want to have a dynamic setting, you should specify this through parameter 3 (clause).

Parameters 6 and 7 are similar they're both logical. Parameter 6 specifies whether the item should be disabled, and parameter 7 specifies whether the parameter should use bold font. These two parameters follow the same rules as parameter 5 as far as dynamic settings go.