Unit CastleClassUtils

Add some strings.

Add all strings from string array to TStrings instance.

Splits S by Splitter, and adds each splitted part to Strings. Splitting is done by Splitter, i.e. if N is the number of occurrences of Splitter inside S, then it always adds N + 1 strings to Strings. Yes, this means that if S starts with Splitter then the first part is equal to ''. And if S ends with Splitter then the last oart is equal to ''.

Use this instead of SList.Text := S to workaround FPC 2.0.2 bug. See [http://www.freepascal.org/mantis/view.php?id=6699]

Make sure we don't have more than MaxCount strings on a list. Removes the last strings if necessary.

Write string contents, encoded as 8-bit (UTF-8), to stream. Versions with "Ln" suffix append a newline. Versions without Stream parameter write to StdOutStream.

Note: When compiled with Delphi, overloaded versions that take Delphi 16-bit String convert it to 8-bit AnsiString, and still write 8-bit. So the output stream contents are the same, in both FPC and Delphi.

Read one character from stream.

Exceptions raised

EReadError

If end of stream.

Read stream, until you find some character in EndingChars. Returns read contents, without final character (the one in EndingChars set).

If you use a version with BackEndingChar parameter and pass BackEndingChar = True, then the ending character will be returned back to stream (we will start reading from it next time). Note that "returning the character" is done by Seek(-1, soFromCurrent), which may not be possible on some streams. Wrap a stream in TPeekCharStream instead, and use TPeekCharStream.ReadUpto, to be able to "return back" a character reliably.

Independently from BackEndingChar, if you use a version with EndingChar parameter, it will be set to the ending character.

Exceptions raised

EReadError

If the stream will end before encountering one of EndingChars.

Read stream, until you find some character in EndingChars, or end of stream.

Compared to StreamReadUpto_NotEOS, this treats "end of stream" as a normal situation, and doesn't raise any exception on it. It sets EndingChar to -1 on end of stream. When EndingChar is not -1, you know you can safely cast it to normal 8-bit character.

Everything else works like with StreamReadUpto_NotEOS.

Read a growing stream, and append it to another destination stream. A "growing stream" is a stream that we can only read sequentially, no seeks allowed, and size is unknown until we hit the end.

The only operation we do on GrowingStream is GrowingStream.Read and the only operation on DestStream is DestStream.WriteBuffer. So DestStream usually must be able to grow dynamically to accomodate any GrowingStream input size.

This procedure ends when GrowingStream ends. If ResetDestStreamPosition then at the end we do DestStream.Position := 0 (since it is usually useful and it would be easy for you to forget about it).

Read a growing stream, and returns it's contents as a string. A "growing stream" is a stream that we can only read sequentially, no seeks allowed, and size is unknown until we hit the end. Works on 8-bit strings, i.e. AnsiStrings.

Encode / decode a string in a binary stream. Records string length (4 bytes), then the string contents (Length(S) bytes). Works on 8-bit strings, i.e. AnsiStrings.

Convert whole Stream to a string. Changes Stream.Position to 0 and then reads Stream.Size bytes, so be sure that Stream.Size is usable. Works on 8-bit strings, i.e. AnsiStrings.

Set contents of TMemoryStream to given string, in UTF-8 encoding. If Rewind then the position is reset to the beginning, otherwise it stays at the end.

Works on 8-bit strings, i.e. AnsiStrings.

Set contents of TMemoryStream to given string, in UTF-8 or UTF-16 (matching default String) encoding. If Rewind then the position is reset to the beginning, otherwise it stays at the end.

On FPC, works with 8-bit strings (AnsiStrings) and is equivalent to MemoryStreamLoadFromString8. On Delphi, works with 16-bit strings (UnicodeString), so the resulting stream size is 2x larger.

Create Component instance, if it's Nil. If Component = nil then it will do Component := ComponentClass.Create(Owner).

Enumerate all properties that are possible to translate in this component and its children. E.g. in TCastleLabel it will return TCastleLabel.Caption, in TCastleEdit it will return TCastleEdit.Text and TCastleEdit.Placeholder.

Returns only non-empty properties, thus assuming that if current (by convention, English) text is empty, then there is no point in translating it. Moreover descendants may define boolean properties to exclude particular text from translating, e.g. TCastleLabel.CaptionTranslate, TCastleEdit.TextTranslate, TCastleEdit.PlaceholderTranslate.

For every TComponent it also recursively enumerates properties to translate in children, i.e. in all published subcomponents and children (returned by TCastleComponent.CustomSerialization). The goal is to be 100% consistent with CastleComponentSerialize, which is used to (de)serialize hierarchy of components (like TCastleUserInterface or TCastleTransform).

You usually don't want to call this method (it is called by other engine routines). Use higher-level routines in CastleLocalizationGetText.

See also

TCastleComponent.TranslateProperties

Enumerate all properties that are possible to translate in this component.

Propose a name for given component class, making it unique in given ComponentsOwner.

Used by TCastleComponent.PropertySections.

Values

• psBasic
• psLayout

Use by TCastleComponent.TranslateProperties.

Notification from TFreeNotificationObserver. Note that it doesn't specify the freed component, because you can get it from Sender.Observed if needed.

Streams to read/write a standard input/output/error of the program.

Tip: to read the standard input as a text file, you can use TTextReader and StdInStream:

var
  StdInReader: TTextReader;
begin
  StdInReader := TTextReader.Create(StdInStream, false);
  try
    while not StdInReader.Eof do
      DoSomethingWithInputLine(StdInReader.Readln);
  finally FreeAndNil(StdinReader) end;
end;

The advantage of using TTextReader above, compared to using the standard Pascal Readln procedure to read from the standard Pascal Input text file, is that you can easily modify the above code to read from any stream. So, instead of the standard input, you can easily read some stream that decompresses gzip data, or downloads data from the Internet... Actually, the overloaded constructor TTextReader.Create can accept an URL, like a file://... or http://..., and will internally use the stream returned by Download function for this URL.

Notes only for Windows GUI applications:

1. Some (or all) of the variables below may be Nil in a Windows GUI application.

   If you want to be on the safe side, then don't use these streams in the GUI application (when IsConsole = false on Windows). But (with some caveats, see below) you can sometimes use them, if they are not-nil.

2. You can have some of the standard streams available, even in a GUI application.

   User can run a GUI program and explicitly redirect it's standard stream, e.g. cat something | my_program.exe for stdin or my_program.exe > output.txt for stdout. Actually some shells, like Cygwin's bash, always redirect some streams under the hood.

   Note that the FPC (and Delphi?) RTL may not provide the standard Input/Output/ErrOutput in this case (because IsConsole = false), but we try a little harder, regardless of the IsConsole value.

3. Caveat: in a GUI program under Windows you cannot depend on the fact that "StdOutStream <> nil means that stdout is actually available (because user redirected stdout etc.)". A first write to the StdOutStream may cause EWriteError, so watch out for this.

   This is tested on Windows 2000 Prof, with FPC 2.0.0 and 2.1.1 (revision 4317). When no stdout is available, StdOutStream should be nil, because GetStdHandle(STD_OUTPUT_HANDLE) should return 0. However, GetStdHandle(STD_OUTPUT_HANDLE) doesn't return 0... It returns some invalid handle (no, not INVALID_HANDLE_VALUE either) that you can't write into (trying to write returns in ERROR_INVALID_HANDLE WinAPI error). It seems that there is no way for me to check whether GetStdHandle(STD_OUTPUT_HANDLE) returned valid handle (e.g. because the program's stdout was redirected, so stdout is perfectly available) or whether it returned something unusable.

   Note that GetStdHandle(STD_INPUT_HANDLE) and GetStdHandle(STD_ERROR_HANDLE) work correctly, so it should be OK to check StdInStream <> nil or StdErrStream <> nil. The only problematic one is GetStdHandle(STD_OUTPUT_HANDLE).

)

Streams to read/write a standard input/output/error of the program.

Tip: to read the standard input as a text file, you can use TTextReader and StdInStream:

var
  StdInReader: TTextReader;
begin
  StdInReader := TTextReader.Create(StdInStream, false);
  try
    while not StdInReader.Eof do
      DoSomethingWithInputLine(StdInReader.Readln);
  finally FreeAndNil(StdinReader) end;
end;

The advantage of using TTextReader above, compared to using the standard Pascal Readln procedure to read from the standard Pascal Input text file, is that you can easily modify the above code to read from any stream. So, instead of the standard input, you can easily read some stream that decompresses gzip data, or downloads data from the Internet... Actually, the overloaded constructor TTextReader.Create can accept an URL, like a file://... or http://..., and will internally use the stream returned by Download function for this URL.

Notes only for Windows GUI applications:

1. Some (or all) of the variables below may be Nil in a Windows GUI application.

   If you want to be on the safe side, then don't use these streams in the GUI application (when IsConsole = false on Windows). But (with some caveats, see below) you can sometimes use them, if they are not-nil.

2. You can have some of the standard streams available, even in a GUI application.

   User can run a GUI program and explicitly redirect it's standard stream, e.g. cat something | my_program.exe for stdin or my_program.exe > output.txt for stdout. Actually some shells, like Cygwin's bash, always redirect some streams under the hood.

   Note that the FPC (and Delphi?) RTL may not provide the standard Input/Output/ErrOutput in this case (because IsConsole = false), but we try a little harder, regardless of the IsConsole value.

3. Caveat: in a GUI program under Windows you cannot depend on the fact that "StdOutStream <> nil means that stdout is actually available (because user redirected stdout etc.)". A first write to the StdOutStream may cause EWriteError, so watch out for this.

   This is tested on Windows 2000 Prof, with FPC 2.0.0 and 2.1.1 (revision 4317). When no stdout is available, StdOutStream should be nil, because GetStdHandle(STD_OUTPUT_HANDLE) should return 0. However, GetStdHandle(STD_OUTPUT_HANDLE) doesn't return 0... It returns some invalid handle (no, not INVALID_HANDLE_VALUE either) that you can't write into (trying to write returns in ERROR_INVALID_HANDLE WinAPI error). It seems that there is no way for me to check whether GetStdHandle(STD_OUTPUT_HANDLE) returned valid handle (e.g. because the program's stdout was redirected, so stdout is perfectly available) or whether it returned something unusable.

   Note that GetStdHandle(STD_INPUT_HANDLE) and GetStdHandle(STD_ERROR_HANDLE) work correctly, so it should be OK to check StdInStream <> nil or StdErrStream <> nil. The only problematic one is GetStdHandle(STD_OUTPUT_HANDLE).

)

Streams to read/write a standard input/output/error of the program.

Tip: to read the standard input as a text file, you can use TTextReader and StdInStream:

var
  StdInReader: TTextReader;
begin
  StdInReader := TTextReader.Create(StdInStream, false);
  try
    while not StdInReader.Eof do
      DoSomethingWithInputLine(StdInReader.Readln);
  finally FreeAndNil(StdinReader) end;
end;

The advantage of using TTextReader above, compared to using the standard Pascal Readln procedure to read from the standard Pascal Input text file, is that you can easily modify the above code to read from any stream. So, instead of the standard input, you can easily read some stream that decompresses gzip data, or downloads data from the Internet... Actually, the overloaded constructor TTextReader.Create can accept an URL, like a file://... or http://..., and will internally use the stream returned by Download function for this URL.

Notes only for Windows GUI applications:

1. Some (or all) of the variables below may be Nil in a Windows GUI application.

   If you want to be on the safe side, then don't use these streams in the GUI application (when IsConsole = false on Windows). But (with some caveats, see below) you can sometimes use them, if they are not-nil.

2. You can have some of the standard streams available, even in a GUI application.

   User can run a GUI program and explicitly redirect it's standard stream, e.g. cat something | my_program.exe for stdin or my_program.exe > output.txt for stdout. Actually some shells, like Cygwin's bash, always redirect some streams under the hood.

   Note that the FPC (and Delphi?) RTL may not provide the standard Input/Output/ErrOutput in this case (because IsConsole = false), but we try a little harder, regardless of the IsConsole value.

3. Caveat: in a GUI program under Windows you cannot depend on the fact that "StdOutStream <> nil means that stdout is actually available (because user redirected stdout etc.)". A first write to the StdOutStream may cause EWriteError, so watch out for this.

   This is tested on Windows 2000 Prof, with FPC 2.0.0 and 2.1.1 (revision 4317). When no stdout is available, StdOutStream should be nil, because GetStdHandle(STD_OUTPUT_HANDLE) should return 0. However, GetStdHandle(STD_OUTPUT_HANDLE) doesn't return 0... It returns some invalid handle (no, not INVALID_HANDLE_VALUE either) that you can't write into (trying to write returns in ERROR_INVALID_HANDLE WinAPI error). It seems that there is no way for me to check whether GetStdHandle(STD_OUTPUT_HANDLE) returned valid handle (e.g. because the program's stdout was redirected, so stdout is perfectly available) or whether it returned something unusable.

   Note that GetStdHandle(STD_INPUT_HANDLE) and GetStdHandle(STD_ERROR_HANDLE) work correctly, so it should be OK to check StdInStream <> nil or StdErrStream <> nil. The only problematic one is GetStdHandle(STD_OUTPUT_HANDLE).

)