Class TCastleButton

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

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.

This item has no description.

This item has no description.

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.

This item has no description.

This item has no description.

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

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.

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

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

This is counterpart to Press method. See Press for more details.

Note: We'd like this method to also be called when user releases a mouse wheel. But currently releasing of the mouse wheel is not reported now by any backend. Only releasing of keys and mouse buttons is reported.

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

Motion of mouse or touch.

This item has no description. Showing description inherited from TCastleUserInterfaceFont.FontChanged.

Force considering font changed (font instance, or glyphs, or sizes changed).

Usually, you don't need to call this explicitly from the outside. Changing font, like CustomFont or TCastleContainer.DefaultFont or UIFont, or any property that may affect the font is automatically applied.

But there are exceptions: right now, if you call Load on a font, it's measurements will change but some controls using it will not recalculate sizes automatically. In this case, call this method.

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.

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

Called always when something important inside this control (or it's children) changed. To be more precise, this is called when something mentioned among the TCastleUserInterfaceChange enumerated items changed.

This is always called with Changes <> [] (non-empty set).

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

Override this to prevent resizing some dimension in CGE editor.

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

Section where to show property in the editor.

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

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.

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

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

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

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

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

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

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.

This item has no description.

This item has no description.

This item has no description.

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.

This item has no description.

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

Horizontal alignment of the text+image within button area, useful in case you don't use AutoSize.

We align text+image within the available area inside the button (which is determined by button size, without paddings determined by PaddingHorizontal, PaddingVertical).

Vertical alignment of the text+image within button area, useful in case you don't use AutoSize.

We align text+image within the available area inside the button (which is determined by button size, without paddings determined by PaddingHorizontal, PaddingVertical).

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

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 TCastleAbstractFont.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 TCastleFontFamily with bold/italic variants. See the example mentioned above, examples/fonts/html_text.lpr, for a code how to do it.

Use custom background images. If True, we use properties

• CustomBackgroundPressed (or fallback on CustomBackgroundNormal if empty),

• CustomBackgroundDisabled (or fallback on CustomBackgroundNormal if empty),

• CustomBackgroundFocused (or fallback on CustomBackgroundNormal if empty),

• CustomBackgroundNormal (or fallback on solid color if empty, see CustomColorPressed, see CustomColorNormal and so on).

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

Optional image displayed on the button.

Scaling of Image.

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

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

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

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

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

Horizontal distance between text or Image and the button border.

Vertical distance between text or Image and the button border.

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

This item has no description.

This item has no description.

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.

This item has no description.

This item has no description.

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

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

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.

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.

Where the Image is drawn on a button.

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

Enabled button can be focused and clicked, is not grayed-out.

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.

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

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

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.

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.

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.

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

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

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

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