uiString Class Reference

String that is able to hold international (UTF-8) strings for the user interface. More...

Public Types
enum	AppendType { OnSameLine , OnNewLine , AfterEmptyLine }
enum	SeparType {   NoSep , CloseLine , Space , Tab ,   Comma , MoreInfo , SemiColon }

Public Member Functions
	uiString ()
	uiString (const char *)=delete
	uiString (const char *original, const char *context, const char *package, const char *disambiguation, int pluralnr)
	uiString (const uiString &)
	no copy, ref counted More...
	~uiString ()
void	addAlternateVersion (const uiString &)
void	addLegacyVersion (const uiString &uistr)
uiString &	addMoreInfo (const char *)
template<class T >
uiString &	addMoreInfo (const T &)
uiString &	addMoreInfo (const uiString &, bool newline=false)
	will deliver ": the string with more info" More...
uiString &	addNewLine (int=1)
uiString &	addSpace (int=1)
uiString &	addTab (int=1)
uiString &	append (const char *s, bool nl=false)
uiString &	append (const OD::String &s, bool nl=false)
uiString &	append (const uiString &s, bool nl=false)
uiString &	appendAfterList (const uiString &)
uiString &	appendIncorrect (const char *, char sep=' ')
uiString &	appendIncorrect (const OD::String &, char sep=' ')
uiString &	appendIncorrect (const uiString &, char sep=' ')
uiString &	appendPhrase (const uiString &, SeparType septyp=uiString::CloseLine, AppendType apptyp=uiString::OnNewLine)
uiString &	appendPhrases (const uiStringSet &, SeparType septyp=uiString::CloseLine, AppendType apptyp=uiString::OnNewLine)
uiString &	appendPhraseSameLine (const uiString &)
uiString &	appendPlainText (const char *, bool addspace=false, bool addquotes=false)
uiString &	appendPlainText (const OD::String &, bool addspace=false, bool addquotes=false)
template<class T >
uiString &	arg (const T &)
uiString &	arg (const uiString &)
uiString &	arg (double, int nrdecimals)
uiString &	arg (float, int nrdecimals)
uiString &	constructWordWith (const uiString &, bool addspace=false)
wchar_t *	createWCharString () const
	returns new string: use 'delete []'. More...
uiString &	embed (const char *open, const char *close)
uiString &	embedFinalState ()
void	encodeStorageString (BufferString &) const
const QString &	fillQString (QString &) const
	translated with arguments inserted More...
void	fillUTF8String (BufferString &) const
	translated with arguments inserted More...
const OD::String &	getFullString (BufferString *=nullptr) const
void	getHexEncoded (BufferString &) const
const char *	getOriginalString () const
	untranslated, no argument substitution More...
const QString &	getQString () const
BufferString	getString () const
	untranslated but arguments evaluated More...
bool	isEmpty () const
bool	isPlainAscii () const
bool	isSet () const
void	makeIndependent ()
	Reads hex-data and sets the translated str. More...
bool	operator! () const
bool	operator!= (const uiString &oth) const
bool	operator< (const uiString &b) const
uiString &	operator= (const char *)=delete
uiString &	operator= (const uiString &)
	no copy, ref counted More...
bool	operator== (const uiString &oth) const
bool	operator> (const uiString &b) const
uiString &	optional ()
uiString &	parenthesize ()
uiString &	postFixWord (const uiString &)
uiString &	preFixWord (const uiString &)
uiString &	quote (bool single)
uiString &	set (const char *)
uiString &	set (const uiString &s)
uiString &	setArg (int, const uiString &)
void	setEmpty ()
void	setFrom (const QString &)
bool	setFromHexEncoded (const char *)
int	size () const
uiString &	toLower (bool yn=true)
	applied before arg subst. More...
uiString &	toTitleCase ()
uiString &	toUpper (bool yn=true)
bool	translate (const QTranslator &, QString &) const
	Returns true if the translation succeeded. More...
int	useEncodedStorageString (const char *)
	returns -1 for fail, >= 0 the number of chars used More...
uiString &	withNumber (std::int64_t)
uiString &	withSurvDepthUnit ()
uiString &	withSurvXYUnit ()
uiString &	withSurvZUnit ()
uiString &	withUnit (const char *)
	just the unit itself, please More...
uiString &	withUnit (const uiString &)

