Class TCastleEdit

Unit

Declaration

type TCastleEdit = class(TCastleUserInterfaceFont)

Description

Edit box to input a single line of text. The contents are in the Text property, you can get or set them at any time.

Note that you should set a suitable TCastleUserInterface.Width of the edit box, to nicely display a typical content. The height is by default auto-calculated (see AutoSizeHeight) looking at font size (and other properties, like padding and frame size), and usually is reasonable automatically.

Hierarchy

Overview

Fields

Published nested const DefaultPadding = 4;
Published nested const DefaultAutoOnScreenKeyboard = false;

Methods

Protected procedure PreferredSize(var PreferredWidth, PreferredHeight: Single); override;
Protected function GetInternalText: String; override;
Protected procedure SetInternalText(const Value: String); override;
Protected procedure DoChange; virtual;
Protected procedure TranslateProperties(const TranslatePropertyEvent: TTranslatePropertyEvent); override;
Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;
Public procedure Render; override;
Public function Press(const Event: TInputPressRelease): boolean; override;
Public procedure Update(const SecondsPassed: Single; var HandleInput: boolean); override;
Public function CapturesEventsAtPosition(const Position: TVector2): boolean; override;
Public procedure SetFocused(const Value: boolean); override;
Public procedure EditorAllowResize( out ResizeWidth, ResizeHeight: Boolean; out Reason: String); override;
Public function PropertySections(const PropertyName: String): TPropertySections; override;

Properties

Public property FocusedColor: TCastleColor read FFocusedColor write SetFocusedColor;
Public property UnfocusedColor: TCastleColor read FUnfocusedColor write SetUnfocusedColor;
Public property PlaceholderColor: TCastleColor read FPlaceholderColor write SetPlaceholderColor;
Public property BackgroundColor: TCastleColor read FBackgroundColor write SetBackgroundColor;
Public property AllowedChars: TSetOfChars read FAllowedChars write FAllowedChars;
Public property MaxLength: Cardinal read FMaxLength write FMaxLength;
Published property Text: String read FText write SetText;
Published property PaddingHorizontal: Single read FPaddingHorizontal write SetPaddingHorizontal default 0;
Published property PaddingVertical: Single read FPaddingVertical write SetPaddingVertical default 0;
Published property Padding: Single read FPadding write SetPadding default DefaultPadding;
Published property Frame: boolean read FFrame write SetFrame default true;
Published property CaptureAllInput: boolean read FCaptureAllInput write FCaptureAllInput; deprecated 'use Container.ForceCaptureInput instead of this';
Published property AutoOnScreenKeyboard: Boolean read FAutoOnScreenKeyboard write FAutoOnScreenKeyboard default DefaultAutoOnScreenKeyboard;
Published property AutoSizeHeight: Boolean read FAutoSizeHeight write SetAutoSizeHeight default true;
Published property Placeholder: String read FPlaceholder write SetPlaceholder;
Published property OnChange: TNotifyEvent read FOnChange write FOnChange;
Published property PasswordChar: Char read FPasswordChar write SetPasswordChar default #0;
Published property TextTranslate: Boolean read FTextTranslate write FTextTranslate default true;
Published property PlaceholderTranslate: Boolean read FPlaceholderTranslate write FPlaceholderTranslate default true;
Published property Alignment: THorizontalPosition read FAlignment write SetAlignment default hpLeft;
Published property Enabled: boolean read FEnabled write SetEnabled default true;
Published property FocusedColorPersistent: TCastleColorPersistent read FFocusedColorPersistent ;
Published property UnfocusedColorPersistent: TCastleColorPersistent read FUnfocusedColorPersistent ;
Published property PlaceholderColorPersistent: TCastleColorPersistent read FPlaceholderColorPersistent ;
Published property BackgroundColorPersistent: TCastleColorPersistent read FBackgroundColorPersistent ;

Description

Fields

Published nested const DefaultPadding = 4;

This item has no description.

Published nested const DefaultAutoOnScreenKeyboard = false;

This item has no description.

Methods

Protected procedure PreferredSize(var PreferredWidth, PreferredHeight: Single); override;

This item has no description. Showing description inherited from TCastleUserInterface.PreferredSize.

Controls that have a preferred size should override this. By default this contains values derived from Width, WidthFraction, Height, HeightFraction, with Border subtracted.

