Class TCastleButton

Unit

Declaration

type TCastleButton = class(TCastleUserInterfaceFont)

Description

Clickable button.

This is TCastleUserInterface descendant, so to use it just add it to the TCastleWindowCustom.Controls or TCastleControlCustom.Controls list. You will also usually want to adjust position (TCastleButton.Left, TCastleButton.Bottom), TCastleButton.Caption, and assign TCastleButton.OnClick (or ovevrride TCastleButton.DoClick).

Hierarchy

Overview

Fields

Public nested const DefaultImageMargin = 10;
Public nested const DefaultPaddingHorizontal = 10;
Public nested const DefaultPaddingVertical = 10;
Public nested const DefaultLineSpacing = 2;
Public nested const DefaultTextAlignment = hpMiddle;

Methods

Protected procedure SetPressed(const Value: boolean); virtual;
Protected procedure UIScaleChanged; override;
Protected procedure PreferredSize(var PreferredWidth, PreferredHeight: Single); override;
Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;
Public procedure Render; override;
Public procedure GLContextOpen; override;
Public procedure GLContextClose; override;
Public function Press(const Event: TInputPressRelease): boolean; override;
Public function Release(const Event: TInputPressRelease): boolean; override;
Public function Motion(const Event: TInputMotion): boolean; override;
Public procedure FontChanged; override;
Public procedure VisibleChange(const Changes: TCastleUserInterfaceChanges; const ChangeInitiatedByChildren: boolean = false); override;
Public procedure EditorAllowResize(out ResizeWidth, ResizeHeight: Boolean; out Reason: String); override;
Public procedure DoClick; virtual;
Public procedure SetFocused(const Value: boolean); override;

Properties

