Castle Game Engine

Class TMenuItem

Description
Hierarchy
Fields
Methods
Properties

Unit

CastleWindow

Declaration

type TMenuItem = class(TMenuEntryWithCaption)

Description

TMenuEntry that is a simple, clickable menu item. User expects that something will happend when he clicks on TMenuItem. You can also specify key shortcuts for this menu item.

Hierarchy

Overview

Methods

Public function DoClick: boolean; virtual;
Public function KeyToString(out S: string): boolean;
Public function KeyMatches(const AKey: TKey; const AKeyString: String; const AModifiers: TModifierKeys): boolean;
Public function CaptionWithKey: string;
Public constructor Create(const ACaption: String; AIntData: Integer); overload;
Public constructor Create(const ACaption: String; AIntData: Integer; AKeyString: String); overload;
Public constructor Create(const ACaption: String; AIntData: Integer; AKey: TKey); overload;
Public destructor Destroy; override;

Properties

Public property IntData: Integer read FIntData write FIntData;
Public property SmallId: Integer read FSmallId;
Public property KeyString: String read FKeyString write FKeyString;
Public property Key: TKey read FKey write FKey default keyNone;
Public property CharKey: Char read GetCharKey write SetCharKey; deprecated 'use KeyString';
Public property Modifiers: TModifierKeys read FModifiers write FModifiers;

Description

Methods

Public function DoClick: boolean; virtual;

Called when this menu item will be choosen by user (by clicking, or pressing the matching key shortcut).

You can override this and return true if you handled the event. If this will return false, CastleWindow will call EventMenuClick (OnMenuClick).

When entering this method, current OpenGL context is set to the context of the window that the clicked menu belongs to.

Default implementation of this method in this class always returns false.

Public function KeyToString(out S: string): boolean;

Returns as S the string that describes key shortcut (KeyString, Key, Modifiers) and then returns true. If KeyString = '' and Key = keyNone then returns false and S is undefined.

Public function KeyMatches(const AKey: TKey; const AKeyString: String; const AModifiers: TModifierKeys): boolean;
 
Public function CaptionWithKey: string;

Caption with optional key description (returned by KeyString) appended.

Public constructor Create(const ACaption: String; AIntData: Integer); overload;
 
Public constructor Create(const ACaption: String; AIntData: Integer; AKeyString: String); overload;
 
Public constructor Create(const ACaption: String; AIntData: Integer; AKey: TKey); overload;
 
Public destructor Destroy; override;
 

Properties

Public property IntData: Integer read FIntData write FIntData;

An integer value, for any purpose you want. Useful to identify this item in TCastleWindow.OnMenuClick callback.

Public property SmallId: Integer read FSmallId;

Unique small identifier of this menu item. This is initialized at creation of this object, to be unique among all currently existing (created and not destroyed) TMenuItem instances.

The intention is that this SmallId should be the smallest possible value >= 0. So it's not something like PtrUInt(Self). This may be useful when you're constructing a menu using some API — you usually want to identify your menu item by some unique id and you want this id to be small (e.g. under WinAPI menu item's id must fit in 16 bit integer).

See also
MenuItemFromSmallId
Search for menu item with given SmallId.
Public property KeyString: String read FKeyString write FKeyString;

Key shortcut for this menu item.

When user presses indicated Key (if it's not keyNone) or KeyString (if it's not '') then DoClick will be called (which results in TCastleWindow.EventMenuClick, and TCastleWindow.OnMenuClick, if DoClick returns false).

Handling of menu key shortcuts is completely within the CastleWindow (usually, it's even done by the underlying backend like GTK or WinAPI). You will not get EventPress (OnPress) messages for keypresses that translate to menu clicks. Although TCastleWindow.Pressed.Keys will be still appropriately updated.

Note that Caption of this object should not contain description of Key or KeyString. The backend will automatically show the key description in an appropriate way.

You should use at most one of these properties, not both. So either use Key or KeyString, and leave the other one at default value (Key = keyNone, KeyString = '').

The KeyString values within range CtrlA..CtrlZ mean that user must press the given letter with Ctrl modfier. This rule includes some special chars like

The KeyString values above do not mean the backspace or tab or enter keys, they mean the combination of Ctrl key + respective letter. If you want to have backspace/tab/enter keys to activate the menu item, use Key = keyBackSpace, Key = keyTab or Key = keyEnter.

TODO: for now, this must be assigned before adding this menu item to parent (actually, before the parent menu is added to window MainMenu) to work reliably. Don't change this property afterwards. Usually, you will set this property by an argument to the constructor.

Public property Key: TKey read FKey write FKey default keyNone;
 
Public property CharKey: Char read GetCharKey write SetCharKey; deprecated 'use KeyString';

Warning: this symbol is deprecated: use KeyString

 
Public property Modifiers: TModifierKeys read FModifiers write FModifiers;

Modifiers (shift, ctrl and such) required to activate this menu item. These have to be pressed along with Key or KeyString.

Note that KeyString may already indicate some modifiers, if it's one of the CtrlA ... CtrlZ then the Ctrl key is required and if it's an uppercase letter then the Shift key is required. There's no need to include this modifier in this property then.

TODO: for now, this must be assigned before adding this menu item to parent (actually, before the parent menu is added to window MainMenu) to work reliably. Don't change this property afterwards.

Generated by PasDoc 0.16.0.