Note that the arguments should be already scaled, i.e. multiplied by UIScale, i.e. expressed in final device pixels.

Note that the returned PreferredWidth and PreferredHeight must not include the space for Border. Border size will be added later.

Protected function GetInternalText: String; override;

This item has no description.

Protected procedure SetInternalText(const Value: String); override;

This item has no description.

Protected procedure DoChange; virtual;

This item has no description.

Protected procedure TranslateProperties(const TranslatePropertyEvent: TTranslatePropertyEvent); override;

This item has no description. Showing description inherited from TCastleComponent.TranslateProperties.

Enumerate all properties that are possible to translate in this component. E.g. in TCastleLabel it will return TCastleLabel.Caption, in TCastleEdit it will return TCastleEdit.Text and TCastleEdit.Placeholder.

Returns only non-empty properties, thus assuming that if current (by convention, English) text is empty, then there is no point in translating it. Moreover descendants may define boolean properties to exclude particular text from translating, e.g. TCastleLabel.CaptionTranslate, TCastleEdit.TextTranslate, TCastleEdit.PlaceholderTranslate.

It is not recursive (it doesn't enumerate children properties). Use global TranslateProperties procedure to call this on a hierarchy of TComponent.

You usually don't want to call this method (it is called by other engine routines). But you may find it useful to override this, if you define new component.

Public constructor Create(AOwner: TComponent); override;

This item has no description.

Public destructor Destroy; override;

This item has no description.

Public procedure Render; override;

This item has no description. Showing description inherited from TCastleUserInterface.Render.

Render a control. Called only when Exists and render context is initialized.

Do not call this method. It will be automatically called by the engine when needed. It will be called when UI is part of TCastleContainer.Controls list or rendered (e.g. for off-screen rendering) by TCastleContainer.RenderControl.

You should only override this method.

See https://castle-engine.io/manual_2d_ui_custom_drawn.php for examples what you can put here.

You can depend on some OpenGL state being set before calling this method. You can depend on it being set, and you can carelessly change it. This state we set:

  • Viewport is set to include whole container.

  • Depth test is off.

  • For ancient fixed-function pipeline (see TGLFeatures.RequestCapabilities):

    • The 2D orthographic projection is always set at the beginning. Useful for 2D controls.

    • The modelview matrix is set to identity. The matrix mode is always modelview.

    • The raster position is set to (0,0). The (deprecated) WindowPos is also set to (0,0).

    • Texturing, lighting, fog is off.

Beware that GLSL RenderContext.CurrentProgram has undefined value when this is called. You should always set it, before making direct OpenGL drawing calls (all the engine drawing routines do it already, this is only a concern if you make direct OpenGL / OpenGLES calls).

Public function Press(const Event: TInputPressRelease): boolean; override;

This item has no description. Showing description inherited from TCastleUserInterface.Press.

Override this method to react to user pressing a key, mouse button or mouse wheel. Return True if the event was handled, which prevents from passing this event to other UI controls.

When implementing in descendants it is best to override it like this:

function TMyControl.Press(const Event: TInputPressRelease): boolean;
begin
  Result := inherited;
  if Result then Exit; // exit if ancestor already handled this event

  if Event.IsKey(keyEnter) then
  begin
    // do something in reaction to Enter key
    ...
    // let engine know that this input event was handled
    Exit(true);
  end;

  if Event.IsMouseButton(buttonLeft) then
  begin
    // do something in reaction to left mouse button press
    ...
    // let engine know that this input event was handled
    Exit(true);
  end;
end;

These events are generated for all UI controls, whether they are considered "interactive" or not. These events are generated for non-interactive controls like TCastleRectangleControl or TCastleLabel as well. For example, these events ignore the TCastleButton.Enabled state, they are generated always (see https://github.com/castle-engine/castle-engine/issues/413 ). Use instead TCastleButton.OnClick to detect clicks on a button in a way that honors the TCastleButton.Enabled state.

When a control returns True from Press, it means it starts to "capture" subsequent mouse events: subsequent mouse moves and release will be send to this control even if mouse will move outside of this control.

The events Press and Release are passed to the parent only after the children had a chance to process this event. Overriding them makes sense if you draw something that "looks clickable" in TCastleUserInterface.Render, which is the standard place you should draw stuff. For example our TCastleButton draws there.

In contrast, the events PreviewPress and PreviewRelease are passed first to the parent control, before children have a chance to process this event. In partcular, overriding them makes sense if you draw something that "looks clickable" in TCastleUserInterface.RenderOverChildren.

Public procedure Update(const SecondsPassed: Single; var HandleInput: boolean); override;

This item has no description. Showing description inherited from TCastleUserInterface.Update.

Control may do here anything that must be continuously repeated. E.g. camera handles here falling down due to gravity, rotating model in Examine mode, and many more.

This method may be used, among many other things, to continuously react to the fact that user pressed some key (or mouse button). For example, if holding some key should move some 3D object, you should do something like:

if HandleInput then
begin
  if Container.Pressed[keyArrowRight] then
    Transform.Position := Transform.Position + Vector3(SecondsPassed * 10, 0, 0);
  HandleInput := false;
end;

Instead of directly using a key code, consider also using TInputShortcut that makes the input key nicely configurable. See engine tutorial about handling inputs.

Multiplying movement by SecondsPassed makes your operation frame-rate independent. Object will move by 10 units in a second, regardless of how many FPS your game has.

The code related to HandleInput is important if you write a generally-useful control that should nicely cooperate with all other controls, even when placed on top of them or under them. The correct approach is to only look at pressed keys/mouse buttons if HandleInput is True. Moreover, if you did check that HandleInput is True, and you did actually handle some keys, then you have to set HandleInput := false. This will prevent the other controls (behind the current control) from handling the keys (they will get HandleInput = False). And this is important to avoid doubly-processing the same key press, e.g. if two controls react to the same key, only the one on top should process it.

Note that to handle a single press / release (like "switch light on when pressing a key") you should rather use Press and Release methods. Use this method only for continuous handling (like "holding this key makes the light brighter and brighter").

To understand why such HandleInput approach is needed, realize that the "Update" events are called differently than simple mouse and key events like "Press" and "Release". "Press" and "Release" events return whether the event was somehow "handled", and the container passes them only to the controls under the mouse (decided by TCastleUserInterface.CapturesEventsAtPosition). And as soon as some control says it "handled" the event, other controls (even if under the mouse) will not receive the event.

This approach is not suitable for Update events. Some controls need to do the Update job all the time, regardless of whether the control is under the mouse and regardless of what other controls already did. So all controls (well, all controls that exist, in case of TCastleUserInterface, see TCastleUserInterface.Exists) receive Update calls.

So the "handled" status is passed through HandleInput. If a control is not under the mouse, it will receive HandleInput = False. If a control is under the mouse, it will receive HandleInput = True as long as no other control on top of it didn't already change it to False.

Public function CapturesEventsAtPosition(const Position: TVector2): boolean; override;

This item has no description. Showing description inherited from TCastleUserInterface.CapturesEventsAtPosition.

Does this control capture events under this container position. The default implementation simply checks whether Position is inside RenderRect. It also checks whether CapturesEvents is True.

Always treated like False when Exists returns False, so the implementation of this method only needs to make checks assuming that Exists = True.

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

This item has no description. Showing description inherited from TCastleUserInterface.SetFocused.

Called when this control becomes or stops being focused, that is: under the mouse cursor and will receive events.

This updates Focused property. This also calls OnInternalMouseEnter / OnInternalMouseLeave.

Public procedure EditorAllowResize( out ResizeWidth, ResizeHeight: Boolean; out Reason: String); override;

This item has no description. Showing description inherited from TCastleUserInterface.EditorAllowResize.

Override this to prevent resizing some dimension in CGE editor.

Public function PropertySections(const PropertyName: String): TPropertySections; override;

This item has no description. Showing description inherited from TCastleComponent.PropertySections.

Section where to show property in the editor.

Properties

Public property FocusedColor: TCastleColor read FFocusedColor write SetFocusedColor;

Focused text color. By default it's black.

Public property UnfocusedColor: TCastleColor read FUnfocusedColor write SetUnfocusedColor;

Unfocused text color. By default it's dark gray.

Public property PlaceholderColor: TCastleColor read FPlaceholderColor write SetPlaceholderColor;

Color for Placeholder. By default it's light gray.

Public property BackgroundColor: TCastleColor read FBackgroundColor write SetBackgroundColor;

Background color. Fills the area under Text and the padding. By default it's white. Note that it can be transparent, in which case it will show the tiEdit image underneath (if Frame is True), or UI control underneath (if Frame is False).

Public property AllowedChars: TSetOfChars read FAllowedChars write FAllowedChars;

Allowed characters that user can input. Note that this only restricts the user input, it does not prevent from programmatically setting Text to include disallowed characters.

Public property MaxLength: Cardinal read FMaxLength write FMaxLength;

Max length of user input. Value of 0 (default) means "no limit". Note that this only restricts the user input, it does not prevent from programmatically setting Text to be longer.

Published property Text: String read FText write SetText;

Currently input text.

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

Inside the box rectangle, padding between the borders (or frame, if Frame) and text. Total horizontal padding is the sum PaddingHorizontal + Padding, total vertical padding is the sum PaddingVertical + Padding.

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

This item has no description.

Published property Padding: Single read FPadding write SetPadding default DefaultPadding;

This item has no description.

Published property Frame: boolean read FFrame write SetFrame default true;

Draw frame around the box. Frame uses theme image tiEdit, see TCastleTheme.Images if you want to customize it.

Published property CaptureAllInput: boolean read FCaptureAllInput write FCaptureAllInput; deprecated 'use Container.ForceCaptureInput instead of this';

Warning: this symbol is deprecated: use Container.ForceCaptureInput instead of this

Should we capture input regardless of the currently focused control. This is in practice only sensible if this is the only edit box currently visible on the screen.

Published property AutoOnScreenKeyboard: Boolean read FAutoOnScreenKeyboard write FAutoOnScreenKeyboard default DefaultAutoOnScreenKeyboard;

Shows the software (on-screen) keyboard on mobile devices automatically when the edit box gets focused.

For now, this only works on Android (not iOS yet – see https://github.com/castle-engine/castle-engine/issues/554).

This requires adding <service name="keyboard" /> to the Android services in CastleEngineManifest.xml. See example examples/mobile/on_screen_keyboard and the Android service documentation for keyboard service.

Published property AutoSizeHeight: Boolean read FAutoSizeHeight write SetAutoSizeHeight default true;

This item has no description.

Published property Placeholder: String read FPlaceholder write SetPlaceholder;

Displayed when Text is empty.

Published property OnChange: TNotifyEvent read FOnChange write FOnChange;

Event sent when Text value was changed by a user. Note that this is not called when you change Text property programmatically.

Published property PasswordChar: Char read FPasswordChar write SetPasswordChar default #0;

Show given character (usually "*") instead of actual input characters. Useful for password input fields.

Setting the PasswordChar to something else than #0 also informs the system that the input is sensitive (e.g. it is a password) and should not be stored in any system-wide dictionary for easy future reuse. This is meaningful for on-screen keyboards on mobile systems, that by default (when PasswordChar is #0) may store entered text in some system-wide dictionary and propose user to use the same words in future inputs. If the user inputs something sensitive (like a password) you want to disable this using PasswordChar <> #0.

Published property TextTranslate: Boolean read FTextTranslate write FTextTranslate default true;

Should the Text be localized (translated into other languages). Determines if the property is enumerated by TCastleComponent.TranslateProperties, which affects the rest of localization routines.

Published property PlaceholderTranslate: Boolean read FPlaceholderTranslate write FPlaceholderTranslate default true;

Should the Placeholder be localized (translated into other languages). Determines if the property is enumerated by TCastleComponent.TranslateProperties, which affects the rest of localization routines.

Published property Alignment: THorizontalPosition read FAlignment write SetAlignment default hpLeft;

Horizontal alignment of the text.

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

Enabled control can be focused and edited, is not grayed-out.

Published property FocusedColorPersistent: TCastleColorPersistent read FFocusedColorPersistent ;

FocusedColor 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 FocusedColor directly.

See also
FocusedColor
Focused text color.
Published property UnfocusedColorPersistent: TCastleColorPersistent read FUnfocusedColorPersistent ;

UnfocusedColor 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 UnfocusedColor directly.

See also
UnfocusedColor
Unfocused text color.
Published property PlaceholderColorPersistent: TCastleColorPersistent read FPlaceholderColorPersistent ;

PlaceholderColor 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 PlaceholderColor directly.

See also
PlaceholderColor
Color for Placeholder.
Published property BackgroundColorPersistent: TCastleColorPersistent read FBackgroundColorPersistent ;

BackgroundColor 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 BackgroundColor directly.

See also
BackgroundColor
Background color.

Generated by PasDoc 0.16.0-snapshot.