Unit CastleMessages

Description
Uses
Functions and Procedures
Types
Constants
Variables

Description

Dialog windows (asking user for confirmation, question, simple text input and such) displayed within an OpenGL context (TCastleWindow).

These routines are comfortable to use, as they return only when the user actually confirmed / made a decision. So you can write code like this: 

if MessageYesNo(Window, 'Are you sure you want to delete this file?') then
  DeleteFile(...);

Features:

  • All the MessageXxx routines display a modal dialog. They return only when the user accepted / answered the dialog box. This way they are comfortable to use anywhere in your program.

  • MessageInputXxx family of functions ask user to enter some text.

  • All the dialog boxes have vertical scroll bar, displayed when needed. So it's OK to use really long text. Scroll bar can be operated with keys (up/down, ctrl+up/down, page up/down, home/end) and mouse (drag the scroll bar, or click below/above it).

  • Long text lines are automatically broken. So it's OK to use text with long lines. We will try to break text only at whitespace.

    If you pass a text as a single string parameter, then our "line breaking" works correctly even for text that already contains newline characters (they are correctly recognized as forcing line break).

    If you pass a text as an "array of string" or TStringList, it's expected that strings inside don't contain newline characters anymore. It's undefined what will happen (i.e. whether they will be correctly broken) otherwise. Of course, TStringList contents used to pass text to MessageXxx will never be modified in any way.

  • User is allowed to resize the window while MessageXxx works. (As long as TCastleWindow.ResizeAllowed = raAllowed, of course.) Long lines are automatically broken taking into account current window width.

  • You can configure dialog boxes look using TCastleTheme. Various parts of the dialog use scaled images. This way you can change the border, background of the dialog, you can also make the dialog box partially transparent.

Call MessageXxx functions only when Window.Closed = false.

Notes about implementation:

  • We temporary replace normal window callbacks and controls using TGLMode. This allows you to call MessageXxx procedures in any place of your program, and things will just work, the MessageXxx will return only once user answers the dialog box.

  • If you use ApplicationProperties.OnUpdate:

    As these events are not tied to a particular window, they continue to work even while we're inside MessageXxx procedure. Be sure to implement them such that they make sense also when we're inside a dialog box.

    In particular, remember that you cannot close the Window when the message box in running. So do not call TCastleWindow.Close from ApplicationProperties.OnUpdate callbacks, at least not without checking whether we're not inside a dialog box.

Warning: Most routines from this unit cannot work on iOS and web platforms, as they don't support Application.ProcessMessage. There is a workaround for MessageOK (see MessageOKPushesView variable), but it doesn't work for other routines like MessageYesNo, so ultimately we advise to just not use this unit at all on iOS and web, and instead use TCastleView-based dialogs from CastleDialogViews unit.

Source: window/castlemessages.pas (line 100).

Uses

Overview

Functions and Procedures

