Could we/May I fix the Swing Tutorial for Monitoring Progress?

[Philip Race]

This won't be possible. The tutorial is not maintained as part of the 
OpenJDK project.
It is an Oracle proprietary document owned by the appropriate Oracle 
internal organisation.
So you won't find the source for it anywhere.

-phil.

On 10/6/23 10:50 PM, David Alayachew wrote:
> Hello Client Libs Dev Team,
>
> The Swing tutorials found here 
> (https://docs.oracle.com/javase/tutorial/uiswing/) are top-notch, as 
> detailed as they need to be, and beginner friendly. These tutorials 
> are excellent, and I have most of the links on that page bookmarked, 
> as I reference them frequently when building GUI's.
>
> That is why it is so surprising to see that the tutorial for 
> Monitoring Progress is so much worse than most of the others. Here is 
> a link to the tutorial in question.
>
> https://docs.oracle.com/javase/tutorial/uiswing/components/progress.html
>
> I have the short version of my thoughts here 
> (https://stackoverflow.com/questions/24835638/issues-with-swingworker-and-jprogressbar/24835935#comment136182857_24835935). 
> But I'll try and keep things down to what's needed.
>
> For starters, the tutorial feels backwards. Normally, you would start 
> with the most basic/common use-cases first, then delve into the 
> fringe/uncommon use-cases later on in the tutorial. That is not what 
> happens. We start off with the more complex and configurable 
> JProgressBar, and it is only after we reach the halfway point of the 
> tutorial, does it decide to let us know that the ProgressMonitor, the 
> simpler and more constrained option, is available to us. This makes 
> the on-ramp for learning this tool needlessly steeper, just by 
> approaching things in the wrong order.
>
> Compare and contrast this to the Dialog tutorial 
> (https://docs.oracle.com/javase/tutorial/uiswing/components/dialog.html). 
> They follow a similar premise -- there is the complex JDialog, and the 
> simple JOptionPane. However, the Dialog tutorial gets it right. They 
> start off with an explicit intro that says "Here are 2 API's, one 
> complex, one simple. We will start with the simple one, but if it does 
> not meet your needs, you can easily switch to (or even compose your 
> JOptionPane into) the JDialog, allowing you to add complexity, only 
> where necessary." This is beginner friendly because it gives the most 
> common use case first, and then lets the user read on if they need 
> something more complex.
>
> Next, the code example they gave is spaghetti-code. Please look at it 
> here 
> (https://docs.oracle.com/javase/tutorial/uiswing/examples/components/ProgressBarDemoProject/src/components/ProgressBarDemo.java). 
> Everything is bundled into a single file, when there's really at least 
> 3 files here. It makes the example so difficult to read and follow 
> along with, as you struggle to put boundaries on what can and cannot 
> occur at any given point in the code.
>
> After that, they pick the most beginner unfriendly way to demonstrate 
> concurrency to the user.
>
> Monitoring progress and updating the progress bar simultaneously 
> necessitates using Concurrency in Swing (understandable). Therefore, 
> the tutorial encourages the user to accomplish this using the class 
> SwingWorker (as they should). But then, they pick the literal most 
> complex and foot-gun like way to do things - so much so that it 
> defeats the entire point.
>
> They tell the user to use SwingWorker::setProgress, which fires an 
> event to PropertyChangeListener, which can then be extracted from the 
> ::getNewValue method from the "progress" PropertyChangeEvent. Already, 
> that's unideal, but the real footgun is that there is the undocumented 
> invariant that the value you pass to ::setProgress must be between 
> 0-100. This is particularly foot-gun like because JProgressBar allows 
> you to set the value to whatever you want, and it will calculate the 
> ratio for you (very nice). Many developers will opt in to this 
> convenience feature, and thus, will be setting themselves up for 
> failure when they try to follow the tutorials direction of using a 
> PropertyChangeListener, thinking they can just pass in the new value 
> for JProgressBar::setValue via the PropertyChangeListener.
>
> This entire foot-gun situation could have easily been avoided if they 
> just used the ::publish/::process pair of methods, which are not only 
> simpler, but also facilitate the bundling of events, should the 
> developer choose to get involved with that.
>
> Hopefully I have demonstrated how this particular tutorial has problems.
>
> If so, I volunteer my time and efforts to fixing this tutorial. If 
> anyone could point me to the right place, I will happily submit a JBS 
> ticket, and then get started making the commit.
>
> And I want to emphasize - the Oracle Swing tutorials are excellent. I 
> tutor, and when I teach Swing/GUI's, I always encourage them to start 
> with the Oracle Swing tutorials. That's my biggest reason for doing 
> this - I want to be able to say that about this tutorial too.
>
> Please let me know your thoughts.
>
> Thank you all for your time!
> David Alayachew
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/client-libs-dev/attachments/20231008/5483e192/attachment.htm>