Stellarium  24.3
Public Member Functions
Template Class Reference

Enhanced version of QString for template processing. More...

#include <template.h>

Public Member Functions

 Template (QString source, QString sourceName)
 Constructor that reads the template from a string. More...
 
 Template (QFile &file, QStringConverter::Encoding encoding=QStringConverter::Utf8)
 Constructor that reads the template from a file. More...
 
int setVariable (QString name, QString value)
 Replace a variable by the given value. More...
 
int setCondition (QString name, bool value)
 Set a condition. More...
 
int loop (QString name, int repetitions)
 Set number of repetitions of a loop. More...
 
void enableWarnings (bool enable=true)
 Enable warnings for missing tags. More...
 
void translate (ITemplateTranslationProvider &provider)
 Translates all translation tags using the given translation provider. More...
 

Detailed Description

Enhanced version of QString for template processing.

Templates are usually loaded from files, but may also be loaded from prepared Strings. Example template file:

Hello {username}, how are you?

{if locked}
    Your account is locked.
{else locked}
    Welcome on our system.
{end locked}

The following users are on-line:
    Username       Time
{loop user}
    {user.name}    {user.time}
{end user}

Example code to fill this template:

Template t(QFile("test.tpl"),QTextCode::codecForName("UTF-8"));
t.setVariable("username", "Stefan");
t.setCondition("locked",false);
t.loop("user",2);
t.setVariable("user0.name,"Markus");
t.setVariable("user0.time,"8:30");
t.setVariable("user1.name,"Roland");
t.setVariable("user1.time,"8:45");

The code example above shows how variable within loops are numbered. Counting starts with 0. Loops can be nested, for example:

<table>
{loop row}
    <tr>
    {loop row.column}
        <td>{row.column.value}</td>
    {end row.column}
    </tr>
{end row}
</table>

Example code to fill this nested loop with 3 rows and 4 columns:

t.loop("row",3);

t.loop("row0.column",4);
t.setVariable("row0.column0.value","a");
t.setVariable("row0.column1.value","b");
t.setVariable("row0.column2.value","c");
t.setVariable("row0.column3.value","d");

t.loop("row1.column",4);
t.setVariable("row1.column0.value","e");
t.setVariable("row1.column1.value","f");
t.setVariable("row1.column2.value","g");
t.setVariable("row1.column3.value","h");

t.loop("row2.column",4);
t.setVariable("row2.column0.value","i");
t.setVariable("row2.column1.value","j");
t.setVariable("row2.column2.value","k");
t.setVariable("row2.column3.value","l");

See also
TemplateLoader
TemplateCache

Constructor & Destructor Documentation

◆ Template() [1/2]

Template::Template ( QString  source,
QString  sourceName 
)

Constructor that reads the template from a string.

Parameters
sourceThe template source text
sourceNameName of the source file, used for logging

◆ Template() [2/2]

Template::Template ( QFile &  file,
QStringConverter::Encoding  encoding = QStringConverter::Utf8 
)

Constructor that reads the template from a file.

Note that this class does not cache template files by itself, so using this constructor is only recommended to be used on local filesystem.

Parameters
fileFile that provides the source text
textCodecEncoding of the source. If null, UTF-8 is assumed.
encodingEncoding of the source. (Qt6 version)
See also
TemplateLoader
TemplateCache
Note
Qt6 upgrade by Georg Zotti for Stellarium

Member Function Documentation

◆ enableWarnings()

void Template::enableWarnings ( bool  enable = true)

Enable warnings for missing tags.

Parameters
enableWarnings are enabled, if true

◆ loop()

int Template::loop ( QString  name,
int  repetitions 
)

Set number of repetitions of a loop.

This affects tags with the syntax

  • {loop name}...{end name}
  • {loop name}...{else name}...{end name}
Parameters
nameName of the loop
repetitionsThe number of repetitions
Returns
The number of loops that have been processed

◆ setCondition()

int Template::setCondition ( QString  name,
bool  value 
)

Set a condition.

This affects tags with the syntax

  • {if name}...{end name}
  • {if name}...{else name}...{end name}
  • {ifnot name}...{end name}
  • {ifnot name}...{else name}...{end name}
Parameters
nameName of the condition
valueValue of the condition
Returns
The count of conditions that have been processed

◆ setVariable()

int Template::setVariable ( QString  name,
QString  value 
)

Replace a variable by the given value.

Affects tags with the syntax

  • {name}

After settings the value of a variable, the variable does not exist anymore, it it cannot be changed multiple times.

Parameters
namename of the variable
valuenew value
Returns
The count of variables that have been processed

◆ translate()

void Template::translate ( ITemplateTranslationProvider provider)

Translates all translation tags using the given translation provider.

The translation tags have a PHP-like format to be able to be parsed using gettext/xgettext. Examples: <?= tr("this is an example") ?>, <?= tr("You have %1 new messages", "20") ?>