1//************************************ bs::framework - Copyright 2018 Marko Pintera **************************************//
2//*********** Licensed under the MIT license. See LICENSE.md for full terms. This notice is not to be removed. ***********//
3#pragma once
4
5namespace bs
6{
7 /** @addtogroup Localization
8 * @{
9 */
10
11 /**
12 * String handle. Provides a wrapper around an Unicode string, primarily for localization purposes.
13 *
14 * Actual value for this string is looked up in a global string table based on the provided identifier string and
15 * currently active language. If such value doesn't exist then the identifier is used as is.
16 *
17 * Use {0}, {1}, etc. in the string value for values that might change dynamically.
18 */
19 class BS_CORE_EXPORT BS_SCRIPT_EXPORT(n:LocString,m:Localization) HString
20 {
21 public:
22 /**
23 * Creates a new localized string with the specified identifier. If the identifier doesn't previously exist in the
24 * string table, identifier value will also be used for initializing the default language version of the string.
25 *
26 * @param[in] identifier String you can use for later referencing the localized string.
27 * @param[in] stringTableId Unique identifier of the string table to retrieve the string from.
28 */
29 BS_SCRIPT_EXPORT()
30 explicit HString(const String& identifier, UINT32 stringTableId = 0);
31
32 /**
33 * Creates a new localized string with the specified identifier and sets the default language version of the
34 * string. If a string with that identifier already exists default language string will be updated.
35 *
36 * @param[in] identifier String you can use for later referencing the localized string.
37 * @param[in] defaultString Default string to assign to the specified identifier. Language to which it will be
38 * assigned depends on the StringTable::DEFAULT_LANGUAGE value.
39 * @param[in] stringTableId Unique identifier of the string table to retrieve the string from.
40 */
41 BS_SCRIPT_EXPORT()
42 explicit HString(const String& identifier, const String& defaultString, UINT32 stringTableId = 0);
43
44 /**
45 * Creates a new empty localized string.
46 *
47 * @param[in] stringTableId Unique identifier of the string table to retrieve the string from.
48 */
49 BS_SCRIPT_EXPORT()
50 HString(UINT32 stringTableId);
51
52 /** Creates a new empty localized string. */
53 BS_SCRIPT_EXPORT()
54 HString();
55
56 HString(const HString& copy);
57 ~HString();
58
59 HString& operator=(const HString& rhs);
60
61 operator const String& () const;
62
63 BS_SCRIPT_EXPORT(in:true)
64 const String& getValue() const;
65
66 /**
67 * Sets a value of a string parameter. Parameters are specified as bracketed values within the string itself
68 * (for example {0}, {1}) etc. Use ^ as an escape character.
69 *
70 * @note This is useful for strings that have dynamically changing values, like numbers, embedded in them.
71 */
72 BS_SCRIPT_EXPORT()
73 void setParameter(UINT32 idx, const String& value);
74
75 /** Returns an empty string. */
76 static const HString& dummy();
77 private:
78 SPtr<LocalizedStringData> mStringData;
79 String* mParameters = nullptr;
80
81 mutable bool mIsDirty = true;
82 mutable String mCachedString;
83 mutable String* mStringPtr = nullptr;
84 };
85
86 /** @} */
87}