Class TCastleOnScreenMenu

DescriptionHierarchyFieldsMethodsProperties

Unit

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

Overview

Fields

Public internal const DefaultMenuKeyNextItem = K_Down;
Public internal const DefaultMenuKeyPreviousItem = K_Up;
Public internal const DefaultMenuKeySelectItem = K_Enter;
Public internal const DefaultMenuKeySliderIncrease = K_Right;
Public internal const DefaultMenuKeySliderDecrease = K_Left;
Public internal const DefaultCurrentItemBorderColor1: TVector3Single = ( 1, 1, 1) ;
Public internal const DefaultCurrentItemBorderColor2: TVector3Single = ( 0.5, 0.5, 0.5) ;
Public internal const DefaultCurrentItemColor : TVector3Single = ( 1, 1, 0.3) ;
Public internal const DefaultNonCurrentItemColor : TVector3Single = ( 1, 1, 1) ;
Public internal const DefaultRegularSpaceBetweenItems = 10;
Public internal const DefaultBackgroundOpacityNotFocused = 0.4;
Public internal const DefaultBackgroundOpacityFocused = 0.7;
Public var Position: TVector2Integer;

Methods

Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;
Public function CurrentAccessory: TMenuAccessory;
Public procedure NextItem;
Public procedure PreviousItem;
Public procedure GLContextClose; override;
Public procedure FixItemsRectangles;
Public procedure ContainerResize(const AContainerWidth, AContainerHeight: Cardinal); override;
Public function DrawStyle: TUIControlDrawStyle; override;
Public procedure Draw; override;
Public function Press(const Event: TInputPressRelease): boolean; override;
Public function Release(const Event: TInputPressRelease): boolean; override;
Public function MouseMove(const OldX, OldY, NewX, NewY: Integer): boolean; override;
Public procedure Update(const SecondsPassed: Single; var HandleInput: boolean); override;
Public function PositionInside(const X, Y: Integer): boolean; override;
Public function AllowSuspendForInput: boolean; override;
Public procedure Click; virtual;
Public procedure CurrentItemSelected; virtual; deprecated;
Public procedure AccessoryValueChanged; virtual;
Public procedure CurrentItemAccessoryValueChanged; virtual; deprecated;
Public procedure CurrentItemChanged; virtual;
Public function SpaceBetweenItems(const NextItemIndex: Cardinal): Cardinal; virtual;

Properties

Public property PositionAbsolute: TVector2Integer read FPositionAbsolute;
Public property CurrentItem: Integer read GetCurrentItem write SetCurrentItem;
Public property Rectangles: TRectangleList read FRectangles;
Public property AllItemsRectangle: TRectangle read FAllItemsRectangle;
Public property AccessoryRectangles: TRectangleList read FAccessoryRectangles;
Public property KeyNextItem: TKey read FKeyNextItem write FKeyNextItem default DefaultMenuKeyNextItem;
Public property KeyPreviousItem: TKey read FKeyPreviousItem write FKeyPreviousItem default DefaultMenuKeyPreviousItem;
Public property KeySelectItem: TKey read FKeySelectItem write FKeySelectItem default DefaultMenuKeySelectItem;
Public property KeySliderIncrease: TKey read FKeySliderIncrease write FKeySliderIncrease default DefaultMenuKeySliderIncrease;
Public property KeySliderDecrease: TKey read FKeySliderDecrease write FKeySliderDecrease default DefaultMenuKeySliderDecrease;
Public property CurrentItemBorderColor1: TVector3Single read FCurrentItemBorderColor1 write FCurrentItemBorderColor1;
Public property CurrentItemBorderColor2: TVector3Single read FCurrentItemBorderColor2 write FCurrentItemBorderColor2;
Public property CurrentItemColor : TVector3Single read FCurrentItemColor write FCurrentItemColor;
Public property NonCurrentItemColor : TVector3Single read FNonCurrentItemColor write FNonCurrentItemColor;
Public property DesignerMode: boolean read FDesignerMode write SetDesignerMode default false;
Published property BackgroundOpacityFocused: Single read FBackgroundOpacityFocused write FBackgroundOpacityFocused default DefaultBackgroundOpacityFocused;
Published property BackgroundOpacityNotFocused: Single read FBackgroundOpacityNotFocused write FBackgroundOpacityNotFocused default DefaultBackgroundOpacityNotFocused;
Published property PositionRelativeMenuX: TPositionRelative read FPositionRelativeMenuX write FPositionRelativeMenuX default prMiddle;
Published property PositionRelativeMenuY: TPositionRelative read FPositionRelativeMenuY write FPositionRelativeMenuY default prMiddle;
Published property PositionRelativeScreenX: TPositionRelative read FPositionRelativeScreenX write FPositionRelativeScreenX default prMiddle;
Published property PositionRelativeScreenY: TPositionRelative read FPositionRelativeScreenY write FPositionRelativeScreenY default prMiddle;
Published property DrawBackgroundRectangle: boolean read FDrawBackgroundRectangle write FDrawBackgroundRectangle default true;
Published property RegularSpaceBetweenItems: Cardinal read FRegularSpaceBetweenItems write FRegularSpaceBetweenItems default DefaultRegularSpaceBetweenItems;
Published property DrawFocusedBorder: boolean read FDrawFocusedBorder write FDrawFocusedBorder default true;
Published property Items: TStringList read FItems write SetItems;
Published property OnClick: TNotifyEvent read FOnClick write FOnClick;
Published property OnAccessoryValueChanged: TNotifyEvent read FOnAccessoryValueChanged write FOnAccessoryValueChanged;
Published property FullSize: boolean read FFullSize write FFullSize default false;

Description

Fields