Public property Image: TCastleImage read FImage write SetImage;
Public property OwnsImage: boolean read FOwnsImage write FOwnsImage default false;
Public property TintPressed : TCastleColor read FTintPressed write FTintPressed;
Public property TintDisabled: TCastleColor read FTintDisabled write FTintDisabled;
Public property TintFocused : TCastleColor read FTintFocused write FTintFocused;
Public property TintNormal : TCastleColor read FTintNormal write FTintNormal;
Public property CustomBackgroundPressed: TCastleImage read FCustomBackgroundPressed write SetCustomBackgroundPressed;
Public property OwnsCustomBackgroundPressed: boolean read FOwnsCustomBackgroundPressed write FOwnsCustomBackgroundPressed default false;
Public property CustomBackgroundDisabled: TCastleImage read FCustomBackgroundDisabled write SetCustomBackgroundDisabled;
Public property OwnsCustomBackgroundDisabled: boolean read FOwnsCustomBackgroundDisabled write FOwnsCustomBackgroundDisabled default false;
Public property CustomBackgroundFocused: TCastleImage read FCustomBackgroundFocused write SetCustomBackgroundFocused;
Public property OwnsCustomBackgroundFocused: boolean read FOwnsCustomBackgroundFocused write FOwnsCustomBackgroundFocused default false;
Public property CustomBackgroundNormal: TCastleImage read FCustomBackgroundNormal write SetCustomBackgroundNormal;
Public property OwnsCustomBackgroundNormal: boolean read FOwnsCustomBackgroundNormal write FOwnsCustomBackgroundNormal default false;
Public property CustomBackgroundCorners: TVector4Integer read FCustomBackgroundCorners write FCustomBackgroundCorners;
Public property CustomTextColor: TCastleColor read FCustomTextColor write FCustomTextColor;
Public property CustomColorPressed: TCastleColor read FCustomColorPressed write SetCustomColorPressed;
Public property CustomColorDisabled: TCastleColor read FCustomColorDisabled write SetCustomColorDisabled;
Public property CustomColorFocused: TCastleColor read FCustomColorFocused write SetCustomColorFocused;
Public property CustomColorNormal: TCastleColor read FCustomColorNormal write SetCustomColorNormal;
Published property MinImageWidth: Single read FMinImageWidth write FMinImageWidth default 0;
Published property MinImageHeight: Single read FMinImageHeight write FMinImageHeight default 0;
Published property TextAlignment: THorizontalPosition read FTextAlignment write SetTextAlignment default DefaultTextAlignment;
Published property LineSpacing: Single read FLineSpacing write SetLineSpacing default DefaultLineSpacing;
Published property Html: boolean read FHtml write SetHtml default false;
Published property CustomBackground: boolean read FCustomBackground write FCustomBackground default false;
Published property CustomTextColorUse: boolean read FCustomTextColorUse write FCustomTextColorUse;
Published property PaddingHorizontal: Single read FPaddingHorizontal write SetPaddingHorizontal default DefaultPaddingHorizontal;
Published property PaddingVertical: Single read FPaddingVertical write SetPaddingVertical default DefaultPaddingVertical;
Published property AutoSize: boolean read FAutoSize write SetAutoSize default true;
Published property AutoSizeWidth: boolean read FAutoSizeWidth write SetAutoSizeWidth default true;
Published property AutoSizeHeight: boolean read FAutoSizeHeight write SetAutoSizeHeight default true;
Published property MinWidth: Single read FMinWidth write SetMinWidth default 0;
Published property MinHeight: Single read FMinHeight write SetMinHeight default 0;
Published property OnClick: TNotifyEvent read FOnClick write FOnClick;
Published property Caption: string read FCaption write SetCaption;
Published property Toggle: boolean read FToggle write FToggle default false;
Published property Pressed: boolean read FPressed write SetPressed default false;
Published property ImageLayout: TCastleButtonImageLayout read FImageLayout write SetImageLayout default ilLeft;
Published property ImageAlphaTest: boolean read FImageAlphaTest write FImageAlphaTest default false;
Published property ImageMargin: Single read FImageMargin write SetImageMargin default DefaultImageMargin;
Published property Enabled: boolean read FEnabled write SetEnabled default true;
Published property EnableParentDragging: boolean read FEnableParentDragging write FEnableParentDragging default false;
Published property TintPressedPersistent: TCastleColorPersistent read FTintPressedPersistent;
Published property TintDisabledPersistent: TCastleColorPersistent read FTintDisabledPersistent;
Published property TintFocusedPersistent: TCastleColorPersistent read FTintFocusedPersistent;
Published property TintNormalPersistent: TCastleColorPersistent read FTintNormalPersistent;
Published property CustomTextColorPersistent: TCastleColorPersistent read FCustomTextColorPersistent;
Published property CustomColorPressedPersistent: TCastleColorPersistent read FCustomColorPressedPersistent;
Published property CustomColorDisabledPersistent: TCastleColorPersistent read FCustomColorDisabledPersistent;
Published property CustomColorFocusedPersistent: TCastleColorPersistent read FCustomColorFocusedPersistent;
Published property CustomColorNormalPersistent: TCastleColorPersistent read FCustomColorNormalPersistent;

Description

Fields

Public nested const DefaultImageMargin = 10;
 
Public nested const DefaultPaddingHorizontal = 10;
 
Public nested const DefaultPaddingVertical = 10;
 
Public nested const DefaultLineSpacing = 2;
 
Public nested const DefaultTextAlignment = hpMiddle;
 

Methods

Protected procedure SetPressed(const Value: boolean); virtual;
 
Protected procedure UIScaleChanged; override;
 
Protected procedure PreferredSize(var PreferredWidth, PreferredHeight: Single); override;
 
Public constructor Create(AOwner: TComponent); override;
 
Public destructor Destroy; override;
 
Public procedure Render; override;
 
Public procedure GLContextOpen; override;
 
Public procedure GLContextClose; override;
 
Public function Press(const Event: TInputPressRelease): boolean; override;
 
Public function Release(const Event: TInputPressRelease): boolean; override;
 
Public function Motion(const Event: TInputMotion): boolean; override;
 
Public procedure FontChanged; override;
 
Public procedure VisibleChange(const Changes: TCastleUserInterfaceChanges; const ChangeInitiatedByChildren: boolean = false); override;
 
Public procedure EditorAllowResize(out ResizeWidth, ResizeHeight: Boolean; out Reason: String); override;
 
Public procedure DoClick; virtual;

Called when user clicks the button. In this class, simply calls OnClick callback.

