Castle Game Engine: CastleOnScreenMenu: Class TCastleOnScreenMenu

# Class TCastleOnScreenMenu
Description | Hierarchy | Fields | Methods | Properties
## Unit CastleOnScreenMenu ## Declaration `type TCastleOnScreenMenu = class(TUIControl)` ## Description On-screen menu displayed in OpenGL. All the menu items are simply displayed on the screen, one after the other. Typical for game menus. Normal user programs may prefer to use the menu bar instead of this (for example TCastleWindowBase.Menu, or normal Lazarus menu). Although this still may be useful for displaying things like sliders. ## Hierarchy TComponent TInputListener TUIControl TCastleOnScreenMenu ## Overview ### Fields
| `internal const DefaultMenuKeyNextItem = K_Down;`
| `internal const DefaultMenuKeyPreviousItem = K_Up;`
| `internal const DefaultMenuKeySelectItem = K_Enter;`
| `internal const DefaultMenuKeySliderIncrease = K_Right;`
| `internal const DefaultMenuKeySliderDecrease = K_Left;`
| `internal const DefaultCurrentItemBorderColor1: TVector3Single = ( 1, 1, 1) ;`
| `internal const DefaultCurrentItemBorderColor2: TVector3Single = ( 0.5, 0.5, 0.5) ;`
| `internal const DefaultCurrentItemColor : TVector3Single = ( 1, 1, 0.3) ;`
| `internal const DefaultNonCurrentItemColor : TVector3Single = ( 1, 1, 1) ;`
| `internal const DefaultRegularSpaceBetweenItems = 10;`
| `internal const DefaultBackgroundOpacityNotFocused = 0.4;`
| `internal const DefaultBackgroundOpacityFocused = 0.7;`
| `var Position: TVector2Integer;`
### Methods
| `constructor Create(AOwner: TComponent); override;`
| `destructor Destroy; override;`
| `function CurrentAccessory: TMenuAccessory;`
| `procedure NextItem;`
| `procedure PreviousItem;`
| `procedure GLContextClose; override;`
| `procedure FixItemsRectangles;`
| `procedure ContainerResize(const AContainerWidth, AContainerHeight: Cardinal); override;`
| `function DrawStyle: TUIControlDrawStyle; override;`
| `procedure Draw; override;`
| `function Press(const Event: TInputPressRelease): boolean; override;`
| `function Release(const Event: TInputPressRelease): boolean; override;`
| `function MouseMove(const OldX, OldY, NewX, NewY: Integer): boolean; override;`
| `procedure Update(const SecondsPassed: Single; var HandleInput: boolean); override;`
| `function PositionInside(const X, Y: Integer): boolean; override;`
| `function AllowSuspendForInput: boolean; override;`
| `procedure Click; virtual;`
| `procedure CurrentItemSelected; virtual; deprecated;`
| `procedure AccessoryValueChanged; virtual;`
| `procedure CurrentItemAccessoryValueChanged; virtual; deprecated;`
| `procedure CurrentItemChanged; virtual;`
| `function SpaceBetweenItems(const NextItemIndex: Cardinal): Cardinal; virtual;`
### Properties
| `property PositionAbsolute: TVector2Integer read FPositionAbsolute;`
| `property CurrentItem: Integer read GetCurrentItem write SetCurrentItem;`
| `property Rectangles: TRectangleList read FRectangles;`
| `property AllItemsRectangle: TRectangle read FAllItemsRectangle;`
| `property AccessoryRectangles: TRectangleList read FAccessoryRectangles;`
| `property KeyNextItem: TKey read FKeyNextItem write FKeyNextItem default DefaultMenuKeyNextItem;`
| `property KeyPreviousItem: TKey read FKeyPreviousItem write FKeyPreviousItem default DefaultMenuKeyPreviousItem;`
| `property KeySelectItem: TKey read FKeySelectItem write FKeySelectItem default DefaultMenuKeySelectItem;`
| `property KeySliderIncrease: TKey read FKeySliderIncrease write FKeySliderIncrease default DefaultMenuKeySliderIncrease;`
| `property KeySliderDecrease: TKey read FKeySliderDecrease write FKeySliderDecrease default DefaultMenuKeySliderDecrease;`
| `property CurrentItemBorderColor1: TVector3Single read FCurrentItemBorderColor1 write FCurrentItemBorderColor1;`
| `property CurrentItemBorderColor2: TVector3Single read FCurrentItemBorderColor2 write FCurrentItemBorderColor2;`
| `property CurrentItemColor : TVector3Single read FCurrentItemColor write FCurrentItemColor;`
| `property NonCurrentItemColor : TVector3Single read FNonCurrentItemColor write FNonCurrentItemColor;`
| `property DesignerMode: boolean read FDesignerMode write SetDesignerMode default false;`
| `property BackgroundOpacityFocused: Single read FBackgroundOpacityFocused write FBackgroundOpacityFocused default DefaultBackgroundOpacityFocused;`
| `property BackgroundOpacityNotFocused: Single read FBackgroundOpacityNotFocused write FBackgroundOpacityNotFocused default DefaultBackgroundOpacityNotFocused;`
| `property PositionRelativeMenuX: TPositionRelative read FPositionRelativeMenuX write FPositionRelativeMenuX default prMiddle;`
| `property PositionRelativeMenuY: TPositionRelative read FPositionRelativeMenuY write FPositionRelativeMenuY default prMiddle;`
| `property PositionRelativeScreenX: TPositionRelative read FPositionRelativeScreenX write FPositionRelativeScreenX default prMiddle;`
| `property PositionRelativeScreenY: TPositionRelative read FPositionRelativeScreenY write FPositionRelativeScreenY default prMiddle;`
| `property DrawBackgroundRectangle: boolean read FDrawBackgroundRectangle write FDrawBackgroundRectangle default true;`
| `property RegularSpaceBetweenItems: Cardinal read FRegularSpaceBetweenItems write FRegularSpaceBetweenItems default DefaultRegularSpaceBetweenItems;`
| `property DrawFocusedBorder: boolean read FDrawFocusedBorder write FDrawFocusedBorder default true;`
| `property Items: TStringList read FItems write SetItems;`
| `property OnClick: TNotifyEvent read FOnClick write FOnClick;`
| `property OnAccessoryValueChanged: TNotifyEvent read FOnAccessoryValueChanged write FOnAccessoryValueChanged;`
| `property FullSize: boolean read FFullSize write FFullSize default false;`
## Description ### Fields
| `internal const DefaultMenuKeyNextItem = K_Down;`
| `internal const DefaultMenuKeyPreviousItem = K_Up;`
| `internal const DefaultMenuKeySelectItem = K_Enter;`
| `internal const DefaultMenuKeySliderIncrease = K_Right;`
| `internal const DefaultMenuKeySliderDecrease = K_Left;`
| `internal const DefaultCurrentItemBorderColor1: TVector3Single = ( 1, 1, 1) ;`
| `internal const DefaultCurrentItemBorderColor2: TVector3Single = ( 0.5, 0.5, 0.5) ;`
| `internal const DefaultCurrentItemColor : TVector3Single = ( 1, 1, 0.3) ;`
| `internal const DefaultNonCurrentItemColor : TVector3Single = ( 1, 1, 1) ;`
| `internal const DefaultRegularSpaceBetweenItems = 10;`
| `internal const DefaultBackgroundOpacityNotFocused = 0.4;`
| `internal const DefaultBackgroundOpacityFocused = 0.7;`
| `var Position: TVector2Integer;`
Position of the menu. Expressed as position of some corner of the menu (see PositionRelativeMenuX/Y), relative to some corner of the screen (see PositionRelativeScreenX/Y). See TPositionRelative documentation for more information. You may be interested in DesignerMode for a possibility to set this property at run-time. Expressed as a public field (instead of a read-write property) because assigning a field of record property is a risk in ObjectPascal (you may be modifying only a temporary copy of the record returned by property getter).
### Methods
| `constructor Create(AOwner: TComponent); override;`
| `destructor Destroy; override;`
| `function CurrentAccessory: TMenuAccessory;`
The accessory (like a slider) attached to currently selected menu item. `Nil` if none.
| `procedure NextItem;`
These change CurrentItem as appropriate. Usually you will just let this class call it internally (from MouseMove, KeyDown etc.) and will not need to call it yourself.
| `procedure PreviousItem;`
| `procedure GLContextClose; override;`
| `procedure FixItemsRectangles;`
Calculate final positions, sizes of menu items on the screen. You must call `FixItemsRectangles` between last modification of Items Position RegularSpaceBetweenItems (and eventually everything else that affects your custom SpaceBetweenItems implementation) and calling one of the procedures Draw MouseMove MouseDown MouseUp KeyDown Update You can call this only while OpenGL context is initialized. ContainerResize already calls `FixItemsRectangles`, and window resize is already called automatically by window (at the addition to Controls list, or whenever window size changes). So in simplest cases (when you fill Items etc. properties before adding TCastleOnScreenMenu to Controls) you, in practice, do not have to call this explicitly.
| `procedure ContainerResize(const AContainerWidth, AContainerHeight: Cardinal); override;`
| `function DrawStyle: TUIControlDrawStyle; override;`
| `procedure Draw; override;`
| `function Press(const Event: TInputPressRelease): boolean; override;`
| `function Release(const Event: TInputPressRelease): boolean; override;`
| `function MouseMove(const OldX, OldY, NewX, NewY: Integer): boolean; override;`
| `procedure Update(const SecondsPassed: Single; var HandleInput: boolean); override;`
| `function PositionInside(const X, Y: Integer): boolean; override;`
| `function AllowSuspendForInput: boolean; override;`
| `procedure Click; virtual;`
Called when user will select CurrentItem, either with mouse or with keyboard.
| `procedure CurrentItemSelected; virtual; deprecated;`
Warning: this symbol is deprecated. Deprecated name for Click.
| `procedure AccessoryValueChanged; virtual;`
Called when the value of current accessory (TMenuAccessory assigned to CurrentItem) changed its value. (Which may happen due to user clicking, or pressing some keys etc.) Note that this will not be called when you just set Value of some property. In the TCastleOnScreenMenu class this just calls VisibleChange, and OnAccessoryValueChanged. You can look at CurrentAccessory or (less advised) CurrentItem to see what changed.
| `procedure CurrentItemAccessoryValueChanged; virtual; deprecated;`
Warning: this symbol is deprecated. Deprecated name for AccessoryValueChanged.
| `procedure CurrentItemChanged; virtual;`
Called when CurrentItem changed. But *not* when CurrentItem changed because of Items.Count changes. In this class this just calls VisibleChange and plays sound stMenuCurrentItemChanged.
| `function SpaceBetweenItems(const NextItemIndex: Cardinal): Cardinal; virtual;`
Return the space needed before NextItemIndex. This will be a space between NextItemIndex - 1 and NextItemIndex (this method will not be called for NextItemIndex = 0). Default implementation in this class simply returns RegularSpaceBetweenItems always. Note that this is used only at FixItemsRectangles call. So when some variable affecting the implementation of this changes, you should call FixItemsRectangles again.
### Properties
| `property PositionAbsolute: TVector2Integer read FPositionAbsolute;`
`PositionAbsolute` expresses the position of the menu rectangle independently from all PositionRelative* properties. You can think of it as "What value would Position have if all PositionRelative* were equal prLowerBorder". An easy exercise for the reader is to check implementation that when all PositionRelative* are prLowerBorder, `PositionAbsolute` is indeed always equal to Position :) This is read-only, is calculated by FixItemsRectangles. It's calculated anyway because our drawing code needs this. You may find it useful if you want to draw something relative to menu position.
| `property CurrentItem: Integer read GetCurrentItem write SetCurrentItem;`
When Items.Count <> 0, this is always some number between 0 and Items.Count - 1. Otherwise (when Items.Count <> 0) this is always -1. If you assign it to wrong value (breaking conditions above), or if you change Items such that conditions are broken, it will be arbitrarily fixed. Changing this calls CurrentItemChanged automatically when needed.
| `property Rectangles: TRectangleList read FRectangles;`
Calculates menu items positions, sizes. These are initialized by FixItemsRectangles. They are absolutely read-only for the user of this class. You can use them to do some graphic effects, when you e.g. want to draw something on the screen that is somehow positioned relative to some menu item or to whole menu rectangle. Note that AllItemsRectangle includes also some outside margin.
| `property AllItemsRectangle: TRectangle read FAllItemsRectangle;`
| `property AccessoryRectangles: TRectangleList read FAccessoryRectangles;`
| `property KeyNextItem: TKey read FKeyNextItem write FKeyNextItem default DefaultMenuKeyNextItem;`
| `property KeyPreviousItem: TKey read FKeyPreviousItem write FKeyPreviousItem default DefaultMenuKeyPreviousItem;`
| `property KeySelectItem: TKey read FKeySelectItem write FKeySelectItem default DefaultMenuKeySelectItem;`
| `property KeySliderIncrease: TKey read FKeySliderIncrease write FKeySliderIncrease default DefaultMenuKeySliderIncrease;`
| `property KeySliderDecrease: TKey read FKeySliderDecrease write FKeySliderDecrease default DefaultMenuKeySliderDecrease;`
| `property CurrentItemBorderColor1: TVector3Single read FCurrentItemBorderColor1 write FCurrentItemBorderColor1;`
Default value is DefaultCurrentItemBorderColor1
| `property CurrentItemBorderColor2: TVector3Single read FCurrentItemBorderColor2 write FCurrentItemBorderColor2;`
Default value is DefaultCurrentItemBorderColor2
| `property CurrentItemColor : TVector3Single read FCurrentItemColor write FCurrentItemColor;`
Default value is DefaultCurrentItemColor
| `property NonCurrentItemColor : TVector3Single read FNonCurrentItemColor write FNonCurrentItemColor;`
Default value is DefaultNonCurrentItemColor
| `property DesignerMode: boolean read FDesignerMode write SetDesignerMode default false;`
"Designer mode" is useful for a developer to visually design some properties of TCastleOnScreenMenu. Container of this control will be aumatically used, we will set mouse position when entering `DesignerMode` to match current menu position. This is usually desirable (otherwise slight mouse move will immediately change menu position). To make it work, make sure Container is assigned before setting `DesignerMode` to `True` — in other words, make sure you add this control to something like TCastleWindowCustom.Controls first, and only then set DesignedMode := `True`. This works assuming that you always call our Draw with identity transform matrix (otherwise, this unit is not able to know how to calculate mouse position corresponding to given menu PositionAbsolute). By default, we're not in designer mode, and user has no way to enter into designer mode. You have to actually add some code to your program to activate designer mode. E.g. in "The Rift" game I required that user passes --debug-menu-designer command-line option and then `DesignerMode` could be toggled by F12 key press. Right now, features of designer mode: Mouse move change Position to current mouse position. PositionRelative changing: Key X changes PositionRelativeScreenX value, key Y changes PositionRelativeScreenY value, Key CtrlX changes PositionRelativeMenuX values, Key CtrlY changes PositionRelativeMenuY values. Also, a white line is drawn in designer mode, to indicate the referenced screen and menu positions. CtrlB toggles DrawBackgroundRectangle. Key CtrlD dumps current properties to StdOut. Basically, every property that can be changed from designer mode is dumped here. This is crucial function if you decide that you want to actually use the designed properties in your program, so you want to paste code setting such properties.
| `property BackgroundOpacityFocused: Single read FBackgroundOpacityFocused write FBackgroundOpacityFocused default DefaultBackgroundOpacityFocused;`
Opacity of the background rectangle (displayed when DrawBackgroundRectangle).
| `property BackgroundOpacityNotFocused: Single read FBackgroundOpacityNotFocused write FBackgroundOpacityNotFocused default DefaultBackgroundOpacityNotFocused;`
| `property PositionRelativeMenuX: TPositionRelative read FPositionRelativeMenuX write FPositionRelativeMenuX default prMiddle;`
See TPositionRelative documentation for meaning of these four PositionRelativeXxx properties.
| `property PositionRelativeMenuY: TPositionRelative read FPositionRelativeMenuY write FPositionRelativeMenuY default prMiddle;`
| `property PositionRelativeScreenX: TPositionRelative read FPositionRelativeScreenX write FPositionRelativeScreenX default prMiddle;`
| `property PositionRelativeScreenY: TPositionRelative read FPositionRelativeScreenY write FPositionRelativeScreenY default prMiddle;`
| `property DrawBackgroundRectangle: boolean read FDrawBackgroundRectangle write FDrawBackgroundRectangle default true;`
| `property RegularSpaceBetweenItems: Cardinal read FRegularSpaceBetweenItems write FRegularSpaceBetweenItems default DefaultRegularSpaceBetweenItems;`
Additional vertical space, in pixels, between menu items. If you want more control over it (if you want to add more/less space between some menu items), override SpaceBetweenItems method.
| `property DrawFocusedBorder: boolean read FDrawFocusedBorder write FDrawFocusedBorder default true;`
Draw a flashing border around the menu when we are focused.
| `property Items: TStringList read FItems write SetItems;`
Items of this menu. Note that Objects of this class have special meaning: they must be either nil or some TMenuAccessory instance (different TMenuAccessory instance for each item). When freeing this TCastleOnScreenMenu instance, note that we will also free all Items.Objects.
| `property OnClick: TNotifyEvent read FOnClick write FOnClick;`
Called when user will select CurrentItem. ###### See also Click Called when user will select CurrentItem, either with mouse or with keyboard.
| `property OnAccessoryValueChanged: TNotifyEvent read FOnAccessoryValueChanged write FOnAccessoryValueChanged;`
Called when the value of current accessory (TMenuAccessory assigned to CurrentItem) will change value. ###### See also AccessoryValueChanged Called when the value of current accessory (TMenuAccessory assigned to CurrentItem) changed its value.
| `property FullSize: boolean read FFullSize write FFullSize default false;`
Should menu intercept all key/mouse input, that is behave like it was filling full container (window or lazarus component). This affects key/mouse processing (menu processes input before all controls underneath), but not drawing (controls underneath are still visible as usual).
Generated by PasDoc 0.13.0 on 2013-08-17 21:27:13