Public internal const DefaultMenuKeyNextItem = K_Down;
 
Public internal const DefaultMenuKeyPreviousItem = K_Up;
 
Public internal const DefaultMenuKeySelectItem = K_Enter;
 
Public internal const DefaultMenuKeySliderIncrease = K_Right;
 
Public internal const DefaultMenuKeySliderDecrease = K_Left;
 
Public internal const DefaultCurrentItemBorderColor1: TVector3Single = ( 1, 1, 1) ;
 
Public internal const DefaultCurrentItemBorderColor2: TVector3Single = ( 0.5, 0.5, 0.5) ;
 
Public internal const DefaultCurrentItemColor : TVector3Single = ( 1, 1, 0.3) ;
 
Public internal const DefaultNonCurrentItemColor : TVector3Single = ( 1, 1, 1) ;
 
Public internal const DefaultRegularSpaceBetweenItems = 10;
 
Public internal const DefaultBackgroundOpacityNotFocused = 0.4;
 
Public internal const DefaultBackgroundOpacityFocused = 0.7;
 
Public 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

Public constructor Create(AOwner: TComponent); override;
 
Public destructor Destroy; override;
 
Public function CurrentAccessory: TMenuAccessory;

The accessory (like a slider) attached to currently selected menu item. Nil if none.

Public 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.

Public procedure PreviousItem;
 
Public procedure GLContextClose; override;
 
Public procedure FixItemsRectangles;

Calculate final positions, sizes of menu items on the screen. You must call FixItemsRectangles between last modification of

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.

Public procedure ContainerResize(const AContainerWidth, AContainerHeight: Cardinal); override;
 
Public function DrawStyle: TUIControlDrawStyle; override;
 
Public procedure Draw; override;
 
Public function Press(const Event: TInputPressRelease): boolean; override;
 
Public function Release(const Event: TInputPressRelease): boolean; override;
 
Public function MouseMove(const OldX, OldY, NewX, NewY: Integer): boolean; override;
 
Public procedure Update(const SecondsPassed: Single; var HandleInput: boolean); override;
 
Public function PositionInside(const X, Y: Integer): boolean; override;
 
Public function AllowSuspendForInput: boolean; override;
 
Public procedure Click; virtual;

Called when user will select CurrentItem, either with mouse or with keyboard.

Public procedure CurrentItemSelected; virtual; deprecated;

Warning: this symbol is deprecated.

Deprecated name for Click.

Public 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.

Public procedure CurrentItemAccessoryValueChanged; virtual; deprecated;

Warning: this symbol is deprecated.

Deprecated name for AccessoryValueChanged.

Public 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.

Public 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

Public 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.

Public 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.

Public 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.

Public property AllItemsRectangle: TRectangle read FAllItemsRectangle;
 
Public property AccessoryRectangles: TRectangleList read FAccessoryRectangles;
 
Public property KeyNextItem: TKey read FKeyNextItem write FKeyNextItem default DefaultMenuKeyNextItem;
 
Public property KeyPreviousItem: TKey read FKeyPreviousItem write FKeyPreviousItem default DefaultMenuKeyPreviousItem;
 
Public property KeySelectItem: TKey read FKeySelectItem write FKeySelectItem default DefaultMenuKeySelectItem;
 
Public property KeySliderIncrease: TKey read FKeySliderIncrease write FKeySliderIncrease default DefaultMenuKeySliderIncrease;
 
Public property KeySliderDecrease: TKey read FKeySliderDecrease write FKeySliderDecrease default DefaultMenuKeySliderDecrease;
 
Public property CurrentItemBorderColor1: TVector3Single read FCurrentItemBorderColor1 write FCurrentItemBorderColor1;

Default value is DefaultCurrentItemBorderColor1

Public property CurrentItemBorderColor2: TVector3Single read FCurrentItemBorderColor2 write FCurrentItemBorderColor2;

Default value is DefaultCurrentItemBorderColor2

Public property CurrentItemColor : TVector3Single read FCurrentItemColor write FCurrentItemColor;

Default value is DefaultCurrentItemColor

Public property NonCurrentItemColor : TVector3Single read FNonCurrentItemColor write FNonCurrentItemColor;

Default value is DefaultNonCurrentItemColor

Public 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:

    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.

Published property BackgroundOpacityFocused: Single read FBackgroundOpacityFocused write FBackgroundOpacityFocused default DefaultBackgroundOpacityFocused;

Opacity of the background rectangle (displayed when DrawBackgroundRectangle).

Published property BackgroundOpacityNotFocused: Single read FBackgroundOpacityNotFocused write FBackgroundOpacityNotFocused default DefaultBackgroundOpacityNotFocused;
 
Published property PositionRelativeMenuX: TPositionRelative read FPositionRelativeMenuX write FPositionRelativeMenuX default prMiddle;

See TPositionRelative documentation for meaning of these four PositionRelativeXxx properties.

Published property PositionRelativeMenuY: TPositionRelative read FPositionRelativeMenuY write FPositionRelativeMenuY default prMiddle;
 
Published property PositionRelativeScreenX: TPositionRelative read FPositionRelativeScreenX write FPositionRelativeScreenX default prMiddle;
 
Published property PositionRelativeScreenY: TPositionRelative read FPositionRelativeScreenY write FPositionRelativeScreenY default prMiddle;
 
Published property DrawBackgroundRectangle: boolean read FDrawBackgroundRectangle write FDrawBackgroundRectangle default true;
 
Published 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.

Published property DrawFocusedBorder: boolean read FDrawFocusedBorder write FDrawFocusedBorder default true;

Draw a flashing border around the menu when we are focused.

Published 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.

Published 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.
Published 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.
Published 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