36     \brief HbParameterLengthLimiter is a class that offers support to insert different types of arguments into a QString.

    36     \brief The HbParameterLengthLimiter class provides support for localizing text strings, and for limiting the length of runtime values inserted into the strings.

    37 

    37 

    38     Supports upto 9 argument inserts per QString.

    38     The HbParameterLengthLimiter class provides the same support for string 

    39 

    39     localization based on unique text IDs as the global hbTrId() function, and 

    40     Supports different kinds of indicators that are used for marking where arguments are inserted

    40     the same support for inserting values based on the given arguments as 

    41         - %x for inserting QStrings, where x is number from 1 to 9 indicating the order in which argumentss are positioned.

    41     QString::arg(). In addition, %HbParameterLengthLimiter supports limiting the 

    42         - %[y]x for inserting QStrings, x indicates argument inserting order and y is a number indicating the maximum length

    42     length of values that are inserted into the translations using arguments. 

    43                 for the argument e.g. %[10]2 would mean that the inserted QStrings maximum length is 10 characters and that the

    43     You can use up to nine arguments to insert values, as supported by QString.

    44                 limited argument is the second argument to be inserted.

    44     

    45         - %Lx   for inserting numbers, x is used to indicate argument inserting order.

    45     In most cases, it is simpler to use hbTrId() for localization (see hbTrId() 

    46 

    46     documentation and examples). However, the number of characters in a text 

    47     Example of how to use HbParameterLengthLimiter:

    47     string can vary widely from language to language. Sometimes when space is 

    48     \snippet{unittest_HbParameterLengthLimiter/unittest_HbParameterLengthLimiter.cpp,1}

    48     limited, you may want to limit the number of characters that are inserted. 

    49 

    49     In this case, use the HbParameterLengthLimiter class instead of %hbTrId().

    50 */

    50     

    51 

    51     Even if the inserted value does not require limiting at the time of coding, 

    52 /*!

    52     there is one advantage in using HbParameterLengthLimiter right away: if you 

    53     Constructs a HbParameterLengthLimiter with \a HbParameterLengthLimiter.

    53     later need to limit the value length for some languages, no code changes are 

    54     

    54     required. You only need to modify the <tt>.ts</tt> translation files for 

    55     \attention Cross-Platform API

    55     those languages. However, if you already know that all translations will fit 

    56     

    56     without any limitations (for example, if you are using scrolling text with 

    57     \param a HbParameterLengthLimiter that will have arguments inserted

    57     HbMarqueeItem), use hbTrId().

    58     

    59     The text strings in .ts localization files can have placeholders, where you 

    60     insert values at runtime. HbParameterLengthLimiter supports the same 

    61     placeholder formats as hbTrId() (\c \%x, \c \%Lx and \c \%Ln), and the 

    62     following additional placeholder:

    63     

    64     <ul>

    65     

    66     <li><tt>%[y]x</tt> for inserting strings, where \c x is a number (1-9) that 

    67     indicates the order of placeholders in the source text string. This 

    68     corresponds to your argument inserting order when you use 

    69     HbParameterLengthLimiter. The order of placeholders may vary in different 

    70     translations, and the numbering ensures that values are inserted into the 

    71     correct placeholders. <tt>[y]</tt> is a number that indicates the maximum 

    72     length (in characters) for the inserted value.</li>

    73     

    74     </ul>

    75     

    76     For example, the text string \c "Downloading file %[10]1 from URL %2" has 

    77     two placeholders to insert two strings, a file name and a URL. The [] 

    78     notation in the first placeholder \c %[10]1 limits the length of the file 

    79     name to 10 characters.

    80     

    81     HbParameterLengthLimiter provides all the same %arg() variants as QString, 

    82     which means you can use it in place of QString::arg() when needed. The 

    83     following examples describe the most common use cases that you would use 

    84     %HbParameterLengthLimiter for. The other functions available can be used for 

    85     more complex cases, such as processing the localized text strings.

    86     

    87     \section _usecases_hbparameterlengthlimiter Using the HbParameterLengthLimiter class

    88     

    89     \subsection _uc_001_hbparameterlengthlimiter Limiting the length of values inserted using an argument

    90       

    91       This example shows how you get the translation based on a given text ID, 

    92       replace the two placeholders with values using runtime arguments, and 

    93       limit the length of both of the inserted values.

    94       

    95       \code

    96       // "Download file %1 from URL %2?"

    97       // fileName = "test_application_data_file.txt"

    98       // urlName = "www.something.org"

    99       HbParameterLengthLimiter myTranslation("txt_browser_download_data");

   100       label->setPlainText(myTranslation.arg(fileName, urlName));

   101       \endcode

   102       

   103       The translation is defined in the <tt>.ts</tt> file in the following 

   104       format:

   105       

   106       \code

   107       <message id="txt_browser_download_data">

   108         <source>"Download file %1 from URL %2?</source>

   109         <translation variants="no">Download file %[10]1 from URL %[12]2?</translation>

   110       </message>

   111       \endcode

   112       

   113       This limits the length of the inserted values to 10 and 12 characters, 

   114       producing a text string such as \c "Download file test_appli... from URL 

   115       www.somethin...?".

   116     

   117       \subsection _uc_002_hbparameterlengthlimiter Inserting values using runtime arguments

   118       

   119       This example shows how you simply get a translation and replace the 

   120       placeholder with a runtime value. You can achieve the same result by using 

   121       hbTrId().

   122       

   123       \code

   124       // "Enter %L1-digit passcode"

   125       // int number = 4

   126       label->setPlainText(HbParameterLengthLimiter("txt_give_numeric_passcode").arg(number));

   127       \endcode

   128       

   129       This example also uses the 'L' notation in the placeholder in the text 

   130       string, which formats the number in the active locale's display format.

   131       

   132       \sa hbTrId(), QString::arg(), HbDirectoryNameLocalizer, HbTranslator

   133 

   134 

   135 */

   136 

   137 /*!

   138     Copy constructor.

   139         

   140     \param a The HbParameterLengthLimiter object to copy.

    66     Constructs a HbParameterLengthLimiter with \a QString.

   149     Constructor for processing a string that has already been localized.

    67     

   150     

    68     \attention Cross-Platform API

   151     \param a A localized string containing the placeholders for inserting values.

    69     

    70     \param a QString that will have arguments inserted

    79     Constructs a HbParameterLengthLimiter with \a char*.

   160 

    80     

   161     Constructs an HbParameterLengthLimiter using a text ID. The functionality is 

    81     \attention Cross-Platform API

   162     similar to what hbTrId() provides, except for the additional support for 

    82     

   163     limiting the length of the inserted values.

    83     \param a char string that will have arguments inserted

   164     

   165     \param a The text ID that identifies the localized string in the 

   166     <tt>.ts</tt> file.

   167     

    92     Constructs a HbParameterLengthLimiter with \a char* and \a int.

   176 

    93     

   177     Constructs an HbParameterLengthLimiter using a text ID, and a numeric 

    94     \attention Cross-Platform API

   178     parameter for handling singular and plural forms correctly. The 

    95     

   179     functionality is the same as provided by the hbTrId() function, except for 

    96     \param a char string that will have arguments inserted

   180     the additional support for limiting the length of the inserted values.

    97     \param n used to identify which plural form to use

   181     

   182     \param a The text ID that identifies the localized string in the 

   183     <tt>.ts</tt> file.    

   184     \param n A numeric parameter that indicates quantity, used to determine 

   185     which singular or plural translation to use from the <tt>.ts</tt> file.

   186     

   106     Conp->structs a HbParameterLengthLimiter without a predefined QString.

   195     Constructs an HbParameterLengthLimiter with a blank string.

   107     

   108     \attention Cross-Platform API  

   117     Destructor

   204     Destructor.

   125     Inserts an \a argument to a HbParameterLengthLimiter QString.

   212     

   126     

   213     Replaces the placeholders in the translation with runtime values using the 

   127     \attention Cross-Platform API

   214     given parameters and arguments.

   128     

   215     

   129     \param a number that will be inserted to the QString

   216     This function corresponds to QString::arg(qlonglong, int, int, const QChar &) const.

   130     \param fieldwidth specifies the minimum amount of space that a is padded to and filled with the character fillChar

   217     

   131     \param base defines the number base

   218     \param a The number that is to be inserted to the output string.

   132     \param fillChar defines the fill character

   219     \param fieldwidth The minimum amount of space that \a a is padded to and 

   220     filled with the character \a fillChar.    

   221     \param base The number base.

   222     \param fillChar The fill character.

   145     Inserts an \a argument to a HbParameterLengthLimiter QString.

   235     

   146     

   236     Replaces the placeholders in the translation with runtime values using the 

   147     \attention Cross-Platform API

   237     given parameters and arguments.

   148     

   238     

   149     \param a number that will be inserted to the QString

   239     This function corresponds to QString::arg(qulonglong, int, int, const QChar &) const.

   150     \param fieldwidth specifies the minimum amount of space that a is padded to and filled with the character fillChar

   240     

   151     \param base defines the number base

   241     \param a The number that is to be inserted to the output string.    

   152     \param fillChar defines the fill character

   242     \param fieldwidth The minimum amount of space that \a a is padded to and 

   243     filled with the character \a fillChar.    

   244     \param base The number base.

   245     \param fillChar The fill character.

   166     Inserts an \a argument to a HbParameterLengthLimiter QString.

   259     

   167     

   260     Replaces the placeholders in the translation with runtime values using the 

   168     \attention Cross-Platform API

   261     given parameters and arguments.

   169     

   262     

   170     \param a number that will be inserted to the QString

   263     This function corresponds to QString::arg(long, int, int, const QChar &) const.

   171     \param fieldwidth specifies the minimum amount of space that a is padded to and filled with the character fillChar

   264     

   172     \param base defines the number base

   265     \param a The number that is to be inserted to the output string.    

   173     \param fillChar defines the fill character

   266     \param fieldwidth The minimum amount of space that \a a is padded to and 

   267     filled with the character \a fillChar.    

   268     \param base The number base.

   269     \param fillChar The fill character.

   187     Inserts an \a argument to a HbParameterLengthLimiter QString.

   283     

   188     

   284     Replaces the placeholders in the translation with runtime values using the 

   189     \attention Cross-Platform API

   285     given parameters and arguments.

   190     

   286     

   191     \param a number that will be inserted to the QString

   287     This function corresponds to QString::arg(ulong, int, int, const QChar &) const.

   192     \param fieldwidth specifies the minimum amount of space that a is padded to and filled with the character fillChar

   288     

   193     \param base defines the number base

   289     \param a The number that is to be inserted to the output string.    

   194     \param fillChar defines the fill character

   290     \param fieldwidth The minimum amount of space that \a a is padded to and 

   291     filled with the character \a fillChar.    

   292     \param base The number base.

   293     \param fillChar The fill character.

   207     Inserts an \a argument to a HbParameterLengthLimiter QString.

   306     

   208     

   307     Replaces the placeholders in the translation with runtime values using the 

   209     \attention Cross-Platform API

   308     given parameters and arguments.

   210     

   309     

   211     \param a number that will be inserted to the QString

   310     This function corresponds to QString::arg(int, int, int, const QChar &) const.

   212     \param fieldWidth specifies the minimum amount of space that a is padded to and filled with the character fillChar

   311     

   213     \param base defines the number base

   312     \param a The number that is to be inserted to the output string.    

   214     \param fillChar defines the fill character

   313     \param fieldWidth The minimum amount of space that \a a is padded to and 

   314     filled with the character \a fillChar.    

   315     \param base The number base.

   316     \param fillChar The fill character.

   228     Inserts an \a argument to a HbParameterLengthLimiter QString.

   330     

   229     

   331     Replaces the placeholders in the translation with runtime values using the 

   230     \attention Cross-Platform API

   332     given parameters and arguments.

   231     

   333     

   232     \param a number that will be inserted to the QString

   334     This function corresponds to QString::arg(uint, int, int, const QChar &) const.

   233     \param fieldWidth specifies the minimum amount of space that a is padded to and filled with the character fillChar

   335     

   234     \param base defines the number base

   336     \param a The number that is to be inserted to the output string.    

   235     \param fillChar defines the fill character

   337     \param fieldWidth The minimum amount of space that \a a is padded to and 

   338     filled with the character \a fillChar.    

   339     \param base The number base.

   340     \param fillChar The fill character.

   248     Inserts an \a argument to a HbParameterLengthLimiter QString.

   353     

   249     

   354     Replaces the placeholders in the translation with runtime values using the 

   250     \attention Cross-Platform API

   355     given parameters and arguments.

   251     

   356     

   252     \param a number that will be inserted to the QString

   357     This function corresponds to QString::arg(short, int, int, const QChar &) const.

   253     \param fieldWidth specifies the minimum amount of space that a is padded to and filled with the character fillChar

   358     

   254     \param base defines the number base

   359     \param a The number that is to be inserted to the output string.    

   255     \param fillChar defines the fill character

   360     \param fieldWidth The minimum amount of space that \a a is padded to and 

   361     filled with the character \a fillChar.    

   362     \param base The number base.

   363     \param fillChar The fill character.

   268     Inserts an \a argument to a HbParameterLengthLimiter QString.

   376     

   269     

   377     Replaces the placeholders in the translation with runtime values using the 

   270     \attention Cross-Platform API

   378     given parameters and arguments.

   271     

   379     

   272     \param a number that will be inserted to the QString

   380     This function corresponds to QString::arg(ushort, int, int, const QChar &) const.

   273     \param fieldWidth specifies the minimum amount of space that a is padded to and filled with the character fillChar

   381     

   274     \param base defines the number base

   382     \param a The number that is to be inserted to the output string.    

   275     \param fillChar defines the fill character

   383     \param fieldWidth The minimum amount of space that \a a is padded to and 

   384     filled with the character \a fillChar.    

   385     \param base The number base.

   386     \param fillChar The fill character.

   288     Inserts an \a argument to a HbParameterLengthLimiter QString.

   399     

   289     

   400     Replaces the placeholders in the translation with runtime values using the 

   290     \attention Cross-Platform API

   401     given parameters and arguments.

   291     

   402     

   292     \param a argument a is formatted according to the specified format and precision

   403     This function corresponds to QString::arg(double, int, char, int, const QChar &) const.

   293     \param fieldWidth specifies the minimum amount of space that a is padded to and filled with the character fillChar

   404     

   294     \param fmt defines the format to be used

   405     \param a Value formatted according to the specified format and precision.    

   295     \param prec defines the precision to be used

   406     \param fieldWidth The minimum amount of space that \a a is padded to and 

   296     \param fillChar defines the fill character

   407     filled with the character \a fillChar.    

   408     \param fmt The format to be used.

   409     \param prec The precision to be used.

   410     \param fillChar The fill character.

   310     Inserts an \a argument to a HbParameterLengthLimiter QString.

   424     

   311     

   425     Replaces the placeholders in the translation with runtime values using the 

   312     \attention Cross-Platform API

   426     given parameters and arguments.

   313     

   427     

   314     \param a character that will be inserted to the QString

   428     This function corresponds to QString::arg(char, int, const QChar &) const.

   315     \param fieldWidth specifies the minimum amount of space that a is padded to and filled with the character fillChar

   429     

   316     \param fillChar defines the fill character

   430     \param a The character that is to be inserted to the output string.    

   431     \param fieldWidth The minimum amount of space that \a a is padded to and 

   432     filled with the character \a fillChar.    

   433     \param fillChar The fill character.

   328     Inserts an \a argument to a HbParameterLengthLimiter QString.

   445     

   329     

   446     Replaces the placeholders in the translation with runtime values using the 

   330     \attention Cross-Platform API

   447     given parameters and arguments.

   331     

   448     

   332     \param a character that will be inserted to the QString

   449     This function corresponds to QString::arg(QChar, int, const QChar &) const.

   333     \param fieldWidth specifies the minimum amount of space that a is padded to and filled with the character fillChar

   450     

   334     \param fillChar defines the fill character

   451     \param a The character that is to be inserted to the output string.    

   452     \param fieldWidth The minimum amount of space that \a a is padded to and 

   453     filled with the character \a fillChar.    

   454     \param fillChar The fill character.

   346     Inserts an \a argument to a HbParameterLengthLimiter QString.

   466     

   347     

   467     Replaces the placeholders in the translation with runtime values using the 

   348     \attention Cross-Platform API

   468     given parameters and arguments. Limits the length of the inserted value, if 

   349     

   469     this is specified in the placeholder using the [] notation.

   350     \param a string that will be inserted to the QString

   470     

   351     \param fieldWidth specifies the minimum amount of space that a is padded to and filled with the character fillChar

   471     This function corresponds to QString::arg(const QString &, int, const QChar &) const.

   352     \param fillChar defines the fill character

   472     

   473     \param a The string that is to be inserted to the output string.    

   474     \param fieldWidth The minimum amount of space that \a a is padded to and 

   475     filled with the character \a fillChar.    

   476     \param fillChar The fill character.

   486     Inserts an arguments a1 and a2 to a HbParameterLengthLimiter QString.

   610 

   487     

   611     Replaces the placeholders in the translation with the given strings using 

   488     \attention Cross-Platform API

   612     the arguments (\a a1 and \a a2). Limits the length of the inserted value, if 

   489     

   613     this is specified in the placeholder using the [] notation.

   490     \param a1 string that will be inserted to the QString

   614     

   491     \param a2 string that will be inserted to the QString

   615     This function corresponds to QString::arg(const QString &, const QString &) const.

   616     

   501     Inserts an arguments a1, a2 and a3 to a HbParameterLengthLimiter QString.

   626 

   502     

   627     Replaces the placeholders in the translation with the given strings using 

   503     \attention Cross-Platform API

   628     the arguments (\a a1, \a a2, and so on). Limits the length of the inserted 

   504     

   629     value, if this is specified in the placeholder using the [] notation.

   505     \param a1 string that will be inserted to the QString

   630     

   506     \param a2 string that will be inserted to the QString

   631     This function corresponds to QString::arg(const QString &, const QString &, const QString &) const.

   507     \param a3 string that will be inserted to the QString

   632     

   518     Inserts an arguments a1, a2, a3 and a4 to a HbParameterLengthLimiter QString.

   643 

   519     

   644     Replaces the placeholders in the translation with the given strings using 

   520     \attention Cross-Platform API

   645     the arguments (\a a1, \a a2, and so on). Limits the length of the inserted 

   521     

   646     value, if this is specified in the placeholder using the [] notation.

   522     \param a1 string that will be inserted to the QString

   647     

   523     \param a2 string that will be inserted to the QString

   648     This function corresponds to QString::arg(const QString &, const QString &, const QString &, const QString &) const.

   524     \param a3 string that will be inserted to the QString

   649     

   525     \param a4 string that will be inserted to the QString

   537     Inserts an arguments a1, a2, a3, a4 and a5 to a HbParameterLengthLimiter QString.

   661 

   538     

   662     Replaces the placeholders in the translation with the given strings using 

   539     \attention Cross-Platform API

   663     the arguments (\a a1, \a a2, and so on). Limits the length of the inserted 

   540     

   664     value, if this is specified in the placeholder using the [] notation.

   541     \param a1 string that will be inserted to the QString

   665     

   542     \param a2 string that will be inserted to the QString

   666     This function corresponds to QString::arg(const QString &, const QString &, const QString &, const QString &, const QString &) const.

   543     \param a3 string that will be inserted to the QString

   667     

   544     \param a4 string that will be inserted to the QString

   545     \param a5 string that will be inserted to the QString

   558     Inserts an arguments a1, a2, a3, a4, a5 and a6 to a HbParameterLengthLimiter QString.

   680     

   559     

   681     Replaces the placeholders in the translation with the given strings using 

   560     \attention Cross-Platform API

   682     the arguments (\a a1, \a a2, and so on). Limits the length of the inserted 

   561     

   683     value, if this is specified in the placeholder using the [] notation.

   562     \param a1 string that will be inserted to the QString

   684     

   563     \param a2 string that will be inserted to the QString

   685     This function corresponds to QString::arg(const QString &, const QString &, const QString &, const QString &, const QString &, const QString &) const.

   564     \param a3 string that will be inserted to the QString

   686     

   565     \param a4 string that will be inserted to the QString

   566     \param a5 string that will be inserted to the QString

   567     \param a6 string that will be inserted to the QString

   581     Inserts an arguments a1, a2, a3, a4, a5, a6 and a7 to a HbParameterLengthLimiter QString.

   700     

   582     

   701     Replaces the placeholders in the translation with the given strings using 

   583     \attention Cross-Platform API

   702     the arguments (\a a1, \a a2, and so on). Limits the length of the inserted 

   584     

   703     value, if this is specified in the placeholder using the [] notation.

   585     \param a1 string that will be inserted to the QString

   704     

   586     \param a2 string that will be inserted to the QString

   705     This function corresponds to QString::arg(const QString &, const QString &, const QString &, const QString &, const QString &, const QString &, const QString &) const.

   587     \param a3 string that will be inserted to the QString

   706     

   588     \param a4 string that will be inserted to the QString

   589     \param a5 string that will be inserted to the QString

   590     \param a6 string that will be inserted to the QString

   591     \param a7 string that will be inserted to the QString

   606     Inserts an arguments a1, a2, a3, a4, a5, a6, a7 and a8 to a HbParameterLengthLimiter QString.

   721     

   607     

   722     Replaces the placeholders in the translation with the given strings using 

   608     \attention Cross-Platform API

   723     the arguments (\a a1, \a a2, and so on). Limits the length of the inserted 

   609     

   724     value, if this is specified in the placeholder using the [] notation.

   610     \param a1 string that will be inserted to the QString

   725     

   611     \param a2 string that will be inserted to the QString

   726     This function corresponds to QString::arg(const QString &, const QString &, const QString &, const QString &, const QString &, const QString &, const QString &, const QString &) const.

   612     \param a3 string that will be inserted to the QString

   727     

   613     \param a4 string that will be inserted to the QString

   614     \param a5 string that will be inserted to the QString

   615     \param a6 string that will be inserted to the QString

   616     \param a7 string that will be inserted to the QString

   617     \param a8 string that will be inserted to the QString

   633     Inserts an arguments a1, a2, a3, a4, a5, a6, a7, a8 and a9 to a HbParameterLengthLimiter QString.

   743     

   634     

   744     Replaces the placeholders in the translation with the given strings using 

   635     \attention Cross-Platform API

   745     the arguments (\a a1, \a a2, and so on). Limits the length of the inserted 

   636     

   746     value, if this is specified in the placeholder using the [] notation.

   637     \param a1 string that will be inserted to the QString

   747     

   638     \param a2 string that will be inserted to the QString

   748     This function corresponds to QString::arg(const QString &, const QString &, const QString &, const QString &, const QString &, const QString &, const QString &, const QString &, const QString &) const.

   639     \param a3 string that will be inserted to the QString

   749     

   640     \param a4 string that will be inserted to the QString

   641     \param a5 string that will be inserted to the QString

   642     \param a6 string that will be inserted to the QString

   643     \param a7 string that will be inserted to the QString

   644     \param a8 string that will be inserted to the QString

   645     \param a9 string that will be inserted to the QString

   662     Changes the QString that is to be used for inserting arguments to QString.

   766 

   663     

   767     Sets the localized string of the HbParameterLengthLimiter object to the 

   664     \attention Cross-Platform API

   768     value of the \a a string.

   665     

   769     

   666     \param a QString that will be used for inserting arguments

   675     Changes the QString that is to be used for inserting arguments to HbParameterLengthLimiter.

   778 

   676     

   779     Sets the localized string of the target HbParameterLengthLimiter object to 

   677     \attention Cross-Platform API

   780     the string contained in the \a a object.

   678     

   781     

   679     \param a HbParameterLengthLimiter holding the QString that will be used for inserting arguments

   688     Returns the current QString.

   790 

   689     

   791     Implicit conversion function that allows you to pass an 

   690     \attention Cross-Platform API    

   792     HbParameterLengthLimiter object in a context where a QString object is 

   793     expected. For example, you can use an HbParameterLengthLimiter object when 

   794     setting the localized text in a widget, rather than first getting the string 

   795     out of HbParameterLengthLimiter and then passing it to the widget.

   796