What is Tk::Message good for?

[asb-capfan]

In the Tk::UserGuide, the standard widget Tk::Message is listed.
However, after reading the POD, I have no idea what Tk::Message should be good for.

What is it good for? Where / How can I use it? How should I use it?

Links:

• https://metacpan.org/pod/distribution/Tk/pod/Message.pod
• https://metacpan.org/pod/distribution/Tk/pod/UserGuide.pod

[chrstphrchvz]

It looks very similar to a Label widget. There are a few bundled examples that use Message, e.g. basic_demo:

perl-tk/examples/basic_demo

Lines 124 to 131 in 806e6b3

	sub message
	{
	my $top = shift;
	my $w = $top->Message("-text","Press keys in blue square");
	configure $w "-foreground","blue";
	$w->pack("-fill"=>"x");
	return $w;
	}

I agree Perl/Tk's documentation of Message is quite sparse, but it states the usual historical differences over Label: it can automatically wrap multiple lines of text and maintain a given aspect ratio. There might be more in Tk for Tcl or other languages' documentation (though I'm not sure it's 1:1 with Perl/Tk's Message). TkDocs even says there's no need for Message anymore since label has a wraplength option and accepts "\n" as a manual line break.

[asb-capfan]

Ah ok, this is very helpful. Thank you.
Maybe I was distracted by the first section in the Description:

The Message method creates a new window (given by the $widget argument) and makes it into a message widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the message such as its colors, font, text, and initial relief. The message command returns its $widget argument. At the time this command is invoked, there must not exist a window named $widget, but $widget's parent must exist.

Coudn't this be omitted, or maybe replaced by an example?
If yes, please let me know, I will create the pull request.

[chrstphrchvz]

Maybe I was distracted by the first section in the Description:

The Message method creates a new window (given by the $widget argument) and makes it into a message widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the message such as its colors, font, text, and initial relief. The message command returns its $widget argument. At the time this command is invoked, there must not exist a window named $widget, but $widget's parent must exist.

I found that confusing as as well, I didn't know what it meant by creating a new window and how that applies to a Message widget—for a moment I thought maybe it was referring to MessageBox.

But it turns out that verbiage was probably lifted from https://www.tcl.tk/man/tcl/TkCmd/message.htm#M9, and just wasn't adapted very well to Perl/Tk syntax since it sounds like it still refers to Tcl syntax (other widgets have the same verbiage in their Tcl docs). So it probably doesn't belong.

As far as what does belong, I would've suggested checking 3rd party docs, but there's little mention of Message anywhere (not even in the comprehensive Mastering Perl/Tk). Maybe suggesting Label as a better-documented alternative is a start.

But note, I'm not an official contributor/maintainer, nor very experienced with Perl and/or Tk.

[eserte]

It seems that the term "window" causes confusion here. This is the X11 heritage shining through: in X11, there's a data type named "Window" which is just a rectangular area on the screen, not necessarily a toplevel window as users would expect nowadays. If you check the other Perl/Tk manpages (Tk::Button, Tk::Label etc.), then you can see that the term "window" is used everywhere.

As for the initial question: I think the description is quite clear what it does what a Tk::Label doesn't. However, Tk::Label is not mentioned here, unlike in the new version of the Tcl/Tk counterpart (see https://www.tcl.tk/man/tcl8.6/TkCmd/message.htm#M9 : "... that differentiate it from a label widget ..."). Maybe this should be added here. Otherwise I don't think the doc needs much changing.

[asb-capfan]

As for the initial question: I think the description is quite clear what it does what a Tk::Label doesn't.

No, it's not. It might be clear for you, but after all. documentation is for the users.
The X11 heritage as well as the description style and the missing example in SYNOPSIS are just plain bad.
Evidence supports this, as I did not find any question about Tk::message using a search engine, and no example code (I even had to create a question here).

As for what needs changing from my point of view, please have a look at the pull request. Everything is fine if it counts as little change for you.