tip490 oo for msgcat: added documentation

1 files changed, 100 insertions, 7 deletions

diff --git a/doc/msgcat.n b/doc/msgcat.n
index 2fc1eee..fbea20f 100644
--- a/doc/msgcat.n
+++ b/doc/msgcat.n
@@ -11,9 +11,9 @@
 .SH NAME
 msgcat \- Tcl message catalog
 .SH SYNOPSIS
-\fBpackage require Tcl 8.5\fR
+\fBpackage require Tcl 8.7\fR
 .sp
-\fBpackage require msgcat 1.6\fR
+\fBpackage require msgcat 1.7\fR
 .sp
 \fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR?
 .sp
@@ -23,6 +23,10 @@ msgcat \- Tcl message catalog
 \fB::msgcat::mcexists\fR ?\fB-exactnamespace\fR? ?\fB-exactlocale\fR? \fIsrc-string\fR
 .VE "TIP 412"
 .sp
+.VS "TIP 490"
+\fB::msgcat::mcpackagenamespaceget\fR
+.VE "TIP 490"
+.sp
 \fB::msgcat::mclocale \fR?\fInewLocale\fR?
 .sp
 \fB::msgcat::mcpreferences\fR
@@ -71,6 +75,11 @@ In \fBmsgcat\fR, there is a global locale initialized by the system locale of th
 Each package may decide to use the global locale or to use a package specific locale.
 .PP
 The global locale may be changed on demand, for example by a user initiated language change or within a multi user application like a web server.
+.PP
+.VS tip490
+Object oriented programming is supported by the use of a package namespace.
+.VE tip490
+.PP
 .SH COMMANDS
 .TP
 \fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR?
@@ -95,6 +104,17 @@ use the result.  If an application is written for a single language in
 this fashion, then it is easy to add support for additional languages
 later simply by defining new message catalog entries.
 .RE
+.VS "TIP 490"
+.TP
+\fB::msgcat::mcn \fInamespace\fR \fIsrc-string\fR ?\fIarg arg ...\fR?
+.
+Like \fB::msgcat::mc\fR, but with the message namespace specified as first argument.
+.PP
+.RS
+\fBmcn\fR may be used for cases where the package namespace is not the namespace of the caller.
+An example is shown within the description of the command \fB::msgcat::mcpackagenamespaceget\fR below.
+.RE
+.PP
 .TP
 \fB::msgcat::mcmax ?\fIsrc-string src-string ...\fR?
 .
@@ -103,17 +123,49 @@ of the longest translated string.  This is useful when designing
 localized GUIs, which may require that all buttons, for example, be a
 fixed width (which will be the width of the widest button).
 .TP
-\fB::msgcat::mcexists\fR ?\fB-exactnamespace\fR? ?\fB-exactlocale\fR? \fIsrc-string\fR
-.
 .VS "TIP 412"
+\fB::msgcat::mcexists\fR ?\fB-exactnamespace\fR? ?\fB-exactlocale\fR? ?\fB-namespace\fR \fInamespace\fR? \fIsrc-string\fR
+.
 Return true, if there is a translation for the given \fIsrc-string\fR.
 .PP
 .RS
 The search may be limited by the option \fB\-exactnamespace\fR to only check the current namespace and not any parent namespaces.
 .PP
 It may also be limited by the option \fB\-exactlocale\fR to only check the first prefered locale (e.g. first element returned by \fB::msgcat::mcpreferences\fR if global locale is used).
-.RE
+.PP
 .VE "TIP 412"
+.VS "TIP 490"
+An explicit package namespace may be specified by the option \fB-namespace\fR.
+The namespace of the caller is used if not explicitly specified.
+.RE
+.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}]
+    ...
+    bind $widget  [list ::tooltip::show $widget $messagenamespace $message]
+}
+
+proc ::tooltip::show {widget messagenamespace message} {
+    ...
+    set message [::msgcat::mcn $messagenamespace $message]
+    ...
+}
+.CE
+.RE
+.PP
+.VE "TIP 490"
 .TP
 \fB::msgcat::mclocale \fR?\fInewLocale\fR?
 .
@@ -563,7 +615,7 @@ A generic unknown handler is used if set to the empty string. This consists in r
 See section \fBcallback invocation\fR below.
 The appended arguments are identical to \fB::msgcat::mcunknown\fR.
 .RE
-.SS Callback invocation
+.SH Callback invocation
 A package may decide to register one or multiple callbacks, as described above.
 .PP
 Callbacks are invoked, if:
@@ -577,7 +629,48 @@ Callbacks are invoked, if:
 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
-.SS Examples
+.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
+.SH 1) In class definition script
+\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
+.SH 2) method defined in a class
+\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
+.SH 3) method defined in a classless object
+\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