MnuClass - Version 1.01

Author:		Mark Hall
E-mail:		markh@dircon.co.uk
Snail Mail:	7, Whitebridge Avenue
		Mitcham
		Surrey
		CR4 3FW
		England

Release List:	1.01	February 1996

This software is FREEWARE. No warranties/guarantees for its use are granted by the author. 

This software may be distributed freely, for no charge. Please ensure that this document accompanies the 
software.

I may, if my personal workload and time permit, fix any bugs reported to me and implement any new 
features requested.

I am a Developer and Trainer working in and around London, England.  Specialising in VFP, FP2.x, VB, 
Access and Delphi.

======================================================================

When I first started using VFP (early beta, Jan 1995) I was surprised by Microsofts' decision not to 
provide a more object oriented method for the creation of menu structures (like in VB).  As soon as I was 
really familiar with classes I set about creating a couple of wrapper classes for standard menu 
management requirements. I've been using them for about 6 months now and I find them a really simple 
way to create and manipulate menus. Here they are, with some basic documentation.  The major benefits 
gained by using these classes are :-

(1) You never have to use any of the VFP menu commands again (DEFINE PAD / DEFINE MENU / 
    DEFINE BAR).  

(2) Use familiar(ish) object oriented code to manipulate menu items e.g.
	oMenu.File.Save.Enabled(.T.)
	oMenu.File.Exit.Shortcut("ALT+X")
(3) Properties supported for menu options include :- Caption, Enabled, Message, Shortcut, Hotkey, 
    BarNo, Checked, Command.
(4) Complex menu manipulation becomes easy.  (enabling / disabling menu items, setting/removing 
    check marks, etc.)
(5) Things you thought were impossible (well, very, very tricky) in FoxPro :- Dynamically changing 
    menu item properties, such as, the caption, the message, the hotkey ....

File List - MnuCls11.zip
MENULIB.VCX		The class library itself
MENULIB.VCT		Part of the class library
MENUDEMO.PRG	A demonstration program
MENUPROC.PRG		Accompanying procedure library
ABOUTFRM.FRM	A simple form


Running The Demo
To run the demo, 
1) Unzip the archive (.ZIP) file into a new subdirectory
2) Start VFP
3) Set the default directory in VFP to point to the new directory (SET DEFAULT TO ...)
4) Start the demo program :- DO MENUDEMO
5) Clicking on the FILE menu, EXIT option will end the demo.


Using The Classes In Your Own Applications
Before the classes can be accessed, the class library must be attached to your application.  The following 
fragment of code is ideal :-

IF NOT "MENULIB" $ SET("CLASSLIB")	&& MENULIB must be in UPPER CASE
      SET CLASSLIB TO MENULIB ADDITIVE
ENDIF

Ensure that the MENULIB.VCX and MENULIB.VCT files are in the working directory.


The Classes
There are only two classes in the library :-

MENU - This is used as a container for the menu. You must have a menu object before you can add any 
menupad objects.  When an object is created from this class, a blank menu is displayed. Menupad objects 
can then be added to set up the rest of the menu. When the menu object is released, the previously active 
menu automatically re-appears.

Example :-
oMenu = CREATEOBJECT("menu")

Methods
HIDESYSTEMTOOLBARS
Description:	Will remove any system toolbars from the screen.
Example:	oMenu.HideSystemToolbars

SHOWHIDDENTOOLBARS
Description:	Will re-display and toolbars that were hidden previously by using the
HideSystemToolbars method.
Example:	oMenu.ShowHiddenToolbars

		
Properties
This class has no extra user-defined properties.




MENUPAD - All of the selectable menu item objects are of this class.  When you wish to add a new menu 
item, simple add an object of this class to the menu structure, using the ADDOBJECT method.

Example :-
To create a File option, at the left of the new menu bar.
oMenu.AddObject("File","menupad")

By default, the Caption for the new menu item will be the same as its name (i.e. File). It is possible to 
allocate a different name when creating the menu item, by passing the new name as a third parameter to 
addobject (Notice the \<, making the T the hotkey, not the E) e.g.
oMenu.AddObject("Edit","menupad","Edit \<Tools")

To add subitems to the FILE and EDIT menus, simply add more menupad objects, at the appropriate level 
e.g.
oMenu.File.AddObject("Open","menupad")
oMenu.File.AddObject("Close","menupad")
oMenu.File.AddObject("Spacer1","menupad","\-")
oMenu.File.AddObject("Exit","menupad","E\<xit")

You can add further levels.  I have not programmed any limits although, the VFP system may have some.  
e.g.
oMenu.File.Open.AddObject("Text","menupad","\<Text File")
oMenu.File.Open.AddObject("Picture","menupad","\<Picture File")

