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

BasicStroke API documentation has understandibility flaws

XMLWordPrintable

    • Icon: Bug Bug
    • Resolution: Fixed
    • Icon: P3 P3
    • 1.3.1
    • 1.4.0
    • docs
    • None
    • beta
    • sparc
    • solaris_7
    • Verified

        The "width" parameter to a BasicStroke is used in multiple constructors, and
        is a property that can be get/set. It's data type is "float", and it is
        described to be the "pen width".

        This much makes sense and is fairly straightforward. HOWEVER, when it comes
        down to the brass tacks of actually using this, it is incredibly confusing
        what it specifically means.

        For example, the questions in my mind that there are no answers for include:

        - What is the valid range for this parameter? [0..1) ?? [1..inf) ??
           Can it have a negative value?

        - What is the effect of a '0' value? (I notice one bug complaining that
           a width=0 doesn't draw a 1 pixel wide line)

        - Why is it's type "float". I expect that the width parameter refers to
          the number of pixels wide the pen is. But pixels cannot have fractional
          size (that is, it doesn't make sense for a pen to be 1.5 pixels wide since
          pixels cannot be split in half). Under this expectation I'd also expect
          the width parameter to have type "int" instead of "float".

        - The description in the getLineWidth method ("Line width is represented
           in user space.") doesn't make much sense.

        Of these the notes about "width" parameter is the most important to resolve.
        I understand that "user space" is a commonly used term in graphics rendering,
        but the phrase doesn't make enough sense in context to me to understand
        what it means.



              jballsunw Jennifer Ball (Inactive)
              dherronsunw David Herron (Inactive)
              Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

                Created:
                Updated:
                Resolved:
                Imported:
                Indexed: