Class TMenuItem

DescriptionHierarchyFieldsMethodsProperties

Unit

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 DoCommand: boolean; virtual;
Public function KeyString(out S: string): boolean;
Public function KeyMatches(const AKey: TKey; const ACharKey: char): boolean;
Public function CaptionWithKey: string;
Public constructor Create(const ACaption: String; AIntData: Integer); overload;
Public constructor Create(const ACaption: String; AIntData: Integer; ACharKey: char); 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 CharKey: char read FCharKey default #0;
Public property Key: TKey read FKey default K_None;

Description

Methods

Public function DoCommand: boolean; virtual;

This will be called when this MenuItem will be choosen by a user (or user will press key matching with our Key/CharKey).

You can override this and return true if you handled the command. If this will return false, CastleWindow will call EventMenuCommand (OnMenuCommand).

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 KeyString(out S: string): boolean;

This returns as S the string that describes CharKey (if CharKey <> #0) or Key (if Key <> K_None) and then returns true. If both CharKey = #0 and Key = K_None then returns false and S is undefined.

Public function KeyMatches(const AKey: TKey; const ACharKey: char): boolean;
 
Public function CaptionWithKey: string;

This is Caption with optional key description (returned by KeyString) appended in '[' ... ']'.

Public constructor Create(const ACaption: String; AIntData: Integer); overload;
 
Public constructor Create(const ACaption: String; AIntData: Integer; ACharKey: char); 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;

This is any data for user-specific purposes.

Public property SmallId: Integer read FSmallId;

This is internally initialized at creation of this object. Each existing TMenuItem will have a unique SmallId. Each "existing" – – this means that after destroying some TMenuItem object, it's SmallId may be reused by some TMenuItem created after that (even if this does not occur now).

The intention is that this SmallId should be smallest possible value >= 0. So it's NOT something like PtrInt(Self). This means that as long as you won't create, say, more than 60 000 menu items in your program (and that's a reasonable assumption) you can count on the fact that "every SmallId is >= 0 and < 60 000".

And this makes SmallId very useful when you're constructing a menu using some API (like glut, Motif, WinAPI) – 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). That's where PtrInt(Self) is not useful and that's where this SmallId is useful.

See also
MenuItemFromSmallId
Search for menu item with given SmallId.
Public property CharKey: char read FCharKey default #0;

Key shortcuts for this menu item.

If Key <> K_None and user will press this Key then this object's DoCommand will be called (and TCastleWindowBase.EventMenuCommnd, and TCastleWindowBase.OnMenuCommand, if DoCommand returns false). Similiar, is CharKey <> #0 and user will press a key with CharKey then it will be treated as this menu item click.

Such key press redirection is handled internally in CastleWindow (possibly it's even internally handled in some library on top of which CastleWindow is implemented, e.g. WinAPI and GTK menus can be explicitly connected with some key press (i.e. without doing any special redirection keypress -> DoCommand in CastleWindow). So you will not get EventPress (OnPress) messages for such keypresses (that translate to menu click). Although TCastleWindowBase.Pressed.Keys will be appropriately updated, of course.

Note: Caption of this object should not contain description of Key and CharKey, such description will be automatically shown to user (maybe by adding something like ' [Ctrl+O]' to displayed Caption, maybe in some better (more visually-pleasing) way).

Note: you don't have to give really corresponding Key and CharKey values, as such correspondency may be dependent on state of modifier keys and OS configuration.

In fact, usually you SHOULD give Key = K_None or c = #0. E.g. you should NOT set Key = K_C and CharKey = 'c'. Instead you should set Key = K_C and CharKey = #0 or Key = K_None and CharKey = 'c'. This way you avoid some uncertainty: Key = K_C is something other than CharKey = 'c' (e.g. Shift+C generates K_C, but does not translate as CharKey = 'c' (it is translated as CharKey = 'C' ('C' uppercase !)).

Notes about CharKey values #8 (CharBackSpace = CtrlH), #9 (CharTab = CtrlI), #13 (CharEnter = CtrlM): these are problematic, since they may mean backspace/tab/enter or combinations with Ctrl key. Our algorithm to deal with this:

  1. If your CharKey is one of the CharBackSpace/Tab/Enter constants, and Key is K_None, then you mean the combination with Ctrl key. That's how it's displayed, and moreover: keyboard presses with K_BackSpace/K_Tab/K_Enter do not trigger this menu item.

    This way menu items with Ctrl+H or Ctrl+M or Ctrl+I do not block you from assigning keyboard K_BackSpace/K_Tab/K_Enter to some other useful action.

  2. If you really want to assign keyboard backspace/tab/enter presses to menu item, use TKey constants K_BackSpace, K_Tab, K_Enter.

Design notes: I am no longer using TMenuItemKey class. Instead I put this functionality into base TMenuItem class. Before, I had in this class TMenuItemChecked functionality, but it's better to put here TMenuItemKey functionality. That's because in this class we have a natural way to specify TMenuItem that does not translate to any key (Key = K_None and CharKey = #0). While with TMenuItemChecked it would require additional property ShowChecked. And I HAVE to integrate into TMenuItem class some functionality – otherwise, if I would separated both TMenuItemKey and TMenuItemChecked classes, then I would be forced to create additional TMenuItemKeyChecked class.

TODO: change these to writeable

Public property Key: TKey read FKey default K_None;
 

Generated by PasDoc 0.12.1 on 2013-02-04 20:26:53