Copyright: Visual Help Copyright® 1993 Firas Bushnaq


TSysMenu Component

Properties

Methods

Description

The system menu component provides an easy way to insert, append or manipulate new item entries into a form's system menu.


Properties

ParentHandle

NewMenuItem

MenuPos

MenuItemType

MenuBar

MenuChecked

MenuEnabled

NewItemId

Inserted


ParentHandle Property

Description

The parenthandle property is the handle of the form whose system menu is to be manipulated.

Example:

sysmenu1.parenthandle := form1.handle;
sysmenu1.NewMenuItem := 'Always on Top';
sysmenu1.MenuPos := 0;


NewMenuItem Property

Description

This is a string property which indicates the caption to display for the item to be added to the system menu.

Example:

sysmenu1.NewMenuItem := 'Always on Top';


MenuPos Property

Description

The MenuPos property indicates where in the system menu to insert the new item.  A value of -1 tells the component to append the item at the end of the menu.  When the InstallMenuItem method is called, this property will be set to the actual position in the menu where the item is appended.

Note:

When adding multiple items to the menu, you must keep track of the id and position of each item added since the MenuPos property relates only to the last item added.

Example:

Sysmenu1.NewMenuItem := 'Always On Top';
Sysmenu1.MenuPos := -1; {append to end of menu}
Sysmenu1.InstallMenuItem;
{the MenuPos property can be queried here to determine its actual position)


MenuItemType Property

Description

The menuitemtype property indicates whether the newmenuitem property is a separator or a string.  The property can be one of the following values:

     mtSeparator

     mtString

If this property is set to mtSeparator, the NewMenuItem property is ignored since no caption is being added to the menu.  The default is mtString.

Example:

sysmenu1.parenthandle := form1.handle;
sysmenu1.MenuPos := -1 {append}
sysmenu1.MenuItemType := mtSeparator;
sysmenu1.Installmenuitem;
sysmenu1.NewMenuItem := 'Always on Top';
sysmenu1.MenuItemType := mtString;
sysmenu1.InstallMenuitem;

The above example appends a separator bar then the item 'Always on Top' to form1's system menu.


MenuBar Property

Description

The Menubar property indicates what type of separator bar is being added to the system menu.  This property is ignored if the MenuItemType is mtString.  This property can take on of the following values:

     mtNone

     mtMenuBarBreak

     mtMenuBreak

The default value is mtNone.

Example:

sysmenu1.parenthandle := form1.handle;
sysmenu1.MenuItemtype := mtSeparator;
sysmenu1.MenuBar := mtMenuBreak;
sysmenu1.MenuPos := -1;
sysmenu1.installmenuitem;
sysmenu1.MenuItemtype := mtString;
sysmenu1.NewMenuItem := 'Always on Top';
sysmenu1.Installmenuitem;

The above example appends a horizontal separator bar and an option 'Always on Top' to the system menu of form1.


MenuChecked Property

Description

The menuchecked property indicates whether the NewMenuItem being added should be checked or not.  This property takes one of the following values:

         mtUnchecked

         mtChecked

The default for this property is mtUnchecked.

Example:

sysmenu1.parenthandle := form1.handle;
sysmenu1.MenuPos := -1 {append}
sysmenu1.MenuItemType := mtSeparator;
sysmenu1.Installmenuitem;
sysmenu1.NewMenuItem := 'Always on Top';
sysmenu1.MenuItemType := mtString;
sysmenu1.Menuchecked := mtChecked;
sysmenu1.InstallMenuitem;
form1.FormStyle := fsStayOnTop;

The above example appends a separator bar then the item 'Always on Top' to form1's system menu.  It then sets the form's FormStyle property to stay on top.


MenuEnabled Property

Description

The Menuenabled property indicates whether the NewMenuItem being added is to be enabled or disabled.  The property can take one of the following values.

          mtEnabled

          mtDisabled

          mtGrayed

The default is mtEnabled.

Example

sysmenu1.parenthandle := form1.handle;
sysmenu1.MenuPos := -1 {append}
sysmenu1.MenuItemType := mtSeparator;
sysmenu1.Installmenuitem;
sysmenu1.NewMenuItem := 'Other Options...';
sysmenu1.MenuItemType := mtString;
sysmenu1.Menuenabled := mtDisabled;
sysmenu1.InstallMenuitem;

The above example appends a separator bar then the item 'Other Options..' to form1's system menu.  The item 'Other Options...' is disabled.


NewItemId Property

Description

This is a read only property which indicates the item id of the most recently added item.  Each time you call the InstallMenuitem method, the component finds a unique id for the newly added item and sets this property to that value.  If you are adding multiple items to the system menu, you need to query this property after each addition and track the id's in your program's code.  Remember that the value of this property at any time is the id of the last item added.

Example:

var
     id : array [0..2] of integer;
begin
     sysmenu1.parenthandle := form1.handle;
     sysmenu1.newmenuitem := 'option one';
     sysmenu1.menupos := -1;  {append}
     sysmenu1.installmenuitem;
     if sysmenu1.inserted = true then
       id[0] := sysmenu1.Newitemid;
    sysmenu1.newmenuitem := 'option two';
    sysmenu1.installmenuitem;
    if sysmenu1.inserted = true then
      id[1] := sysmenu1.newitemid;
end;

The above example appends two new menu items and sets the id array to the newitemid after each call to the installmenuitem method.


Inserted Property

Description

The Inserted property is a read only boolean property and is used to determine if the Installmenuitem method was successful.  If the item could not be installed, this property is set to false, otherwise it is set to true.