Static Public Member Functions
static uiString &	dummy ()
static const uiString &	empty ()
static const uiString &	emptyString ()
static uiString	getOrderString (int)
	1st, 2nd, 3rd, ... More...
static const char *	sODLocalizationApplication ()
	Will be deprecated (soon): More...

Protected Member Functions
bool	isEqualTo (const uiString &oth) const

Private Member Functions
const QString &	getQStringInternal () const
bool	isCacheValid () const
	operator bool () const =delete
	operator double () const =delete
	operator float () const =delete
	operator int () const =delete

Private Attributes
uiStringData *	data_
Threads::Lock	datalock_
char *	debugstr_

Static Private Attributes
static uiString	dummystring_
static const uiString	emptystring_

Friends
class	uiStringData

Detailed Description

String that is able to hold international (UTF-8) strings for the user interface.

uiString is reference counted; Making a copied object is cheap.

The string will have an 'original string' of simple ASCI characters, which can be used as a 'key' but never for user display.

The string can have %1, %2, ... arguments. For these, sooner or later arguments must be provided, as in: uiString string = tr("%1 plus %2 is %3").arg( 4 ).arg( 5 ).arg( 4+5 ); ... will result in the string "4 plus 5 is 9"

As such, uiString's are suited for limited text manipulation. But if we are doing this for translated words and phrases, beware that alteration and combining is not right. Tranalations allow: Entire phrases to be concatenated Construction of lists with certain 'reasonable' separators. In no case, just glue together words and/or verbs into your own phrases.

The translation in OpendTect is done using Qt's subsystem for localization. A class that needs to use localized strings should:

1. In many cases, you can pick your stuff from the uiStrings common words and phrases defined in uistrings.h.
2. If you need specific words or phrases not in uistrings.h, then use the mTextTranslationClass(classname,packagekey) macro. The packagekey is a string that identifies your software package (probably a short plugin name). OpendTect's internal classes use the "od" package string, and can for short use the mODTextTranslationClass macro.
3. Use the tr() function for all non-standard strings. The tr() function returns a uiString that can be passed to the ui.
4. For functions not belonging to a class, use the od_static_tr function. Any function matching the *_static_tr will be interpreted by Qt's lupdate.

Notes:

Use the pre-translated strings and phrases in uistrings.h as often as possible. Examples: uiStrings::phrCannotRead() and uiStrings::sTraceNumber().

Do not juggle with words to construct phrases. This will lead to bad translations, sometimes hilarious stuff. You can however join multiple phrases into one error message. Prefer this style:

uiString msg( tr("Rendering %1 data in background").arg(objnm) ); msg.appendPhrase( tr("When finished, the image will appear") );

Note the absence of '.' at the end of lines - these phrase terminators should be added if necessary depending on the situation. Do not put them in tr() messages. There are options for different separators when appending.

All uiStrings:sXXX() start with a capital. To get the no-caps or all-caps versions, simply use toLower() and toUpper(), as in: uiStrings::sColumn().toLower()

Units of measure are not translated. Some common units may have a translation, if they are not abbreviated. For example, 'ft' is not translated, 'Feet' is. Easy to use is uiStrings::sFeet( bool abbreviation=true );

You can add 'delimiters' and 'embedding' to words ot phrases. Try to not juggle with these yourself, make sure things are handled in a decent, standard way. For example, there is a uiString::withUnit() that adds the unit (if not empty) with parentheses. Also look at parenthesize(), embed(), optional(), ...

m3Dots: This is only for menus. For buttons, the last argument 'immediate' determines the possible 3 dots at the end of the text. m3Dots is therefore for menu items only (which actually should have been designed to use the same construction, a design error). Set the flag to false and the user will expect a new dialog to pop up rather than immediate action. So the button object will add the '...' if that is the style (but that may change).

<>

Member Enumeration Documentation

AppendType

enum uiString::AppendType

Enumerator
OnSameLine
OnNewLine
AfterEmptyLine

SeparType

enum uiString::SeparType

appendXX() functions should be used to concatenate entire sentences. You cannot just mix&match words or groups of words at the risk of hilarious translations.

Enumerator
NoSep
CloseLine
Space
Tab
Comma
MoreInfo
SemiColon

Constructor & Destructor Documentation

uiString() [1/4]

uiString::uiString

(

)