Public procedure SetFocused(const Value: boolean); override;
 

Properties

Public property Image: TCastleImage read FImage write SetImage;

Set this to non-nil to display an image on the button.

Public property OwnsImage: boolean read FOwnsImage write FOwnsImage default false;

Should we free the Image when you set another one or at destructor.

Public property TintPressed : TCastleColor read FTintPressed write FTintPressed;

Color tint when button is pressed (regardless if enabled or disabled). Opaque white by default.

Public property TintDisabled: TCastleColor read FTintDisabled write FTintDisabled;

Color tint when button is disabled (and not pressed). Opaque white by default.

Public property TintFocused : TCastleColor read FTintFocused write FTintFocused;

Color tint when button is focused. Opaque white by default.

Public property TintNormal : TCastleColor read FTintNormal write FTintNormal;

Color tint when button is enabled, but neither pressed nor focused. Opaque white by default.

Public property CustomBackgroundPressed: TCastleImage read FCustomBackgroundPressed write SetCustomBackgroundPressed;

Background image on the pressed button. See CustomBackground for details.

Public property OwnsCustomBackgroundPressed: boolean read FOwnsCustomBackgroundPressed write FOwnsCustomBackgroundPressed default false;

Should we free CustomBackgroundPressed image when you set another one or at destructor.

Public property CustomBackgroundDisabled: TCastleImage read FCustomBackgroundDisabled write SetCustomBackgroundDisabled;

Background image on the disabled button. See CustomBackground for details.

Public property OwnsCustomBackgroundDisabled: boolean read FOwnsCustomBackgroundDisabled write FOwnsCustomBackgroundDisabled default false;

Should we free CustomBackgroundDisabled image when you set another one or at destructor.

Public property CustomBackgroundFocused: TCastleImage read FCustomBackgroundFocused write SetCustomBackgroundFocused;

Background image on the focused button. See CustomBackground for details.

Public property OwnsCustomBackgroundFocused: boolean read FOwnsCustomBackgroundFocused write FOwnsCustomBackgroundFocused default false;

Should we free CustomBackgroundFocused image when you set another one or at destructor.

Public property CustomBackgroundNormal: TCastleImage read FCustomBackgroundNormal write SetCustomBackgroundNormal;

Background image on the normal button. See CustomBackground for details.

Public property OwnsCustomBackgroundNormal: boolean read FOwnsCustomBackgroundNormal write FOwnsCustomBackgroundNormal default false;

Should we free CustomBackgroundNormal image when you set another one or at destructor.

Public property CustomBackgroundCorners: TVector4Integer read FCustomBackgroundCorners write FCustomBackgroundCorners;

Corners used when rendering custom background images. See CustomBackground for details. Zero by default.

Public property CustomTextColor: TCastleColor read FCustomTextColor write FCustomTextColor;

Text color to use if CustomTextColorUse is True. Black by default, just like Theme.TextColor.

Public property CustomColorPressed: TCastleColor read FCustomColorPressed write SetCustomColorPressed;

Button colors used when CustomBackground is True, but CustomBackgroundXxx images (like CustomBackgroundNormal) are left unassigned.

By default they are all transparent black, so actually the button is completely transparent in this case.

They are affected by tint (see TintPressed, TintDisabled, TintFocused, TintNormal). The tint color is simply multiplied component-wise with these colors. By default all tint colors are opaque white, so the multiplication by tint actually doesn't change anything.

Public property CustomColorDisabled: TCastleColor read FCustomColorDisabled write SetCustomColorDisabled;
 
Public property CustomColorFocused: TCastleColor read FCustomColorFocused write SetCustomColorFocused;
 
Public property CustomColorNormal: TCastleColor read FCustomColorNormal write SetCustomColorNormal;
 
Published property MinImageWidth: Single read FMinImageWidth write FMinImageWidth default 0;

Auto-size routines (see AutoSize) may treat the image like always having at least these minimal sizes. Even if the Image is empty (Nil). This is useful when you have a row of buttons (typical for toolbar), and you want them to have the same height, and their captions to be displayed at the same level, regardless of their images sizes.