Example:

sysmenu1.parenthandle := form1.handle;
sysmenu1.newmenuitem := 'Always on top';
sysmenu1.menupos := -1 ; {append}
sysmenu1.installmenuitem;
if not sysmenu1.inserted then
  Showmessage('Could not append menu item !');


Methods

InstallMenuItem

RemoveMenuItem

ResetMenu

CheckItem

UncheckItem

EnableItem

DisableItem

IsItemChecked

IsItemEnabled

GetItemCaption


InstallMenuItem Method

Description

This method installs the new menu item on the system menu.  If successful, this method sets the inserted property to true. If not, the inserted property is set to false.  You should query the inserted property after each call to InstallMenuItem.  Before calling this method, be sure to set the NewMenuItem and MenuPos properties as well as any other properties needed to control the state of the new item.  This method sets the MenuPos property to the actual position where the item was inserted when it returns.  This is useful when appending an item to the menu, the MenuPos property is initially -1, but upon return from this method, the MenuPos property will be the actual position inserted (appended) in the menu.

See Also:

RemoveMenuItem

Properties


RemoveMenuItem Method

Description

This method removes the menu item indicated by the MenuPos property from the system menu.

Example:

sysmenu1.menupos := 0;
sysmenu1.removemenuitem;

The above example removes the first item in the system menu.


ResetMenu Method

Description

This method resets the system menu to its initial state.  Any items that have been added with this component will be removed.

Example:

sysmenu1.newitemid := 'Option one';
sysmenu1.menupos := -1;
sysmenu1.installmenuitem;
sysmenu1.newitemid := 'Option two';
sysmenu1.installmenuitem;
...
...
...
sysmenu1.resetmenu;

The above example adds two items to the menu and (later) resets the menu to its original state.


CheckItem Method

Description

This method is a function which takes one integer parameter indicating the position of the menu item.  If the parameter is a valid menu item then the method will cause that item to appear as checked.  This method is distinguished from the MenuChecked property in that it operates on items that have already been installed into the system menu, or for that matter, an item in the menu whether or not it was installed with the system menu component.

Example

sysmenu1.checkitem(0);

The item in position 0 of the system menu (the first item) will be checked.

See Also:

UnCheckItem


UnCheckItem Method

This method is a function which takes one integer parameter indicating the position of the menu item.  If the parameter is a valid menu item then the method will cause that item to appear as checked.  This method is distinguished from the MenuChecked property (when false) in that it operates on items that have already been installed into the system menu, or for that matter, an item in the menu whether or not it was installed with the system menu component.

Example

sysmenu1.Uncheckitem(0);

The item in position 0 of the system menu (the first item) will be unchecked.

See Also:

CheckItem


EnableItem Method

Description

This method is a function which takes one integer parameter indicating the position of the menu item.  If the parameter is a valid menu item then the method will cause that item to appear as checked.  This method is distinguished from the MenuEnabled property in that it operates on items that have already been installed into the system menu, or for that matter, an item in the menu whether or not it was installed with the system menu component.

Example:

sysmenu1.Enableitem(0);

The item in position 0 of the system menu (the first item) will be enabled.

See Also:

DisableItem


DisableItem Method

Description

This method is a function which takes one integer parameter indicating the position of the menu item.  If the parameter is a valid menu item then the method will cause that item to appear as checked.  This method is distinguished from the MenuEnabled property (when false) in that it operates on items that have already been installed into the system menu, or for that matter, an item in the menu whether or not it was installed with the system menu component.

Example:

sysmenu1.disableitem(0);

The menu item in position 0 will be disabled.

See Also:

EnableItem


IsItemChecked Method

Description

This method is a function which takes one parameter which is an integer indicating the item;s position in the menu.  The return value is boolean true or false indicating whether the menu item is checked or unchecked.

Example:

If sysmenu1.IsItemChecked(1) then
  ShowMessage('Menu Item 1 is checked');
else
  ShowMessage('Menu Item 1 is unchecked');


IsItemEnabled Method

Description

This method is a function which takes one parameter which is an integer indicating the item;s position in the menu.  The return value is boolean true or false indicating whether the menu item is enabled or disabled.

Example:

If sysmenu1.IsItemenabled(1) then
  ShowMessage('Menu Item 1 is enabled');
else
  ShowMessage('Menu Item 1 is disabled');


GetItemCaption Method

Description

This method is a function which returns the menu item's caption as a string.  The method takes one integer parameter indicating the position of the item within the menu.

Example:

var
        Cap : string;
begin
        Cap := sysmenu1.GetItemCaption(0);
        ShowMessage('Item 0 Caption = ' + Cap);


mtChecked

For the Menuchecked property indicates that the item should be checked.


mtDisabled

For the MenuEnabled property indicates that the new menu item should be disabled.


mtEnabled

For the MenuEnabled property, indicates that the new menu item is to be enabled.


mtGrayed

For the MenuEnabled property, indicates that the new menu item should be grayed.  Effectively this is the same as mtDisabled.


mtMenuBarBreak

A vertical menu bar separator.


mtMenuBreak

A horizontal menu bar separator.


mtNone

No Separator bar.  This is the default for the MenuBar property.


mtSeparator

For the MenuItemType property indicates that the NewMenuItem to be added is a menu separator bar.


mtString

For the MenuItemType property indicates that the NewMenuItem is a string to be added to the system menu.


mtUnchecked

For the Menuchecked property indicates that the item should be unchecked.