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