uiString() [2/4]

uiString::uiString

(

const uiString &

)

no copy, ref counted

~uiString()

uiString::~uiString

(

)

uiString() [3/4]

uiString::uiString ( const char *  )

delete

uiString() [4/4]

uiString::uiString	(	const char *	original,
		const char *	context,
		const char *	package,
		const char *	disambiguation,
		int	pluralnr
	)

Member Function Documentation

addAlternateVersion()

void uiString::addAlternateVersion

(

const uiString &

)

addLegacyVersion()

void uiString::addLegacyVersion ( const uiString &  uistr )

inline

addMoreInfo() [1/3]

uiString & uiString::addMoreInfo ( const char *  str )

inline

addMoreInfo() [2/3]

template<class T >

uiString & uiString::addMoreInfo ( const T &  t )

inline

addMoreInfo() [3/3]

uiString & uiString::addMoreInfo ( const uiString &  str, bool  newline = false  )

inline

will deliver ": the string with more info"

addNewLine()

uiString& uiString::addNewLine ( int  = 1 )

inline

addSpace()

uiString& uiString::addSpace ( int  = 1 )

inline

addTab()

uiString& uiString::addTab ( int  = 1 )

inline

append() [1/3]

uiString& uiString::append ( const char *  s, bool  nl = false  )

inline

append() [2/3]

uiString& uiString::append ( const OD::String &  s, bool  nl = false  )

inline

append() [3/3]

uiString& uiString::append ( const uiString &  s, bool  nl = false  )

inline

appendAfterList()

uiString & uiString::appendAfterList ( const uiString &  str )

inline

appendIncorrect() [1/3]

uiString & uiString::appendIncorrect ( const char *  str, char  sep = ' '  )

inline

appendIncorrect() [2/3]

uiString & uiString::appendIncorrect ( const OD::String &  str, char  sep = ' '  )

inline

appendIncorrect() [3/3]

uiString & uiString::appendIncorrect ( const uiString &  str, char  sep = ' '  )

inline

appendPhrase()

uiString& uiString::appendPhrase	(	const uiString &	,
		SeparType	septyp = uiString::CloseLine,
		AppendType	apptyp = uiString::OnNewLine
	)

appendPhrases()

uiString& uiString::appendPhrases	(	const uiStringSet &	,
		SeparType	septyp = uiString::CloseLine,
		AppendType	apptyp = uiString::OnNewLine
	)

appendPhraseSameLine()

uiString & uiString::appendPhraseSameLine ( const uiString &  str )

inline

appendPlainText() [1/2]

uiString& uiString::appendPlainText	(	const char *	,
		bool	addspace = false,
		bool	addquotes = false
	)

appendPlainText() [2/2]

uiString& uiString::appendPlainText	(	const OD::String &	,
		bool	addspace = false,
		bool	addquotes = false
	)

arg() [1/4]

template<class T >

uiString & uiString::arg ( const T &  var )

inline

the arg() functions allow numbers, other uiStrings, and external strings (like names) to be inserted. See class remarks for example.

arg() [2/4]

uiString& uiString::arg

(

const uiString &

)

arg() [3/4]

uiString & uiString::arg ( double  val, int  nrdecimals  )

inline

arg() [4/4]

uiString & uiString::arg ( float  val, int  nrdecimals  )

inline

constructWordWith()

uiString & uiString::constructWordWith ( const uiString &  str, bool  addspace = false  )

inline

createWCharString()

wchar_t* uiString::createWCharString

(

)

const

returns new string: use 'delete []'.

dummy()

static uiString& uiString::dummy ( )

inlinestatic

embed()

uiString& uiString::embed	(	const char *	open,
		const char *	close
	)

embedFinalState()

uiString& uiString::embedFinalState

(

)

empty()

static const uiString& uiString::empty ( )

inlinestatic

emptyString()

static const uiString& uiString::emptyString ( )

inlinestatic

encodeStorageString()

void uiString::encodeStorageString

(

BufferString &

)

const

fillQString()

const QString& uiString::fillQString

(

QString &

)

const

translated with arguments inserted

fillUTF8String()

void uiString::fillUTF8String

(

BufferString &

)

const

translated with arguments inserted

getFullString()

const OD::String& uiString::getFullString

(

BufferString *

= nullptr

)

const

getHexEncoded()

