Castle Game Engine: CastleMessages

# Unit CastleMessages
Description | Uses | Classes, Interfaces, Objects and Records | Functions and Procedures | Types | Constants | Variables
- ## Description Dialog boxes (asking user for confirmation, question, simple text input etc.) inside TCastleWindowBase. Features: MessageInputXxx ask user to enter some text. The dialog boxes have vertical scroll bar, displayed when needed. So don't worry about displaying 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 don't worry about displaying text with long lines. We will try to break text only at whitespace. Note that our "line breaking" works correctly for all fonts (see TMessagesTheme.Font), even if font is not fixed-character-width font. 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 TCastleWindowBase.ResizeAllowed = raAllowed, of course.) Long lines are automatically broken taking into account current window width. You can configure dialog boxes look using CastleMessagesTheme variable. For example, you can make the dialog box background partially transparent. Call MessageXxx functions only when Window.Closed = false. Note that MessageXxx will do Window.MakeCurrent (probably more than once). Calling MessageXxx requires one free place on OpenGL attrib stack. Notes about implementation: It's implemented using CastleWindowModes approach. Which means that when you call some MessageXxx procedure, it temporarily switches all TCastleWindowBase callbacks (OnDraw, OnPress, OnRelease, OnUpdate etc.) for it's own. So you can be sure that e.g. no TCastleWindow callbacks that you registered in your own programs/units will be called while MessageXxx works. When message box ends (e.g. for simple MessageOk, this happens when user will accept it by Enter key or clicking OK), original callbacks are restored. This way you can call MessageXxx procedures in virtually any place of your program, and things will magically work — inside MessageXxx we wait until user answers the dialog box. Be careful if you use Application callbacks, OnUpdate / OnTimer. They are tied to GL window manager, Glwn, not to any particular window, and so they continue to work even while we're inside MessageXxx procedure. While this can be useful, you should be careful when implementing these Application callbacks. When they access some TCastleWindowBase instance, it may be currently inside MessageXxx call. The whole MessageXxx is supposed to start and end on an open TCastleWindowBase instance, so no Open or Close methods of TCastleWindowBase will be called during MessageXxx. OnCloseQuery during MessageXxx calls prevents user from exiting the program, actually OnCloseQuery callback is simple no-op. Which means, among other things, that you can safely use MessageXxx inside your own OnCloseQuery, for example you can implement you OnCloseQuery like
        if MessageYesNo('Are you sure ?') then
          Window.Close;