By now, the menu looks like this :-
(No pictures in text mode - sorry)
 

Using Properties
Property values for a menupad object are queried or set via a method, not directly via the property itself.  
The reason for this is because when you alter (for example) the caption of a menu item, some VFP code 
needs to run to actually change the prompt on the appropriate menu bar/pad.  Setting a property in VFP 
does not run code.

Example:- 
To test wether the TextFile option on the menu is enabled, use the enabled method, with no parameters :-
? oMenu.File.Open.Text.Enabled()

To disable the same menu item, send the new value as a parameter to the enabled method :-
oMenu.File.Open.Text.Enabled(.F.)
You will notice that the 'Text File' option will appear 'greyed out' when you next examine the menu.



List Of  MenuPad Properties

CAPTION 
Description:	The caption is the text displayed on the menu for the given menu object.  
Type:		Character.
Default:		By default the caption is the same as the name of the menupad object.
Info:		Use the \< characters to identify the HotKey character in the caption (as usual in Fox
		menus).  Set the caption to \- if you need a dividing line across the menu popup.

To change / set a caption
oMenu.Edit.Caption("\<Edit")

To query a caption
? oMenu.Edit.Caption()


MESSAGE 
Description:	The message is the text displayed on the VFP status bar when the menu object is 	
		highlighted.
Type:		Character.
Default:		By default the message is blank

To change / set a message
oMenu.Edit.Caption("\<Edit")

To query a message
? oMenu.Edit.Caption()


ENABLED
Description:	Determines if the menu object appears normally, or is 'greyed out' and not 		
		accessible.  
Type:		Logical.
Default:		By default enabled is true (.t.)

To change / set the enabled property
oMenu.File.Open.Enabled(.f.)

To query the enabled property
? oMenu.File.Open.Enabled()


CHECKED
Description:	Determines if a check mark (tick) appears next to the menu item
Type:		Logical.
Default:		By default checked is false (.f.)

To change / set the checked property
oMenu.File.Close.Checked(.t.)

To query the checked property
? oMenu.File.Close.Checked()


SHORTCUT
Description:	Defines the menu shortcut used to activate the menu option from the keyboard
Type:		Character.
Default:		By default no shortcut is defined.  It is empty
Info:		See the ON KEY LABEL command in the VFP help file for a list of valid 		
		menu shortcut key combinations. e.g.  "ALT+F", "CTRL+HOME", "CTRL+T".
		The entered text will also appear next to the item on the menu.

To change / set the shortcut property
oMenu.File.Exit.Shortcut("ALT+X")

To query the enabled property
? oMenu.File.Exit.Shortcut()


COMMAND
Description:	Used to define a single VFP command that is executed when the menu item is 	
	selected.  
Type:		Character.
Default:		By default no command is set.
Info:		No syntax checking is done when the command is set.  Only testing the menu
		will highlight any problems.  If a number of commands need to run when the 
		option is chosen, a small program will be needed and the command should be set 
		to "DO progname".  It is easiest if all such programs are placed in a procedure
		library and the SET PROCEDURE TO command used to give VFP access
		to this library. See the demo program for an example.

To change / set the enabled property
oMenu.File.Exit.Command("SET SYSMENU TO DEFAULT")

To query the enabled property
? oMenu.File.Exit.Command()


BARNO
Description:	Used mainly to make a menu item respond like one of the standard VFP menu items
Type:		Numeric
Default:		The barno is set to a system generated value when the menu item is created.
Info:		Only change the barno property if you wish to make a menu item respond like 
		one of the standard VFP menu items.  Knowledge of the barno for a specific menu
		item could be useful if you wish to use one of the standard VFP bar / menu
		management commands.

To change add a COPY item to the demo menu, and make it respond like the standard VFP EDIT - COPY 
option :-
oMenu.File.Edit.AddObject("Copy","menupad")		&& Add the menu item
oMenu.File.Edit.Copy.Barno(_MED_COPY)

This new copy option will behave like the usual VFP copy option. i.e. it may appear initially disabled, 
only becoming enabled when there is something to copy.  _MED_COPY is a system defined value.  The 
system bar number definitions for the entire VFP menu can be found in the VFP help file. Look for the 
'System menu names' topic.

To query the barno property
? oMenu.Edit.Copy.Barno()

In this case, you will receive a number, _MED_COPY is effectively a variable managed by the VFP 
system.


The End Of The Documentation
If you have any questions, comments, problems contact me, at the above addresses.  I prefer e-mail (it's 
easier and faster).

HopeYouLikeIt !

