Class TCastleNotifications

Unit

Declaration

type TCastleNotifications = class(TCastleUserInterfaceFont)

Description

Notifications displayed on the screen. Each message disappears after a short time. Suitable for game messages like "Picked up 20 ammo". Call Show to display a message.

This is a TCastleUserInterface descendant, so to use it — just add it to TCastleWindow.Controls or TCastleControl.Controls. Use TCastleUserInterface anchors to automatically position it on the screen, for example:

Notifications := TCastleNotifications.Create(Owner);
Notifications.Anchor(hpMiddle);
Notifications.Anchor(vpMiddle);
Notifications.TextAlignment := hpMiddle; // looks best, when anchor is also in the middle

Hierarchy

Overview

Fields

Public nested const DefaultMaxMessages = 4;
Public nested const DefaultTimeout = 5.0;
Public nested const DefaultFade = 1.0;

Methods

Protected procedure PreferredSize(var PreferredWidth, PreferredHeight: Single); override;
Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;
Public procedure Show(const s: string); overload;
Public procedure Show(s: TStringList); overload;
Public procedure Clear;
Public procedure Update(const SecondsPassed: Single; var HandleInput: boolean); override;
Public procedure Render; override;
Public function PropertySections(const PropertyName: String): TPropertySections; override;

Properties

Public property Color: TCastleColor read FColor write FColor;
Public property History: TCastleStringList read FHistory;
Published property MaxMessages: integer read FMaxMessages write FMaxMessages default DefaultMaxMessages;
Published property Timeout: Single read FTimeout write FTimeout default DefaultTimeout;
Published property Fade: Single read FFade write FFade default DefaultFade;
Published property CollectHistory: boolean read FCollectHistory write FCollectHistory default false;
Published property TextAlignment: THorizontalPosition read FTextAlignment write FTextAlignment default hpLeft;
Published property DesignTestMessagesInterval: Single read FDesignTestMessagesInterval write FDesignTestMessagesInterval default 1;
Published property Wrap: Boolean read FWrap write FWrap default true;
Published property ColorPersistent: TCastleColorPersistent read FColorPersistent ;

Description

Fields

Public nested const DefaultMaxMessages = 4;

This item has no description.

Public nested const DefaultTimeout = 5.0;

This item has no description.

Public nested const DefaultFade = 1.0;

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.

Public constructor Create(AOwner: TComponent); override;

This item has no description.

Public destructor Destroy; override;

This item has no description.

Public procedure Show(const s: string); overload;

Show new message. An overloaded version that takes a single string will detect newlines in the string automatically so a message may be multi-line. The messages will be automatically broken to fit on the screen width with given font.

Public procedure Show(s: TStringList); overload;

This item has no description.

Public procedure Clear;

Clear all messages.

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 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 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 Color: TCastleColor read FColor write FColor;

Color used to draw subsequent messages. Default value is white.

Public property History: TCastleStringList read FHistory;

All the messages passed to Show, collected only if CollectHistory. May be Nil when not CollectHistory.

Published property MaxMessages: integer read FMaxMessages write FMaxMessages default DefaultMaxMessages;

How many message lines should be visible on the screen, at maximum.

Published property Timeout: Single read FTimeout write FTimeout default DefaultTimeout;

How long a given message should be visible on the screen, in seconds. Message stops being visible when this timeout passed, or when we need more space for new messages (see MaxMessages).

Note that the Fade time is already included in this value, so a message is normally visible only for the Timeout - Fade seconds, and then it starts fading out.

Published property Fade: Single read FFade write FFade default DefaultFade;

This item has no description.

Published property CollectHistory: boolean read FCollectHistory write FCollectHistory default false;

Turn this on to have all the messages you pass to Show be collected inside History string list. History is expanded by Show, it is cleared by Clear, just like the notifications on screen. However, unlike the visible messages, it has unlimited size (messages there are not removed when MaxMessages or Timeout take action), and messages inside are not broken to honour screen width.

This is useful if you want to show the player a history of messages (in case they missed the message in game).

Published property TextAlignment: THorizontalPosition read FTextAlignment write FTextAlignment default hpLeft;

Alignment of the text inside.

Published property DesignTestMessagesInterval: Single read FDesignTestMessagesInterval write FDesignTestMessagesInterval default 1;

In design mode (within CGE editor) we can spawn test messages (so you can see how the notifications look). This property determines how often we do it. 0 means to not do it.

Published property Wrap: Boolean read FWrap write FWrap default true;

Wrap messages to fit in parent width. This is usually nice for display, but it may cause problems when parent size depends on child (e.g. because parent uses TCastleUserInterface.AutoSizeToChildren), because then child size also depends on parent, and parent would never grow.

Published property ColorPersistent: TCastleColorPersistent read FColorPersistent ;

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

See also
Color
Color used to draw subsequent messages.

Generated by PasDoc 0.16.0-snapshot.