MAINMENU, POPUPMENU and MENUITEM Objects +
Updated: Sep 17, 2009

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 a 13x13 pixel bitmap used to display .Checked = true

  Handle may be a .bmp resource (a string) or a hBitmap (dword).
  Example shown in the BITMAP Object .BMP property.

  If a .CheckedBmp is assigned, HotBasic automatically enables its use.
  Generally, 13x13 pixel bitmaps will display correctly.  The
  GetMenuCheckMarkDimensions API function retrieves the dimensions of the
  default bitmap size for menu items. 

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 a 13x13 pixel bitmap used to display .Checked = false 

  Handle may be a .bmp resource (a string) or a hBitmap (dword).
  Example shown in the BITMAP Object .BMP property.


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

  .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-2009 James J Keene PhD
Original Publication: Dec 14, 2003