Game Development Reference
In-Depth Information
The
s3eOSReadString
API makes string entry really simple; but it is not actually
supported on every platform. To use this API we include the file
s3eOSReadString.h
,
and then make a call to the function
s3eOSReadStringAvailable
to see if string entry
functionality is available for use.
If we are able to use the API, then we have two functions at our disposal. The
first is
s3eOSReadStringUTF8
, which will display a string entry dialog and
return a UTF-8 encoded string as a
const char
pointer. The second method is
s3eOSReadStringUTF8WithDefault
, which allows us to also specify a UTF-8
string that will be used to populate the string dialog when it appears.
UTF-8 is a widely used character format that allows full multilingual
character support. It is often used when memory concerns are
foremost, as single-byte characters such as the standard ASCII
character set can still be represented in a single byte. Characters
from outside the ASCII set (for example, Japanese Kanji) are
encoded with two, three, or more bytes of information. One big
advantage of UTF-8 is that you can continue to use null-terminated
strings since it is guaranteed that a zero byte will never form part of
a valid character code.
Both functions otherwise work in the same way. They both return a pointer to the
string entered by the user (the API will take care of freeing this memory), or NULL
if the user canceled the dialog.
They both also take an optional last parameter that can customize the layout of
the string entry dialog. If the parameter is omitted or the value zero is passed, no
restrictions are applied. The following table shows the other values that can be used:
Value
Description
S3E_OSREADSTRING_FLAG_EMAIL
Indicates that we are expecting an e-mail
address to be entered.
S3E_OSREADSTRING_FLAG_NUMBER
Indicates that we are expecting a numeric
value to be entered.
S3E_OSREADSTRING_FLAG_PASSWORD
Indicates that the application will use the OS
method for entering a password, possibly
hiding characters as they are entered.
S3E_OSREADSTRING_FLAG_URL
Indicates that we are expecting a URL to be
entered.
Search WWH ::
Custom Search