MAINMENU, POPUPMENU and MENUITEM Objects +
Updated: June 2, 2005

MAINMENU and MENUITEM define program menu entries.  MAINMENU (alias
POPUPMENU) objects cause a popup menu to appear listing selections.
MENUITEM's call program subroutines defined by the .OnClick property
and called when the menu item is selected by the user using mouse or
keyboard.

Usage is illustrated in hotmenu.bas, hotpopup.bas and in hotwin.bas.

Imagine that the entire menu tree is fully expanded.  Then, for each MAINMENU
item in the menu bar below the window title bar, define all of the MENUITEM's
that will appear in the popup menu when a MAINMENU item is selected.

Similar to FORM objects, the .Parent property of MENU objects is assigned to
the last defined FORM object.  The MENU object handle is MyObject.Menu and
may be viewed as the handle of the "container" of one or more MAINMENU's.

If MyObject is a FORM then its MAINMENU's are displayed as a form menu bar.
If not a form (LABEL, LISTBOX, etc), the MAINMENU is a popup menu which may be
displayed under program control or in response to an event (Please see
Statements > Miscellaneous > POPUP).

MyObject.Menu is automatically assigned as the parent of MAINMENU's defined
with CREATE or DIM.  Further, HotBasic automatically assigns each MAINMENU as
the parent of all MENUITEM's, until another MAINMENU or FORM object is defined.
These parent-child relationships are based on the order in which the objects
are defined.

Typical creation sequence for a menu bar:  (1) FORM, (2) MAINMENU, (3) one or
more MENUITEM's, (4) optionally repeat 2 and 3, (5) optionally repeat 1 to 4.

CREATE syntax is required to nest a MAINMENU as a child of a MAINMENU.

If secondary forms contain menus, the FORM .Show method may be required to 
ensure that the menu bar is drawn.

Alternate or popup menus can be created using a secondary form or almost any
FORM object as a "container" for a menu.  Even if the form container itself
is never displayed (.visible = false), its .menu property provides the handle
of the menu object.


PROPERTIES (Read/Write):
~~~~~~~~~~ ~~~~~~~~~~~~~
Caption    Menu text.  MyMenu.Caption = "File"

  As illustrated in hotmenu.bas, the string may have two parts separated
  by "\t" (for tab):

  (1) The & character may specify a "hotkey" letter to select an item. 
      The "alt" key can be used to set focus on a MAINMENU item.

  (2) "Hot&Babe\tCtrl-B" is the same as "Hot&Babe"+tab+"Ctrl-B".  Indeed,
      any string expression may be used to define .Caption.

  (3) "ctrl" characters may also be used to select menu items.

  String expressions can be used write .Caption, for multi-language support:

  Caption = mLIST.Item(i+j*n)

  where mLIST is a LIST containing menu captions i (0 to n-1) for
  n menu elements for language j (0 to [number of languages - 1]).

           Get menu text.  MyString = MyMenu.Caption

Checked    Checked state.  MyMenu.Checked = true  'or false
           IF MyMenu.Checked THEN  'read .Checked state

CheckedBmp Handle of bitmap used to display .Checked = true

  If a .CheckedBmp is assigned, HB automatically enables its use.

Default    Default state.  MyMenu.Default = true  'or false

Enabled    Enabled state.  MyMenu.Enabled = true  'or false

Grayed     Grayed state.  MyMenu.Grayed = true  'or false

  A Grayed menu item is both disabled and visually grayed.

Hilite     Hilite state.  MyMenu.Hilite = true  'or false

Parent     Menu parent.  MyMenu.Parent = MyForm.Menu

UncheckedBmp
           Handle of bitmap used to display .Checked = false 


PROPERTIES (Read Only Numeric):
~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~
Handle     Menu handle.  MyHandle = MyMenu.Handle

ID         Menu ID.  MyMenuID = MyMenu.ID


METHODS    Arguments & Comments
~~~~~~~    ~~~~~~~~~~~~~~~~~~~~
Separator  Inserts separator bar in menu.  MyMenu.Separator

  Starting with v3.9, .Separator requires a separately dimensioned
  MENUITEM.  The separator item is positioned only by the order of
  statements in source code.

  DIM mn13s As MENUITEM: mn13s.Separator  'mn13s is separator


EVENTS     Arguments & Comments
~~~~~~     ~~~~~~~~~~~~~~~~~~~~
OnClick    Specifies user-defined event handler subroutine.

           MyMenu.OnClick = DoThisItem  'sub (or label with RETURN)


###########
hotmenu.bas in HotToys and hotwin.bas show MENU coding.


+ Penthouse (registered) version

Copyright 2003-2005 James J Keene PhD
Original Publication: Dec 14, 2003
