Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | close fork |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | core-8-branch |
Files: | files | file ages | folders |
SHA3-256: |
35a6b8673b6e0ae1435f18fa07211d2f |
User & Date: | dgp 2018-03-13 16:29:50.502 |
Context
2018-03-14
| ||
22:56 | another range check-in: b285990627 user: dgp tags: mistake | |
2018-03-13
| ||
17:14 | merge 8.6 check-in: 1a04240e68 user: dgp tags: core-8-branch | |
16:29 | close fork check-in: 35a6b8673b user: dgp tags: core-8-branch | |
16:28 | Fix bugs in msgcat that prevent clean test suite run. check-in: 47d13b9fc2 user: dgp tags: core-8-branch | |
16:13 | tip 499 msgcat custom preferences: documentation added check-in: edef076fc6 user: oehhar tags: core-8-branch | |
Changes
Changes to doc/msgcat.n.
︙ | ︙ | |||
25 26 27 28 29 30 31 | .sp .VS "TIP 490" \fB::msgcat::mcpackagenamespaceget\fR .VE "TIP 490" .sp \fB::msgcat::mclocale \fR?\fInewLocale\fR? .sp | > | > | 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 | .sp .VS "TIP 490" \fB::msgcat::mcpackagenamespaceget\fR .VE "TIP 490" .sp \fB::msgcat::mclocale \fR?\fInewLocale\fR? .sp .VS "TIP 499" \fB::msgcat::mcpreferences\fR ?\fIlocale preference\fR? ... .VE "TIP 499" .sp .VS "TIP 412" \fB::msgcat::mcloadedlocales subcommand\fR ?\fIlocale\fR? .VE "TIP 412" .sp \fB::msgcat::mcload \fIdirname\fR .sp |
︙ | ︙ | |||
50 51 52 53 54 55 56 57 58 59 60 61 62 63 | .VS "TIP 412" \fB::msgcat::mcpackagelocale subcommand\fR ?\fIlocale\fR? .sp \fB::msgcat::mcpackageconfig subcommand\fR \fIoption\fR ?\fIvalue\fR? .sp \fB::msgcat::mcforgetpackage\fR .VE "TIP 412" .BE .SH DESCRIPTION .PP The \fBmsgcat\fR package provides a set of functions that can be used to manage multi-lingual user interfaces. Text strings are defined in a .QW "message catalog" | > > > > | 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 | .VS "TIP 412" \fB::msgcat::mcpackagelocale subcommand\fR ?\fIlocale\fR? .sp \fB::msgcat::mcpackageconfig subcommand\fR \fIoption\fR ?\fIvalue\fR? .sp \fB::msgcat::mcforgetpackage\fR .VE "TIP 412" .sp .VS "TIP 499" \fB::msgcat::mcutil subcommand\fR ?\fIlocale\fR? .VS "TIP 499" .BE .SH DESCRIPTION .PP The \fBmsgcat\fR package provides a set of functions that can be used to manage multi-lingual user interfaces. Text strings are defined in a .QW "message catalog" |
︙ | ︙ | |||
141 142 143 144 145 146 147 | .PP .VE "TIP 490" .VS "TIP 490" .TP \fB::msgcat::mcpackagenamespaceget\fR . Return the package namespace of the caller. | | | 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 | .PP .VE "TIP 490" .VS "TIP 490" .TP \fB::msgcat::mcpackagenamespaceget\fR . Return the package namespace of the caller. This command handles all cases described in section \fBOBJECT ORIENTED PROGRAMMING\fR. .PP .RS Example usage is a tooltip package, which saves the caller package namespace to update the translation each time the tooltip is shown: .CS proc ::tooltip::tooltip {widget message} { ... set messagenamespace [uplevel 1 {::msgcat::mcpackagenamespaceget}] |
︙ | ︙ | |||
165 166 167 168 169 170 171 | .CE .RE .PP .VE "TIP 490" .TP \fB::msgcat::mclocale \fR?\fInewLocale\fR? . | < | | > > > > > > > > > > < | | | | > > > | > > | > | > | < > > > > | 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 | .CE .RE .PP .VE "TIP 490" .TP \fB::msgcat::mclocale \fR?\fInewLocale\fR? . If \fInewLocale\fR is omitted, the current locale is returned, otherwise the current locale is set to \fInewLocale\fR. .PP .RS If the new locale is set to \fInewLocale\fR, the corresponding preferences are calculated and set. For example, if the current locale is en_US_funky, then \fB::msgcat::mcpreferences\fR returns \fB{en_us_funky en_us en {}}\fR. .PP The same result may be acheved by \fB::msgcat::mcpreferences\fR {*}[\fB::msgcat::mcutil getpreferences\fR \fInewLocale\fR]. .PP The current locale is always the first element of the list returned by \fBmcpreferences\fR. .PP msgcat stores and compares the locale in a case-insensitive manner, and returns locales in lowercase. The initial locale is determined by the locale specified in the user's environment. See \fBLOCALE SPECIFICATION\fR below for a description of the locale string format. .PP .VS "TIP 412" If the locale is set, the preference list of locales is evaluated. Locales in this list are loaded now, if not jet loaded. .VE "TIP 412" .RE .TP \fB::msgcat::mcpreferences\fR ?\fIlocale preference\fR? ... . Without arguments, returns an ordered list of the locales preferred by the user. The list is ordered from most specific to least preference. .PP .VS "TIP 499" .RS A set of locale preferences may be given to set the list of locale preferences. The current locale is also set, which is the first element of the locale preferences list. .PP Locale preferences are loaded now, if not jet loaded. .PP As an example, the user may prefer French or English text. This may be configured by: .CS ::msgcat::mcpreferences fr en {} .CE .RE .PP .VS "TIP 499" .TP \fB::msgcat:mcloadedlocales subcommand\fR ?\fIlocale\fR? . This group of commands manage the list of loaded locales for packages not setting a package locale. .PP .RS The subcommand \fBget\fR returns the list of currently loaded locales. |
︙ | ︙ | |||
279 280 281 282 283 284 285 286 287 288 289 290 291 292 | Note that this routine is only called if the concerned package did not set a package locale unknown command name. .RE .TP \fB::msgcat::mcforgetpackage\fR . The calling package clears all its state within the \fBmsgcat\fR package including all settings and translations. .VE "TIP 412" .PP .SH "LOCALE SPECIFICATION" .PP The locale is specified to \fBmsgcat\fR by a locale string passed to \fB::msgcat::mclocale\fR. The locale string consists of a language code, an optional country code, and an optional | > > > > > > > > > > > > > > > > | 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 | Note that this routine is only called if the concerned package did not set a package locale unknown command name. .RE .TP \fB::msgcat::mcforgetpackage\fR . The calling package clears all its state within the \fBmsgcat\fR package including all settings and translations. .VE "TIP 412" .PP .VS "TIP 499" .TP \fB::msgcat::mcutil getpreferences\fR \fIlocale\fR . Return the preferences list of the given locale as described in section \fBLOCALE SPECIFICATION\fR. An example is the composition of a preference list for the bilingual region "Biel/Bienne" as a concatenation of swiss german and swiss french: .CS % concat [lrange [msgcat::mcutil getpreferences fr_CH] 0 end-1] [msgcat::mcutil getpreferences de_CH] fr_ch fr de_ch de {} .CE .TP \fB::msgcat::mcutil getsystemlocale\fR . The system locale is returned as described by the section \fBLOCALE SPECIFICATION\fR. .VE "TIP 499" .PP .SH "LOCALE SPECIFICATION" .PP The locale is specified to \fBmsgcat\fR by a locale string passed to \fB::msgcat::mclocale\fR. The locale string consists of a language code, an optional country code, and an optional |
︙ | ︙ | |||
485 486 487 488 489 490 491 | .PP .CS \fBmsgcat::mc\fR {Produced %1$d at %2$s} $num $city # ... where that key is mapped to one of the # human-oriented versions by \fBmsgcat::mcset\fR .CE .VS "TIP 412" | | | 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 | .PP .CS \fBmsgcat::mc\fR {Produced %1$d at %2$s} $num $city # ... where that key is mapped to one of the # human-oriented versions by \fBmsgcat::mcset\fR .CE .VS "TIP 412" .SH "PACKAGE PRIVATE LOCALE" .PP A package using \fBmsgcat\fR may choose to use its own package private locale and its own set of loaded locales, independent to the global locale set by \fB::msgcat::mclocale\fR. .PP This allows a package to change its locale without causing any locales load or removal in other packages and not to invoke the global locale change callback (see below). .PP |
︙ | ︙ | |||
509 510 511 512 513 514 515 | This command may cause the load of locales. .RE .TP \fB::msgcat::mcpackagelocale get\fR . Return the package private locale or the global locale, if no package private locale is set. .TP | | | > > > > > > > > > > > > | 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 | This command may cause the load of locales. .RE .TP \fB::msgcat::mcpackagelocale get\fR . Return the package private locale or the global locale, if no package private locale is set. .TP \fB::msgcat::mcpackagelocale preferences\fR ?\fIlocale preference\fR? ... . With no parameters, return the package private preferences or the global preferences, if no package private locale is set. The package locale state (set or not) is not changed (in contrast to the command \fB::msgcat::mcpackagelocale set\fR). .PP .RS .VS "TIP 499" If a set of locale preferences is given, it is set as package locale preference list. The package locale is set to the first element of the preference list. A package locale is activated, if it was not set so far. .PP Locale preferences are loaded now for the package, if not jet loaded. .VE "TIP 499" .RE .PP .TP \fB::msgcat::mcpackagelocale loaded\fR . Return the list of locales loaded for this package. .TP \fB::msgcat::mcpackagelocale isset\fR . |
︙ | ︙ | |||
536 537 538 539 540 541 542 | . Returns true, if the given locale is loaded for the package. .TP \fB::msgcat::mcpackagelocale clear\fR . Clear any loaded locales of the package not present in the package preferences. .PP | | | 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 | . Returns true, if the given locale is loaded for the package. .TP \fB::msgcat::mcpackagelocale clear\fR . Clear any loaded locales of the package not present in the package preferences. .PP .SH "CHANGING PACKAGE OPTIONS" .PP Each package using msgcat has a set of options within \fBmsgcat\fR. The package options are described in the next sectionPackage options. Each package option may be set or unset individually using the following ensemble: .TP \fB::msgcat::mcpackageconfig get\fR \fIoption\fR . |
︙ | ︙ | |||
611 612 613 614 615 616 617 | The called procedure must return the formatted message which will finally be returned by msgcat::mc. .PP A generic unknown handler is used if set to the empty string. This consists in returning the key if no arguments are given. With given arguments, format is used to process the arguments. .PP See section \fBcallback invocation\fR below. The appended arguments are identical to \fB::msgcat::mcunknown\fR. .RE | | | > | > > | > > | > | | 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 | The called procedure must return the formatted message which will finally be returned by msgcat::mc. .PP A generic unknown handler is used if set to the empty string. This consists in returning the key if no arguments are given. With given arguments, format is used to process the arguments. .PP See section \fBcallback invocation\fR below. The appended arguments are identical to \fB::msgcat::mcunknown\fR. .RE .SH "Callback invocation" A package may decide to register one or multiple callbacks, as described above. .PP Callbacks are invoked, if: .PP 1. the callback command is set, .PP 2. the command is not the empty string, .PP 3. the registering namespace exists. .PP If a called routine fails with an error, the \fBbgerror\fR routine for the interpreter is invoked after command completion. Only exception is the callback \fBunknowncmd\fR, where an error causes the invoking \fBmc\fR-command to fail with that error. .PP .VS tip490 .SH "OBJECT ORIENTED PROGRAMMING" \fBmsgcat\fR supports packages implemented by object oriented programming. Objects and classes should be defined within a package namespace. .PP There are 3 supported cases where package namespace sensitive commands of msgcat (\fBmc\fR, \fBmcexists\fR, \fBmcpackagelocale\fR, \fBmcforgetpackage\fR, \fBmcpackagenamespaceget\fR, \fBmcpackageconfig\fR, \fBmcset\fR and \fBmcmset\fR) may be called: .PP .TP \fB1) In class definition script\fR . \fBmsgcat\fR command is called within a class definition script. .CS namespace eval ::N2 { mcload $dir/msgs oo::class create C1 {puts [mc Hi!]} } .CE .PP .TP \fB2) method defined in a class\fR . \fBmsgcat\fR command is called from a method in an object and the method is defined in a class. .CS namespace eval ::N3Class { mcload $dir/msgs oo::class create C1 oo::define C1 method m1 { puts [mc Hi!] } } .CE .PP .TP \fB3) method defined in a classless object\fR . \fBmsgcat\fR command is called from a method of a classless object. .CS namespace eval ::N4 { mcload $dir/msgs oo::object create O1 oo::objdefine O1 method m1 {} { puts [mc Hi!] } } .CE .PP .VE tip490 .SH EXAMPLES Packages which display a GUI may update their widgets when the global locale changes. To register to a callback, use: .CS namespace eval gui { msgcat::mcpackageconfig changecmd updateGUI proc updateGui args { |
︙ | ︙ | |||
732 733 734 735 736 737 738 | } .CE .VE "TIP 412" .SH CREDITS .PP The message catalog code was developed by Mark Harrison. .SH "SEE ALSO" | | | | 790 791 792 793 794 795 796 797 798 799 800 801 802 | } .CE .VE "TIP 412" .SH CREDITS .PP The message catalog code was developed by Mark Harrison. .SH "SEE ALSO" format(n), scan(n), namespace(n), package(n), oo::class(n), oo::object .SH KEYWORDS internationalization, i18n, localization, l10n, message, text, translation, class, object .\" Local Variables: .\" mode: nroff .\" End: |