Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-6580853

AWT JavaDoc should use the "is visible on the screen" instead of the awkward "is showing" concept



    • Subcomponent:
    • CPU:
    • OS:


      There's an "is showing" concept in the AWT JavaDoc spec. This concept corresponds to the awkwardly named java.awt.Component.isShowing() method. According to the English grammar and the meaning of the state when the component "isShowing", this wording seems to be incorrect.

      It is proposed to change all the occurrences of "is showing" and "is not showing" ("on the screen") to "is visible on the screen" and "is not visible on the screen". The addition of the "on the screen" words will differentiate this wording from the simple "is visible", as the latter one corresponds to the isVisible() method, rather than to the isShowing() method. These methods have slightly different meanings:

      * isVisible() tells whether the component is marked to be able to be visible on the screen. It's not guaranteed that this component is indeed visible now, as the parent of the component (say, the Frame the component is added to) can still be hidden.
      * isShowing() tells whether the component is really visible on the screen right now, i.e. the user is able to observe the component on the screen with his eyes. (The component can actually be still hidden if, for instance, the frame is obscured by other application frames, but anyway the component is physically and natively made visible.)

      If such a difference is not enough to properly separate the meanings, we could use the passive voice wording "is shown" instead of the initially proposed "is visible on the screen". The better choice is left to the engineer.
      It looks like even the "is visible on the screen" or "is shown" phrases are not perfect for the description of the mentioned state. Perhaps we need to think a bit of a better wording ("recursively visible"?.. it's too long and might be inaccurate as well). If such a phrase was born, we could also deprecate the existing isShowing() method and introduce something like is*Shown*() method to perform the same action. This would enable the API be consistent to the JavaDoc.




            serb Sergey Bylokhov
            anthony Anthony Petrov (Inactive)
            0 Vote for this issue
            2 Start watching this issue