procedure MessageOK(Window: TCastleWindow; const s: string; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false); overload;
procedure MessageOK(Window: TCastleWindow; const SArray: array of string; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false); overload;
procedure MessageOK(Window: TCastleWindow; TextList: TStringList; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false); overload;
function MessageInput(Window: TCastleWindow; const s: string; const answerDefault: string = ''; const MinLength: integer = 0; const MaxLength: integer = 0; const AllowedChars: TSetOfChars = AllChars; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): string; overload;
function MessageInput(Window: TCastleWindow; TextList: TStringList; const answerDefault: string = ''; const MinLength: integer = 0; const MaxLength: integer = 0; const AllowedChars: TSetOfChars = AllChars; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): string; overload;
function MessageInputQuery(Window: TCastleWindow; const s: string; var Answer: string; const MinLength: integer = 0; const MaxLength: integer = 0; const AllowedChars: TSetOfChars = AllChars; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean; overload;
function MessageInputQuery(Window: TCastleWindow; TextList: TStringList; var Answer: string; const MinLength: integer = 0; const MaxLength: integer = 0; const AllowedChars: TSetOfChars = AllChars; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean; overload;
function MessageChoice(Window: TCastleWindow; const s: string; const ButtonCaptions: array of string; const ButtonChars: array of char; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false; const AllowCancel: boolean = false): char; overload;
function MessageChoice(Window: TCastleWindow; const SArray: array of string; const ButtonCaptions: array of string; const ButtonChars: array of char; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false; const AllowCancel: boolean = false): char; overload;
function MessageChoice(Window: TCastleWindow; TextList: TStringList; const ButtonCaptions: array of string; const ButtonChars: array of char; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false; const AllowCancel: boolean = false): char; overload;
function MessageKey(Window: TCastleWindow; const S: string; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): TKey; overload;
function MessageKey(Window: TCastleWindow; const SArray: array of string; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): TKey; overload;
function MessageKey(Window: TCastleWindow; TextList: TStringList; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): TKey; overload;
procedure MessageKeyMouse(Window: TCastleWindow; const S: string; out Event: TInputPressRelease; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false); overload; deprecated 'use the function form of MessageKeyMouse';
procedure MessageKeyMouse(Window: TCastleWindow; TextList: TStringList; out Event: TInputPressRelease; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false); overload; deprecated 'use the function form of MessageKeyMouse';
function MessageKeyMouse(Window: TCastleWindow; const S: string; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): TInputPressRelease; overload;
function MessageKeyMouse(Window: TCastleWindow; TextList: TStringList; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): TInputPressRelease; overload;
function MessageYesNo(Window: TCastleWindow; const s: string; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean; overload;
function MessageYesNo(Window: TCastleWindow; const SArray: array of string; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean; overload;
function MessageYesNo(Window: TCastleWindow; TextList: TStringList; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean; overload;
function MessageInputCardinal(Window: TCastleWindow; const s: string; const AnswerDefault: string; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): Cardinal; overload;
function MessageInputCardinal(Window: TCastleWindow; const s: string; const AnswerDefault: Cardinal; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): Cardinal; overload;
function MessageInputQueryCardinal(Window: TCastleWindow; const Title: string; var Value: Cardinal; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean;
function MessageInputQueryCardinalHex(Window: TCastleWindow; const Title: string; var Value: Cardinal; const MaxWidth: Cardinal; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean;
function MessageInputQuery(Window: TCastleWindow; const Title: string; var Value: Extended; const ValueAsString: string = ''; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean; overload;
function MessageInputQuery(Window: TCastleWindow; const Title: string; var Value: Single; const ValueAsString: string = ''; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean; overload;
function MessageInputQueryVector3( Window: TCastleWindow; const Title: string; var Value: TVector3; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean;
function MessageInputQueryVector4( Window: TCastleWindow; const Title: string; var Value: TVector4; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean;

Types

TTextAlign = THorizontalPosition deprecated;

Constants

DefaultAlign = hpLeft;
taRight = hpRight deprecated;
taMiddle = hpMiddle deprecated;
taLeft = hpLeft deprecated;

Variables

MessageOKPushesView: boolean;

Description

Functions and Procedures

procedure MessageOK(Window: TCastleWindow; const s: string; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false); overload;

Ask user for simple confirmation. This is the simplest "OK" dialog box.

Source: window/castlemessages.pas (line 123).

procedure MessageOK(Window: TCastleWindow; const SArray: array of string; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false); overload;

This item has no description.

Source: window/castlemessages.pas (line 126).

procedure MessageOK(Window: TCastleWindow; TextList: TStringList; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false); overload;

This item has no description.

Source: window/castlemessages.pas (line 129).

function MessageInput(Window: TCastleWindow; const s: string; const answerDefault: string = ''; const MinLength: integer = 0; const MaxLength: integer = 0; const AllowedChars: TSetOfChars = AllChars; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): string; overload;

Ask user to input a string. User must give an answer (there is no "Cancel" button), use MessageInputQuery if you want a version with "Cancel" button.

Parameters
AnswerMaxLen
0 (zero) means that there's no maximum answer length.

Source: window/castlemessages.pas (line 140).

function MessageInput(Window: TCastleWindow; TextList: TStringList; const answerDefault: string = ''; const MinLength: integer = 0; const MaxLength: integer = 0; const AllowedChars: TSetOfChars = AllChars; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): string; overload;

This item has no description.

Source: window/castlemessages.pas (line 147).

function MessageInputQuery(Window: TCastleWindow; const s: string; var Answer: string; const MinLength: integer = 0; const MaxLength: integer = 0; const AllowedChars: TSetOfChars = AllChars; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean; overload;

Ask user to input a string, or cancel. Returns True and sets Answer if user accepted some text. Note that initial Answer value is the answer proposed to the user.

Parameters
AnswerMaxLen
0 (zero) means that there's no maximum answer length.

Source: window/castlemessages.pas (line 162).

function MessageInputQuery(Window: TCastleWindow; TextList: TStringList; var Answer: string; const MinLength: integer = 0; const MaxLength: integer = 0; const AllowedChars: TSetOfChars = AllChars; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean; overload;

This item has no description.

Source: window/castlemessages.pas (line 169).

function MessageChoice(Window: TCastleWindow; const s: string; const ButtonCaptions: array of string; const ButtonChars: array of char; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false; const AllowCancel: boolean = false): char; overload;

Ask user to choose one option from many. ButtonCaptions contain a list of button captions.

ButtonChars (must have always the same length as ButtonCaptions) contains the chars that are returned for each corresponding button press. The user can also directly press the given key. ButtonChars is not case sensitive, all letters on this list must be different (not only in case). We always return a lowercase letter corresponding to one of ButtonChars letters.

Example usage: 

case MessageChoice(Window, 'Which fruit to you want to eat?',
  ['Apple', 'Banana', 'Cancel'],
  ['a', 'b', CharEscape]) of
  'a': // ... user pressed "Apple" button or "A" key -> likes apples
  'b': // ... user pressed "Banana" button or "B" key -> likes bananas
  CharEscape: // ... user pressed "Cancel" button or "Escape" key -> cancelled
end;

When AllowCancel, user can always press Escape to easily cancel the dialog. Regardless if CharEscape is among ButtonChars. We return CharEscape then.

Source: window/castlemessages.pas (line 204).

function MessageChoice(Window: TCastleWindow; const SArray: array of string; const ButtonCaptions: array of string; const ButtonChars: array of char; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false; const AllowCancel: boolean = false): char; overload;

This item has no description.

Source: window/castlemessages.pas (line 209).

function MessageChoice(Window: TCastleWindow; TextList: TStringList; const ButtonCaptions: array of string; const ButtonChars: array of char; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false; const AllowCancel: boolean = false): char; overload;

This item has no description.

Source: window/castlemessages.pas (line 214).

function MessageKey(Window: TCastleWindow; const S: string; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): TKey; overload;

Ask user to press any key, return this key as Keys.TKey.

Never returns keyNone (which means that keys that cannot be interpreted as Keys.TKey will be ignored, and will not close the dialog box).

Source: window/castlemessages.pas (line 227).

function MessageKey(Window: TCastleWindow; const SArray: array of string; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): TKey; overload;

This item has no description.

Source: window/castlemessages.pas (line 230).

function MessageKey(Window: TCastleWindow; TextList: TStringList; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): TKey; overload;

This item has no description.

Source: window/castlemessages.pas (line 233).

procedure MessageKeyMouse(Window: TCastleWindow; const S: string; out Event: TInputPressRelease; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false); overload; deprecated 'use the function form of MessageKeyMouse';

Warning: this symbol is deprecated: use the function form of MessageKeyMouse

Ask user to press anything (key or mouse button or mouse wheel), and return it. The natural use for this is to allow user to configure keybindings of your program, like for TInputShortcut.

Source: window/castlemessages.pas (line 243).

procedure MessageKeyMouse(Window: TCastleWindow; TextList: TStringList; out Event: TInputPressRelease; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false); overload; deprecated 'use the function form of MessageKeyMouse';

Warning: this symbol is deprecated: use the function form of MessageKeyMouse

This item has no description.

Source: window/castlemessages.pas (line 247).

function MessageKeyMouse(Window: TCastleWindow; const S: string; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): TInputPressRelease; overload;

This item has no description.

Source: window/castlemessages.pas (line 251).

function MessageKeyMouse(Window: TCastleWindow; TextList: TStringList; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): TInputPressRelease; overload;

This item has no description.

Source: window/castlemessages.pas (line 254).

function MessageYesNo(Window: TCastleWindow; const s: string; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean; overload;

This item has no description.

Source: window/castlemessages.pas (line 259).

function MessageYesNo(Window: TCastleWindow; const SArray: array of string; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean; overload;

This item has no description.

Source: window/castlemessages.pas (line 262).

function MessageYesNo(Window: TCastleWindow; TextList: TStringList; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean; overload;

This item has no description.

Source: window/castlemessages.pas (line 265).

function MessageInputCardinal(Window: TCastleWindow; const s: string; const AnswerDefault: string; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): Cardinal; overload;

Ask user to input an unsigned integer.

Note that AnswerDefault below may be given as Cardinal or as a string. The latter is useful if you want the default answer to be '', i.e. empty string — no default answer.

Source: window/castlemessages.pas (line 276).

function MessageInputCardinal(Window: TCastleWindow; const s: string; const AnswerDefault: Cardinal; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): Cardinal; overload;

This item has no description.

Source: window/castlemessages.pas (line 280).

function MessageInputQueryCardinal(Window: TCastleWindow; const Title: string; var Value: Cardinal; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean;

This item has no description.

Source: window/castlemessages.pas (line 284).

function MessageInputQueryCardinalHex(Window: TCastleWindow; const Title: string; var Value: Cardinal; const MaxWidth: Cardinal; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean;

Ask user to input a value in hexadecimal. Give MaxWidth = 0 to say that there is no maximum width.

Source: window/castlemessages.pas (line 292).

function MessageInputQuery(Window: TCastleWindow; const Title: string; var Value: Extended; const ValueAsString: string = ''; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean; overload;

Ask user to input a floating-point number. Number can use CastleScript expressions, so e.g. "1/30", "2+2" or "pi/2" are allowed too.

If you give non-empty ValueAsString, it will be used to show the initial value for the user. Otherwise, we will just show FloatToStrDot(Value), which sometimes may be too ugly. For example Value = 0.01 cannot be precisely represented as a floating point number, and FloatToStrDot shows that this is really something like 0.0099xxxxx.

Source: window/castlemessages.pas (line 307).

function MessageInputQuery(Window: TCastleWindow; const Title: string; var Value: Single; const ValueAsString: string = ''; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean; overload;

This item has no description.

Source: window/castlemessages.pas (line 312).

function MessageInputQueryVector3( Window: TCastleWindow; const Title: string; var Value: TVector3; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean;

This item has no description.

Source: window/castlemessages.pas (line 329).

function MessageInputQueryVector4( Window: TCastleWindow; const Title: string; var Value: TVector4; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean;

This item has no description.

Source: window/castlemessages.pas (line 335).

Types

TTextAlign = THorizontalPosition deprecated;

Warning: this symbol is deprecated.

Position of text in message dialogs. Deprecated, use THorizontalPosition instead.

Source: window/castlemessages.pas (line 113).

Constants

DefaultAlign = hpLeft;

This item has no description.

Source: window/castlemessages.pas (line 115).

taRight = hpRight deprecated;

Warning: this symbol is deprecated.

This item has no description.

Source: window/castlemessages.pas (line 116).

taMiddle = hpMiddle deprecated;

Warning: this symbol is deprecated.

This item has no description.

Source: window/castlemessages.pas (line 117).

taLeft = hpLeft deprecated;

Warning: this symbol is deprecated.

This item has no description.

Source: window/castlemessages.pas (line 118).

Variables

MessageOKPushesView: boolean;

When True, the MessageOK call creates TViewDialogOK, pushes it (using TCastleContainer.PushView), and immediately returns, without waiting for user confirmation.

When False (default), the MessageOK call returns only when user confirms the dialog (pressing "OK"). In this case we also use a bit internal way to "intercept" user input while the dialog box is shown, that is not based on TCastleView, so it doesn't mess with user views.

Practically speaking, calling MessageOK when this is True, is equivalent to doing: 

var
  Dlg: TViewDialogOK;
begin
  Dlg := TViewDialogOK.Create(Self);
  Dlg.Text := 'My text';
  Container.PushView(Dlg);
end;

When to set this to True:

(

If you turn this on, then you should organize your whole application into views using TCastleView. You can even pause the running game in overridden TCastleView.Pause, to make game paused when the message dialog is displayed.

See documentation how to use views.

Note that this feature doesn't change other routines in CastleMessages. For example MessageYesNo is still a modal function (it waits for user input), and it simply doesn't work on iOS. If you want to use TCastleView to manage all dialogs, then use explicitly views like TViewDialogYesNo from the CastleDialogViews unit.

Source: window/castlemessages.pas (line 411).

Generated by PasDoc 0.17.0.snapshot.

Copyright Michalis Kamburelis and Castle Game Engine Contributors.

This webpage is also open-source and we welcome pull requests to improve it.

We use cookies for analytics. See our privacy policy.