Published property MinImageHeight: Single read FMinImageHeight write FMinImageHeight default 0;
 
Published property TextAlignment: THorizontalPosition read FTextAlignment write SetTextAlignment default DefaultTextAlignment;

For multi-line Caption, the horizontal alignment of the lines.

Published property LineSpacing: Single read FLineSpacing write SetLineSpacing default DefaultLineSpacing;

For multi-line Caption, the extra spacing between lines. May also be negative to squeeze lines tighter.

Published property Html: boolean read FHtml write SetHtml default false;

Enable HTML tags in the Caption. This allows to easily change colors or use bold, italic text.

See the example examples/fonts/html_text.lpr and examples/fonts/html_text_demo.html for a demo of what HTML tags can do. See TCastleFont.PrintStrings documentation for a list of support HTML markup.

Note that to see the bold/italic font variants in the HTML markup, you need to set the font to be TFontFamily with bold/italic variants. See the example mentioned above, examples/fonts/html_text.lpr, for a code how to do it.

Published property CustomBackground: boolean read FCustomBackground write FCustomBackground default false;

Use custom background images. If True, we use properties

They are rendered as 3x3 images (see TGLImageCore.Draw3x3) with corners specified by CustomBackgroundCorners.

They are affected by tint (see TintPressed, TintDisabled, TintFocused, TintNormal).

Published property CustomTextColorUse: boolean read FCustomTextColorUse write FCustomTextColorUse;

Should we use custom text color in CustomTextColor instead of Theme.TextColor or Theme.DisabledTextColor.

Published property PaddingHorizontal: Single read FPaddingHorizontal write SetPaddingHorizontal default DefaultPaddingHorizontal;

Horizontal distance between text or Image and the button border.

Published property PaddingVertical: Single read FPaddingVertical write SetPaddingVertical default DefaultPaddingVertical;

Vertical distance between text or Image and the button border.

Published property AutoSize: boolean read FAutoSize write SetAutoSize default true;

When AutoSize is True (the default) then button sizes are automatically calculated when you change the Caption and Image. The calculated size takes into account the Caption text size (with current font), and Image size, plus some margin to make it look nice.

