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

  • Be careful if you use TCastleApplication.OnUpdate or TCastleApplication.OnTimer. 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 blindly call TCastleWindowCustom.Close from TCastleApplication callbacks.

  • Since your normal callbacks and controls are not run when message box is running, you usually don't need to do anything special about it, unless you use TCastleApplication callbacks mentioned above.

Uses

Overview

Functions and Procedures

procedure MessageOK(Window: TCastleWindowCustom; const s: string; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false); overload;
procedure MessageOK(Window: TCastleWindowCustom; const SArray: array of string; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false); overload;
procedure MessageOK(Window: TCastleWindowCustom; TextList: TStringList; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false); overload;
function MessageInput(Window: TCastleWindowCustom; 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: TCastleWindowCustom; 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: TCastleWindowCustom; 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: TCastleWindowCustom; 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: TCastleWindowCustom; const s: string; const ButtonCaptions: array of string; const ButtonChars: array of char; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): char; overload;
function MessageChoice(Window: TCastleWindowCustom; const SArray: array of string; const ButtonCaptions: array of string; const ButtonChars: array of char; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): char; overload;
function MessageChoice(Window: TCastleWindowCustom; TextList: TStringList; const ButtonCaptions: array of string; const ButtonChars: array of char; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): char; overload;
function MessageKey(Window: TCastleWindowCustom; const S: string; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): TKey; overload;
function MessageKey(Window: TCastleWindowCustom; const SArray: array of string; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): TKey; overload;
function MessageKey(Window: TCastleWindowCustom; TextList: TStringList; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): TKey; overload;
procedure MessageKeyMouse(Window: TCastleWindowCustom; 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: TCastleWindowCustom; TextList: TStringList; out Event: TInputPressRelease; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false); overload; deprecated 'use the function form of MessageKeyMouse';
function MessageKeyMouse(Window: TCastleWindowCustom; const S: string; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): TInputPressRelease; overload;
function MessageKeyMouse(Window: TCastleWindowCustom; TextList: TStringList; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): TInputPressRelease; overload;
function MessageYesNo(Window: TCastleWindowCustom; const s: string; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean; overload;
function MessageYesNo(Window: TCastleWindowCustom; const SArray: array of string; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean; overload;
function MessageYesNo(Window: TCastleWindowCustom; TextList: TStringList; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean; overload;
function MessageInputCardinal(Window: TCastleWindowCustom; const s: string; const AnswerDefault: string; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): Cardinal; overload;
function MessageInputCardinal(Window: TCastleWindowCustom; const s: string; const AnswerDefault: Cardinal; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): Cardinal; overload;
function MessageInputQueryCardinal(Window: TCastleWindowCustom; const Title: string; var Value: Cardinal; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean;
function MessageInputQueryCardinalHex(Window: TCastleWindowCustom; const Title: string; var Value: Cardinal; const MaxWidth: Cardinal; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean;
function MessageInputQuery(Window: TCastleWindowCustom; const Title: string; var Value: Extended; const ValueAsString: string = ''; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean;
function MessageInputQuery(Window: TCastleWindowCustom; const Title: string; var Value: Single; const ValueAsString: string = ''; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean;
function MessageInputQueryVector3( Window: TCastleWindowCustom; const Title: string; var Value: TVector3; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean;
function MessageInputQueryVector4( Window: TCastleWindowCustom; 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

MessageOKPushesState: boolean;

Description

Functions and Procedures

procedure MessageOK(Window: TCastleWindowCustom; 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: TCastleWindowCustom; const SArray: array of string; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false); overload;
 
procedure MessageOK(Window: TCastleWindowCustom; TextList: TStringList; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false); overload;
 
function MessageInput(Window: TCastleWindowCustom; 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: TCastleWindowCustom; 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: TCastleWindowCustom; 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: TCastleWindowCustom; 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: TCastleWindowCustom; const s: string; const ButtonCaptions: array of string; const ButtonChars: array of char; const Alignment: THorizontalPosition = DefaultAlign; const Html: 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;

function MessageChoice(Window: TCastleWindowCustom; const SArray: array of string; const ButtonCaptions: array of string; const ButtonChars: array of char; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): char; overload;
 
function MessageChoice(Window: TCastleWindowCustom; TextList: TStringList; const ButtonCaptions: array of string; const ButtonChars: array of char; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): char; overload;
 
function MessageKey(Window: TCastleWindowCustom; 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 K_None (which means that keys that cannot be interpreted as Keys.TKey will be ignored, and will not close the dialog box).

function MessageKey(Window: TCastleWindowCustom; const SArray: array of string; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): TKey; overload;
 
function MessageKey(Window: TCastleWindowCustom; TextList: TStringList; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): TKey; overload;
 
procedure MessageKeyMouse(Window: TCastleWindowCustom; 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: TCastleWindowCustom; 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

 
function MessageKeyMouse(Window: TCastleWindowCustom; const S: string; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): TInputPressRelease; overload;
 
function MessageKeyMouse(Window: TCastleWindowCustom; TextList: TStringList; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): TInputPressRelease; overload;
 
function MessageYesNo(Window: TCastleWindowCustom; const s: string; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean; overload;
 
function MessageYesNo(Window: TCastleWindowCustom; const SArray: array of string; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean; overload;
 
function MessageYesNo(Window: TCastleWindowCustom; TextList: TStringList; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean; overload;
 
function MessageInputCardinal(Window: TCastleWindowCustom; 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: TCastleWindowCustom; const s: string; const AnswerDefault: Cardinal; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): Cardinal; overload;
 
function MessageInputQueryCardinal(Window: TCastleWindowCustom; const Title: string; var Value: Cardinal; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean;
 
function MessageInputQueryCardinalHex(Window: TCastleWindowCustom; 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: TCastleWindowCustom; const Title: string; var Value: Extended; const ValueAsString: string = ''; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean;

Ask user to input a floating-point number.

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

function MessageInputQuery(Window: TCastleWindowCustom; const Title: string; var Value: Single; const ValueAsString: string = ''; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean;
 
function MessageInputQueryVector3( Window: TCastleWindowCustom; const Title: string; var Value: TVector3; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean;
 
function MessageInputQueryVector4( Window: TCastleWindowCustom; const Title: string; var Value: TVector4; const Alignment: THorizontalPosition = DefaultAlign; const Html: boolean = false): boolean;
 

Types

TTextAlign = THorizontalPosition deprecated;

Warning: this symbol is deprecated.

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

Constants

DefaultAlign = hpLeft;
 
taRight = hpRight deprecated;

Warning: this symbol is deprecated.

 
taMiddle = hpMiddle deprecated;

Warning: this symbol is deprecated.

 
taLeft = hpLeft deprecated;

Warning: this symbol is deprecated.

 

Variables

MessageOKPushesState: boolean;

Change MessageOK behaviour to create TStateDialogOK and push it (using TUIState.Push) 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 state 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 TUIState) it disabled during the display of the error messsage.

If you turn this on, then you should organize your whole application into states using TUIState. You can even pause the running game in overridden TUIState.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 TUIState to manage all dialogs, then use explicitly states like TStateDialogYesNo from the CastleDialogStates unit.


Generated by PasDoc 0.15.0.