Unit CastleMessages

Description

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

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.

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.

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

This item has no description.

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

This item has no description.

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

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

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.

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.

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.

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

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

This item has no description.

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

This item has no description.

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.

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.

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

This item has no description.

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

This item has no description.

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

This item has no description.

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

This item has no description.

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

This item has no description.

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.

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.

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

This item has no description.

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.

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.

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.

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

This item has no description.

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

This item has no description.

Types

TTextAlign = THorizontalPosition deprecated;

Warning: this symbol is deprecated.

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

Constants

DefaultAlign = hpLeft;

This item has no description.

taRight = hpRight deprecated;

Warning: this symbol is deprecated.

This item has no description.

taMiddle = hpMiddle deprecated;

Warning: this symbol is deprecated.

This item has no description.

taLeft = hpLeft deprecated;

Warning: this symbol is deprecated.

This item has no description.

Variables

MessageOKPushesView: boolean;

Change MessageOK behavior to create TViewDialogOK and push it (using TCastleContainer.PushView) and immediately return, without waiting for user confirmation.

Why you may want to use this (or not to use this)?

  • This is the only way to make MessageOK working on iOS (where Application.ProcessMessages is not available).

  • This looks a little better in case user may resize the window while the MessageOK is running, or when something animates under MessageOK. When this is True, the view underneath redraws properly, so it can adjust to window size and animate. Otherwise, all MessageXxx methods in this unit only show a static screenshot underneath, that is scaled if needed.

  • On the other hand, the notification about unhandled exceptions (done by CastleWindow automatically, using MessageOK) is a little safer when this is False. When this is False, there's a greater chance that the problematic code (e.g. the update method of some other TCastleView) it disabled during the display of the error messsage.

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.

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.


Generated by PasDoc 0.16.0-snapshot.