JDK-8210361 : Add images to docs for public API classes of controls and missing examples
  • Type: Enhancement
  • Component: javafx
  • Sub-Component: controls
  • Priority: P4
  • Status: Resolved
  • Resolution: Fixed
  • Submitted: 2018-09-04
  • Updated: 2020-08-20
  • Resolved: 2019-01-29
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
Other
openjfx12Fixed
Related Reports
Blocks :  
JDK-8211014 - Fix mistakes in FX API docs
Duplicate :  
JDK-8252095 - RadioMenuItem javadoc sample has typos
Description
The JavaDoc for various controls (Button, ComboBox, TableView...) could really benefit from a representative picture (screenshot) of the control.

Developers that read the class description would like to know what the control looks like and seeing it is more helpful than the sentence describing it.

This was done back in AWT (e.g., https://docs.oracle.com/javase/10/docs/api/java/awt/TextArea.html), but not in Swing.
Comments
The latest (.02) patch looks good to me, too. +1
28-01-2019
I am OK with the changes. +1.
28-01-2019
diff.02.patch available at http://cr.openjdk.java.net/~nlisker/8210361/
28-01-2019
Please also provide the "git diff" patch since Ajit will need that to push (else we won't have the added .png files). Btw, you got all but one of the white space issues: modules/javafx.controls/src/main/java/javafx/scene/control/TableView.java:153: Trailing whitespace Ajit can correct that when pushing.
28-01-2019
New Webrev: http://cr.openjdk.java.net/~nlisker/8210361/webrev.02/ Fixed points 2 and 3. checkWhiteSpace reported OK on all the files even before the changes, so it was not detecting the changeset even after a local commit and giving it a revision number. I think I got them all, but if a few are left they can be fixed during the commit.
28-01-2019
[~nlisker] I don't have any.
28-01-2019
Ajit, do you have any other comments?
25-01-2019
I think it is fine to have the controls be of different sizes for the reasons Nir mentioned. I spot checked several of the controls and they look good to me, although I saw one issue: 1. The ProgressBar and ProgressIndicator docs still have the following text (and it appears to the right of the second image in each). Implementation of ProgressBar (ProgressIndicator) According to JavaFX UI Control API Specification I also note the following general problems that need to be addressed: 2. There are white-space problems in the following files: $ bash tools/scripts/checkWhiteSpace modules/javafx.controls/src/main/java/javafx/scene/control/CheckMenuItem.java :trailingWhitespace: modules/javafx.controls/src/main/java/javafx/scene/control/ComboBox.java :trailingWhitespace: modules/javafx.controls/src/main/java/javafx/scene/control/ContextMenu.java :trailingWhitespace: modules/javafx.controls/src/main/java/javafx/scene/control/ProgressBar.java :trailingWhitespace: modules/javafx.controls/src/main/java/javafx/scene/control/RadioMenuItem.java :trailingWhitespace: modules/javafx.controls/src/main/java/javafx/scene/control/TableView.java :trailingWhitespace: modules/javafx.controls/src/main/java/javafx/scene/control/TreeTableView.java :trailingWhitespace: 3. Please use an underscore rather than a space ' ' in the following filenames: ProgressBar indeterminate.png ProgressIndicator indeterminate.png We prefer to avoid files with spaces in their names. [Edited to add] I missed your earlier note about the "...According to JavaFX UI Control API Specification" comments, so you can ignore point #1 above for this JBS issue.
25-01-2019
Well, unlike ProgressBar, the determinate and indeterminate views are very different, so I think it's fine that they have different sizes.
23-01-2019
Hmmm... It's tempting to make them consistent, but if they are of the default sizes, let's leave them untouched. I thought about introducing setHeight()/setWidth() in that example, but that does not go well with documentation. On other hand, if we stretch the image, that will also look untidy as font and circle will be stretched.
23-01-2019
About 6, these are the default sizes. I attached an image showing them. Do you want me to make them artificially the same size?
22-01-2019
Thanks for the all the hard yards. It is looking much better now. I did notice some inconsistencies though - here are they : 1) ChoiceBox: A single space on second line in ChoiceBox Example removed. This might be alignment issue. ChoiceBox cb = new ChoiceBox(); cb.getItems().addAll("item1", "item2", "item3"); 2) Dialog : Image needs small correction. Title of dialog has a misspelt word ���Dialoog��� 3) ListView: The sentence after added image should start on new line. Currently, it is adjacent to image. 4) Pagination: Text above example says ���A simple example of how to create a pagination control with ten pages and each page containing ten hyperlinks.��� Please remove text ���and each page containing ten hyperlinks��� as it has become irrelevant after the changes in example code. 5) ProgressBar : a : It is preferred if you can make width & height of both images same for consistent look. b : The text after new second image should start on new line 6) ProgressIndicator: a : It is preferred if you can make width & height of both images same for consistent look. b : The text after new second image should start on new line
22-01-2019
Kevin, Ajit, New Webrev: http://cr.openjdk.java.net/~nlisker/8210361/webrev.01/ Corresponding diff patch is also under: http://cr.openjdk.java.net/~nlisker/8210361/ Changes: * `alt` string added. * Copyright year updated. * Added examples (and images) for missing classes such as: TextField, PasswordField, TextArea and Spinner. * Added images for missing classes such as the various menu-related classes mentioned by Ajit. * Added indeterminate progress images for ProgressBar and ProgressIndicator. * Rephrased/extended examples that were lacking, incorrect, or had JavaDoc render issues such as: TableView, TreeTableView, Dialog and various menu-related classes. Ignore the misplaced "Implementation of <ControlName> According to JavaFX UI Control API Specification" sentences, they are targeted in JDK-8211014. I note that there is still inconsistency in the indentation of the code snippets. Sometimes there is a single space, sometimes none. I don't think it matters much because anyone who copy-pastes into an IDE will have it re-indent the code automatically. Personally, I would prefer some (1-4 spaces) indentation for readability, but I do not consider this to be a stopping issue. I'll also add that since the examples are meant to give a quick start and demonstrate simplicity, it would be useful in the future to link from each class to its corresponding tutorial page (under https://docs.oracle.com/javase/8/javafx/user-interface-tutorial/ui_controls.htm#JFXUI336) since these show complementary fancy and elaborate techniques, and they do so very well. Swing does this, e.g., in https://docs.oracle.com/en/java/javase/11/docs/api/java.desktop/javax/swing/JButton.html. I'm hesitant to do this currently because the tutorials are still targeted to JavaFX 8 and I'm not sure about their future hosting address. We can create a new issue for this.
20-01-2019
Ajit, 1. Yes, also for TreeTableView. I wanted to see if what I did was fine before doing all of them. Will do them in the upcoming patch. 2. I'll add a title and a label as content. 3. OK, I can do the same for progress bar too. 4. OK, I'll try to streamline the menu items. 5. Yeah, it's escaping the @ I think, though if it's inside {@literal ...} it shouldn't need to be escaped. 6. I'll use the following spacing, which is minimal, in all examples: * <p> * Example: * <pre><code> TitledPane t1 = new TitledPane("T1", new Button("B1")); * TitledPane t2 = new TitledPane("T2", new Button("B2")); * TitledPane t3 = new TitledPane("T3", new Button("B3")); * Accordion accordion = new Accordion(); * accordion.getPanes().addAll(t1, t2, t3);</code></pre> * * <img src="doc-files/Accordion.png" alt=""> See spacing image for the result. Are the code examples supposed to be indented horizontally by some amount or aligned with the rest of the text?
18-01-2019
Questions to Kevin : 1) Do we need images with specific DPI for javadoc? 2) Does javadoc for javafx support translation? If yes, do the example code strings get translated?
17-01-2019
1) I do not see images for exiting examples of these controls- Menu MenuBar MenuButton MenuItem SpiltMenuButton Can you please check and add them? 2) Image for showing Dialog does not look good. It is an empty dialog with no title and just a login button. We may need to change the example a bit to add at least dialog title. 3) ProgressIndicator - has an image that shows 25% complete. I think, it should also have an image to illustrate indeterminate indicator example which is above it. 4) RadioMenuItem Shows a menu named ���Selection��� - but the example code does not have it. It is better to add it in example code. 5) SpiltMenuButton documentation has ���&#064���. It can be fixed under other bug - I am listing here as I observed it. 6) This may not pertain to the scope of this bug, but relevant to the visual look of the documentation. I see inconsistency in spacing at few places - refer to vertical spacing after string ���Example��� in two attached images - Review_TitledPane.png and Review_HyperLink.png
17-01-2019
Thanks for the git-diff patch, that applies fine and will help in the review. To answer your question, if you look in the rt.patch in the webrev itself, it just lists a number of lines of the form: "Binary files /dev/null and new/modules/javafx.controls/src/main/docs/.../XXX.png differ", one line per file. Yes, the individual files are pointed to by the webrev (you can click on the "raw" link and see them), but it is time-consuming and error prone to download them individually and copy them to the right place.
16-01-2019
diff patch is available at http://cr.openjdk.java.net/~nlisker/8210361/. By the way, the webrev seems to contains the image files as well. Why can they not be applied? Will fix 2, 3 and the Pagination example. I'll remove the lines "Implementation of <ControlName> According to JavaFX UI Control API Specification" as part of JDK-8211014 since it's not related to the code examples.
16-01-2019
Most of the changes and images look fine at a quick glance, but will need a more careful review. Here are some general comments: 1. Please provide a git-diff patch (one generated with "hg diff --git") so that it contains the binary files. Otherwise I can't apply the patch and test it to see what the images look like 2. For accessibility, the `alt` string should have some text like: alt="An image showing the XXXX control" 3. Can you changes the copyright year to 2019? One other point: * The changes to the example in Pagination.java are such that it no longer makes sense to have a loop, since you pass in a constant string (which also shows up in the example image). I realize that this is an odd example to begin with. As for the questions raised by the notes, I think your approach is fine. I have no idea why some classes have the line "Implementation of <ControlName> According to JavaFX UI Control API Specification" (or why we didn't spot it before), but it seems out of place and redundant. It recommend removing it.
15-01-2019
Webrev: http://cr.openjdk.java.net/~nlisker/8210361/webrev.00/ Not all controls are included yet, but it's better to have a look at what there is right now and then continue with the rest. Some notes: * Not all controls that need an example have one (PasswordField, ChoiceDialog...). I try to add one myself. * Some code examples have mistakes in them. I opted to correct them here since they are tied to the images directly. * I removed import statements, in the few cases where they appear, from code examples as they clutter the demonstration code. * Not all code examples are near the bottom. I added the images after the code. * Some classes have the line "Implementation of <ControlName> According to JavaFX UI Control API Specification" (e.g., ProgressBar). What is it for?
14-01-2019
They look fine. I think placing them next to the code sample, near the bottom, seems best.
12-09-2018
Attached samples of the images. They were created by using the code example in the class doc. If these are fine I'll do the rest. Placement: should they be placed near the top for visibility or next to the code example, which is on the bottom?
12-09-2018