Width is auto-calculated only when AutoSize and AutoSizeWidth (otherwise we use Width, WidthFraction and similar properties). Likewise, Height is calculated only when AutoSize and AutoSizeHeight (otherwise we use Height, HeightFraction and similar properties). This way you can turn off auto-sizing in only one dimension if you want (and when you don't need such flexibility, leave AutoSizeWidth = AutoSizeHeight = True and control both by simple AutoSize).

If needed, you can query the resulting button size with the standard TCastleUserInterface methods like TCastleUserInterface.EffectiveWidth and TCastleUserInterface.EffectiveHeight. Note that they may not be available before the button is actually added to the container, and the container size is initialized (we need to know the size of container, for UI scaling to determine the font size).

Published property AutoSizeWidth: boolean read FAutoSizeWidth write SetAutoSizeWidth default true;
 
Published property AutoSizeHeight: boolean read FAutoSizeHeight write SetAutoSizeHeight default true;
 
Published property MinWidth: Single read FMinWidth write SetMinWidth default 0;

When auto-size is in effect, these properties may force a minimal width/height of the button. This is useful if you want to use auto-size (to make sure that the content fits inside), but you want to force filling some space.

Published property MinHeight: Single read FMinHeight write SetMinHeight default 0;
 
Published property OnClick: TNotifyEvent read FOnClick write FOnClick;
 
Published property Caption: string read FCaption write SetCaption;

Caption to display on the button. The text may be multiline (use the LineEnding or NL constants to mark newlines).

Published property Toggle: boolean read FToggle write FToggle default false;

Can the button be permanently pressed. Good for making a button behave like a checkbox, that is indicate a boolean state. When Toggle is True, you can set the Pressed property, and the clicks are visualized a little differently.

Published property Pressed: boolean read FPressed write SetPressed default false;

Is the button pressed down. If Toggle is True, you can read and write this property to set the pressed state.

When not Toggle, this property isn't really useful to you. The pressed state is automatically managed then to visualize user clicks. In this case, you can read this property, but you cannot reliably set it.

Published property ImageLayout: TCastleButtonImageLayout read FImageLayout write SetImageLayout default ilLeft;

Where the Image is drawn on a button.

Published property ImageAlphaTest: boolean read FImageAlphaTest write FImageAlphaTest default false;

If the image has alpha channel, should we render with alpha test (simple yes/no transparency) or alpha blending (smootly mix with background using full transparency).

Published property ImageMargin: Single read FImageMargin write SetImageMargin default DefaultImageMargin;

Distance between text and Image. Unused if Image not set.

Published property Enabled: boolean read FEnabled write SetEnabled default true;
 
Published property EnableParentDragging: boolean read FEnableParentDragging write FEnableParentDragging default false;

Enable to drag a parent control, for example to drag a TCastleScrollView that contains this button. To do this, you need to turn on TCastleScrollView.EnableDragging, and set EnableParentDragging=True on all buttons inside. In effect, buttons will cancel the click operation once you start dragging, which allows the parent to handle all the motion events for dragging.

Published property TintPressedPersistent: TCastleColorPersistent read FTintPressedPersistent;

TintPressed that can be visually edited in Castle Game Engine Editor, Lazarus and Delphi. Normal user code does not need to deal with this, instead read or write TintPressed directly.

See also
TintPressed
Color tint when button is pressed (regardless if enabled or disabled).
Published property TintDisabledPersistent: TCastleColorPersistent read FTintDisabledPersistent;

TintDisabled that can be visually edited in Castle Game Engine Editor, Lazarus and Delphi. Normal user code does not need to deal with this, instead read or write TintDisabled directly.

See also
TintDisabled
Color tint when button is disabled (and not pressed).
Published property TintFocusedPersistent: TCastleColorPersistent read FTintFocusedPersistent;

TintFocused that can be visually edited in Castle Game Engine Editor, Lazarus and Delphi. Normal user code does not need to deal with this, instead read or write TintFocused directly.

See also
TintFocused
Color tint when button is focused.
Published property TintNormalPersistent: TCastleColorPersistent read FTintNormalPersistent;

TintNormal that can be visually edited in Castle Game Engine Editor, Lazarus and Delphi. Normal user code does not need to deal with this, instead read or write TintNormal directly.

See also
TintNormal
Color tint when button is enabled, but neither pressed nor focused.
Published property CustomTextColorPersistent: TCastleColorPersistent read FCustomTextColorPersistent;

CustomTextColor that can be visually edited in Castle Game Engine Editor, Lazarus and Delphi. Normal user code does not need to deal with this, instead read or write CustomTextColor directly.

See also
CustomTextColor
Text color to use if CustomTextColorUse is True.
Published property CustomColorPressedPersistent: TCastleColorPersistent read FCustomColorPressedPersistent;

CustomColorPressed that can be visually edited in Castle Game Engine Editor, Lazarus and Delphi. Normal user code does not need to deal with this, instead read or write CustomColorPressed directly.

See also
CustomColorPressed
Button colors used when CustomBackground is True, but CustomBackgroundXxx images (like CustomBackgroundNormal) are left unassigned.
Published property CustomColorDisabledPersistent: TCastleColorPersistent read FCustomColorDisabledPersistent;

CustomColorDisabled that can be visually edited in Castle Game Engine Editor, Lazarus and Delphi. Normal user code does not need to deal with this, instead read or write CustomColorDisabled directly.

See also
CustomColorDisabled
Published property CustomColorFocusedPersistent: TCastleColorPersistent read FCustomColorFocusedPersistent;

CustomColorFocused that can be visually edited in Castle Game Engine Editor, Lazarus and Delphi. Normal user code does not need to deal with this, instead read or write CustomColorFocused directly.

See also
CustomColorFocused
Published property CustomColorNormalPersistent: TCastleColorPersistent read FCustomColorNormalPersistent;

CustomColorNormal that can be visually edited in Castle Game Engine Editor, Lazarus and Delphi. Normal user code does not need to deal with this, instead read or write CustomColorNormal directly.

See also
CustomColorNormal

Generated by PasDoc 0.15.0.