## Uses Classes CastleWindow CastleGLUtils GL GLU GLExt CastleUtils CastleGLBitmapFonts CastleStringUtils CastleVectors CastleKeysMouse ## Overview ### Classes, Interfaces, Objects and Records
Name | Description
--- | ---
record `TMessagesTheme` |
### Functions and Procedures
`procedure MessageOK(Window: TCastleWindowBase; const s: string; textalign: TTextAlign = taMiddle); overload;`
`procedure MessageOK(Window: TCastleWindowBase; const SArray: array of string; textalign: TTextAlign = taMiddle); overload;`
`procedure MessageOK(Window: TCastleWindowBase; textlist: TStringList; textalign: TTextAlign = taMiddle); overload;`
`function MessageInput(Window: TCastleWindowBase; const s: string; textalign: TTextAlign = taMiddle; const answerDefault: string = ''; answerMinLen: integer = 0; answerMaxLen: integer = 0; const answerAllowedChars: TSetOfChars = AllChars): string; overload;`
`function MessageInput(Window: TCastleWindowBase; textlist: TStringList; textalign: TTextAlign = taMiddle; const answerDefault: string = ''; answerMinLen: integer = 0; answerMaxLen: integer = 0; const answerAllowedChars: TSetOfChars = AllChars): string; overload;`
`function MessageInputQuery(Window: TCastleWindowBase; const s: string; var answer: string; textalign: TTextAlign; answerMinLen: integer = 0; answerMaxLen: integer = 0; const answerAllowedChars: TSetOfChars = AllChars): boolean; overload;`
`function MessageInputQuery(Window: TCastleWindowBase; textlist: TStringList; var answer: string; textalign: TTextAlign; answerMinLen: integer = 0; answerMaxLen: integer = 0; const answerAllowedChars: TSetOfChars = AllChars): boolean; overload;`
`function MessageChar(Window: TCastleWindowBase; const s: string; const AllowedChars: TSetOfChars; const ClosingInfo: string; textalign: TTextAlign = taMiddle; IgnoreCase: boolean = false): char; overload;`
`function MessageChar(Window: TCastleWindowBase; const SArray: array of string; const AllowedChars: TSetOfChars; const ClosingInfo: string; textalign: TTextAlign = taMiddle; IgnoreCase: boolean = false): char; overload;`
`function MessageChar(Window: TCastleWindowBase; textlist: TStringList; const AllowedChars: TSetOfChars; const ClosingInfo: string; textalign: TTextAlign = taMiddle; IgnoreCase: boolean = false): char; overload;`
`function MessageKey(Window: TCastleWindowBase; const S: string; const ClosingInfo: string; TextAlign: TTextAlign): TKey; overload;`
`function MessageKey(Window: TCastleWindowBase; const SArray: array of string; const ClosingInfo: string; TextAlign: TTextAlign): TKey; overload;`
`function MessageKey(Window: TCastleWindowBase; TextList: TStringList; const ClosingInfo: string; TextAlign: TTextAlign): TKey; overload;`
`procedure MessageKeyMouse(Window: TCastleWindowBase; const S: string; const ClosingInfo: string; TextAlign: TTextAlign; out Event: TInputPressRelease); overload;`
`procedure MessageKeyMouse(Window: TCastleWindowBase; TextList: TStringList; const ClosingInfo: string; TextAlign: TTextAlign; out Event: TInputPressRelease); overload;`
`function MessageYesNo(Window: TCastleWindowBase; const s: string; textalign: TTextAlign = taMiddle): boolean; overload;`
`function MessageYesNo(Window: TCastleWindowBase; const SArray: array of string; textalign: TTextAlign = taMiddle): boolean; overload;`
`function MessageYesNo(Window: TCastleWindowBase; textlist: TStringList; textalign: TTextAlign = taMiddle): boolean; overload;`
`function MessageInputCardinal(Window: TCastleWindowBase; const s: string; TextAlign: TTextAlign; const AnswerDefault: string): Cardinal; overload;`
`function MessageInputCardinal(Window: TCastleWindowBase; const s: string; TextAlign: TTextAlign; AnswerDefault: Cardinal): Cardinal; overload;`
`function MessageInputQueryCardinal(Window: TCastleWindowBase; const Title: string; var Value: Cardinal; TextAlign: TTextAlign): boolean;`
`function MessageInputQueryCardinalHex(Window: TCastleWindowBase; const Title: string; var Value: Cardinal; TextAlign: TTextAlign; MaxWidth: Cardinal): boolean;`
`function MessageInputQuery(Window: TCastleWindowBase; const Title: string; var Value: Extended; TextAlign: TTextAlign; const ValueAsString: string = ''): boolean;`
`function MessageInputQuery(Window: TCastleWindowBase; const Title: string; var Value: Single; TextAlign: TTextAlign; const ValueAsString: string = ''): boolean;`
`function MessageInputQueryVector3Single( Window: TCastleWindowBase; const Title: string; var Value: TVector3Single; TextAlign: TTextAlign): boolean;`
`function MessageInputQueryVector4Single( Window: TCastleWindowBase; const Title: string; var Value: TVector4Single; TextAlign: TTextAlign): boolean;`
### Types
`TTextAlign = (...);`
### Constants
`MessagesTheme_Default: TMessagesTheme = ( RectColor: (0, 0, 0, 1); RectBorderCol: (1, 1, 0.33); ScrollBarCol: (0.5, 0.5, 0.5); ClosingInfoCol: (1, 1, 0.33); AdditionalStrCol: (0.33, 1, 1); TextCol: (1, 1, 1); Font: nil; );`
`MessagesTheme_TypicalGUI: TMessagesTheme = ( RectColor: (0.75, 0.75, 0.66, 1); RectBorderCol: (0.87, 0.87, 0.81); ScrollBarCol: (0.87, 0.87, 0.81); ClosingInfoCol: (0.4, 0, 1); AdditionalStrCol: (0, 0.4, 0); TextCol: (0, 0, 0); Font: nil; );`
### Variables
`MessagesTheme: TMessagesTheme;`
## Description ### Functions and Procedures
`procedure MessageOK(Window: TCastleWindowBase; const s: string; textalign: TTextAlign = taMiddle); overload;`
Ask user for simple confirmation. In other words, this is the standard and simplest "OK" dialog box.
`procedure MessageOK(Window: TCastleWindowBase; const SArray: array of string; textalign: TTextAlign = taMiddle); overload;`
`procedure MessageOK(Window: TCastleWindowBase; textlist: TStringList; textalign: TTextAlign = taMiddle); overload;`
`function MessageInput(Window: TCastleWindowBase; const s: string; textalign: TTextAlign = taMiddle; const answerDefault: string = ''; answerMinLen: integer = 0; answerMaxLen: integer = 0; const answerAllowedChars: TSetOfChars = AllChars): string; overload;`
Ask user to input a string. User must give an answer (there is no "Cancel" button) — see MessageInputQuery if you want "Cancel" button. ###### Parameters AnswerMaxLen 0 (zero) means that there's no maximum answer length.
`function MessageInput(Window: TCastleWindowBase; textlist: TStringList; textalign: TTextAlign = taMiddle; const answerDefault: string = ''; answerMinLen: integer = 0; answerMaxLen: integer = 0; const answerAllowedChars: TSetOfChars = AllChars): string; overload;`
`function MessageInputQuery(Window: TCastleWindowBase; const s: string; var answer: string; textalign: TTextAlign; answerMinLen: integer = 0; answerMaxLen: integer = 0; const answerAllowedChars: TSetOfChars = AllChars): 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: TCastleWindowBase; textlist: TStringList; var answer: string; textalign: TTextAlign; answerMinLen: integer = 0; answerMaxLen: integer = 0; const answerAllowedChars: TSetOfChars = AllChars): boolean; overload;`
`function MessageChar(Window: TCastleWindowBase; const s: string; const AllowedChars: TSetOfChars; const ClosingInfo: string; textalign: TTextAlign = taMiddle; IgnoreCase: boolean = false): char; overload;`
Ask user to input a single character from a given set. This is good when user has a small, finite number of answers for some question, and each answer can be assigned some key. For example, MessageYesNo is built on top of this procedure: keys "y" and "n" are allowed characters that user can input. ###### Parameters ClosingInfo This is a text to indicate to user what keys can be pressed and what they mean. ClosingInfo is displayed below basic Text of the message, and in a different color. If may be '' if you don't want this. IgnoreCase This means that case of letters in AllowedChars will be ignored. For example, you can include only uppercase 'A' in AllowedChars. Or you can include lowercase 'a'. Or you can include both. It doesn't matter — we will always accept both lower and upper case. Also, when character is returned, it's always uppercased. So you can't even know if user pressed lower of upper case letter.
`function MessageChar(Window: TCastleWindowBase; const SArray: array of string; const AllowedChars: TSetOfChars; const ClosingInfo: string; textalign: TTextAlign = taMiddle; IgnoreCase: boolean = false): char; overload;`
`function MessageChar(Window: TCastleWindowBase; textlist: TStringList; const AllowedChars: TSetOfChars; const ClosingInfo: string; textalign: TTextAlign = taMiddle; IgnoreCase: boolean = false): char; overload;`
`function MessageKey(Window: TCastleWindowBase; const S: string; const ClosingInfo: string; TextAlign: TTextAlign): 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: TCastleWindowBase; const SArray: array of string; const ClosingInfo: string; TextAlign: TTextAlign): TKey; overload;`
`function MessageKey(Window: TCastleWindowBase; TextList: TStringList; const ClosingInfo: string; TextAlign: TTextAlign): TKey; overload;`
`procedure MessageKeyMouse(Window: TCastleWindowBase; const S: string; const ClosingInfo: string; TextAlign: TTextAlign; out Event: TInputPressRelease); overload;`
Ask user to press any 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. TODO: for historical reasons, in case of key events, it for now returns only events that can be represented as TKey (so Event.Key <> K_None, as long as Event.EventType = itKey).
`procedure MessageKeyMouse(Window: TCastleWindowBase; TextList: TStringList; const ClosingInfo: string; TextAlign: TTextAlign; out Event: TInputPressRelease); overload;`
`function MessageYesNo(Window: TCastleWindowBase; const s: string; textalign: TTextAlign = taMiddle): boolean; overload;`
`function MessageYesNo(Window: TCastleWindowBase; const SArray: array of string; textalign: TTextAlign = taMiddle): boolean; overload;`
`function MessageYesNo(Window: TCastleWindowBase; textlist: TStringList; textalign: TTextAlign = taMiddle): boolean; overload;`
`function MessageInputCardinal(Window: TCastleWindowBase; const s: string; TextAlign: TTextAlign; const AnswerDefault: string): Cardinal; overload;`
Ask user to input an unsigned integer. This is actually a shortcut for simple MessageInput with answerMinLength = 1 and AllowedChars = ['0'..'9'], since this guarantees input of some unsigned integer number. 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: TCastleWindowBase; const s: string; TextAlign: TTextAlign; AnswerDefault: Cardinal): Cardinal; overload;`
`function MessageInputQueryCardinal(Window: TCastleWindowBase; const Title: string; var Value: Cardinal; TextAlign: TTextAlign): boolean;`
`function MessageInputQueryCardinalHex(Window: TCastleWindowBase; const Title: string; var Value: Cardinal; TextAlign: TTextAlign; MaxWidth: Cardinal): boolean;`
Ask user to input a value in hexadecimal. Give MaxWidth = 0 to say that there is no maximum width.
`function MessageInputQuery(Window: TCastleWindowBase; const Title: string; var Value: Extended; TextAlign: TTextAlign; const ValueAsString: string = ''): 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: TCastleWindowBase; const Title: string; var Value: Single; TextAlign: TTextAlign; const ValueAsString: string = ''): boolean;`
`function MessageInputQueryVector3Single( Window: TCastleWindowBase; const Title: string; var Value: TVector3Single; TextAlign: TTextAlign): boolean;`
`function MessageInputQueryVector4Single( Window: TCastleWindowBase; const Title: string; var Value: TVector4Single; TextAlign: TTextAlign): boolean;`
### Types
`TTextAlign = (...);`
Specifies text alignment for MessageXxx functions in CastleMessages unit. ###### Values taLeft: taMiddle: taRight:
### Constants
`MessagesTheme_Default: TMessagesTheme = ( RectColor: (0, 0, 0, 1); RectBorderCol: (1, 1, 0.33); ScrollBarCol: (0.5, 0.5, 0.5); ClosingInfoCol: (1, 1, 0.33); AdditionalStrCol: (0.33, 1, 1); TextCol: (1, 1, 1); Font: nil; );`
`MessagesTheme_TypicalGUI: TMessagesTheme = ( RectColor: (0.75, 0.75, 0.66, 1); RectBorderCol: (0.87, 0.87, 0.81); ScrollBarCol: (0.87, 0.87, 0.81); ClosingInfoCol: (0.4, 0, 1); AdditionalStrCol: (0, 0.4, 0); TextCol: (0, 0, 0); Font: nil; );`
### Variables
`MessagesTheme: TMessagesTheme;`
The way MessageXxx procedures in this unit are displayed. By default it is equal to MessagesTheme_Default. Note that all procedures in this unit are re-entrant (safe for recursive calls, and in threads), unless you modify this variable. When you modify this from one thread, be sure that you don't currently use it in some MessageXxx (in other thread, or maybe you're in Application.OnUpdate or such that is called while other window is in MessageXxx).
Generated by PasDoc 0.13.0 on 2013-08-17 21:27:13