void uiString::getHexEncoded

(

BufferString &

)

const

Encodes translated string into a const char* buffer that can has only 0-9 A-F

getOrderString()

static uiString uiString::getOrderString ( int  )

static

1st, 2nd, 3rd, ...

getOriginalString()

const char* uiString::getOriginalString

(

)

const

untranslated, no argument substitution

getQString()

const QString& uiString::getQString

(

)

const

getQStringInternal()

const QString& uiString::getQStringInternal ( ) const

private

getString()

BufferString uiString::getString

(

)

const

untranslated but arguments evaluated

isCacheValid()

bool uiString::isCacheValid ( ) const

private

isEmpty()

bool uiString::isEmpty

(

)

const

isEqualTo()

bool uiString::isEqualTo ( const uiString &  oth ) const

protected

isPlainAscii()

bool uiString::isPlainAscii

(

)

const

isSet()

bool uiString::isSet ( ) const

inline

makeIndependent()

void uiString::makeIndependent

(

)

Reads hex-data and sets the translated str.

create a separate copy (with its own ref count)

operator bool()

uiString::operator bool ( ) const

privatedelete

operator double()

uiString::operator double ( ) const

privatedelete

operator float()

uiString::operator float ( ) const

privatedelete

operator int()

uiString::operator int ( ) const

privatedelete

operator!()

bool uiString::operator! ( ) const

inline

operator!=()

bool uiString::operator!= ( const uiString &  oth ) const

inline

operator<()

bool uiString::operator<

(

const uiString &

b

)

const

operator=() [1/2]

uiString& uiString::operator= ( const char *  )

delete

operator=() [2/2]

uiString& uiString::operator=

(

const uiString &

)

no copy, ref counted

operator==()

bool uiString::operator== ( const uiString &  oth ) const

inline

operator>()

bool uiString::operator>

(

const uiString &

b

)

const

optional()

uiString& uiString::optional

(

)

parenthesize()

uiString& uiString::parenthesize

(

)

postFixWord()

uiString & uiString::postFixWord ( const uiString &  str )

inline

preFixWord()

uiString & uiString::preFixWord ( const uiString &  str )

inline

quote()

uiString& uiString::quote

(

bool

single

)

set() [1/2]

uiString& uiString::set

(

const char *

)

set() [2/2]

uiString& uiString::set ( const uiString &  s )

inline

setArg()

uiString& uiString::setArg	(	int	,
		const uiString &
	)

setEmpty()

void uiString::setEmpty

(

)

setFrom()

void uiString::setFrom

(

const QString &

)

Set the translated text. No further translation will be done.

setFromHexEncoded()

bool uiString::setFromHexEncoded

(

const char *

)

size()

int uiString::size

(

)

const

sODLocalizationApplication()

static const char* uiString::sODLocalizationApplication ( )

inlinestatic

Will be deprecated (soon):

toLower()

uiString& uiString::toLower

(

bool

yn = true

)

applied before arg subst.

toTitleCase()

uiString& uiString::toTitleCase

(

)

toUpper()

uiString& uiString::toUpper ( bool  yn = true )

inline

translate()

bool uiString::translate	(	const QTranslator &	,
		QString &
	)		const

Returns true if the translation succeeded.

useEncodedStorageString()

int uiString::useEncodedStorageString

(

const char *

)

returns -1 for fail, >= 0 the number of chars used

withNumber()

uiString & uiString::withNumber ( std::int64_t  nr )

inline

withSurvDepthUnit()

uiString& uiString::withSurvDepthUnit

(

)

withSurvXYUnit()

uiString& uiString::withSurvXYUnit

(

)

withSurvZUnit()

uiString& uiString::withSurvZUnit

(

)

withUnit() [1/2]

uiString & uiString::withUnit ( const char *  str )

inline

just the unit itself, please

withUnit() [2/2]

uiString& uiString::withUnit

(

const uiString &

)

Friends And Related Function Documentation

uiStringData

friend class uiStringData

friend

Member Data Documentation

data_

uiStringData* uiString::data_

mutableprivate

datalock_

Threads::Lock uiString::datalock_

mutableprivate

debugstr_

char* uiString::debugstr_

mutableprivate

dummystring_

uiString uiString::dummystring_

staticprivate

emptystring_

const uiString uiString::emptystring_

staticprivate