Package com.oorian.html.elements

Class Picture<T extends Picture<T>>

java.lang.Object
com.oorian.html.Element<T>
com.oorian.html.VisualElement<T>
com.oorian.html.StyledElement<T>
com.oorian.html.elements.Picture<T>
public class Picture<T extends Picture<T>> extends StyledElement<T>
Represents an HTML <picture> element for responsive images.

The <picture> element is a container for multiple <source> elements and one <img> element, allowing browsers to choose the most appropriate image based on the current viewport, device pixel ratio, or supported image formats. This enables art direction, format fallbacks, and resolution switching for responsive design.

Features:

  • Provides multiple image sources for different scenarios
  • Supports art direction with different images for different viewport sizes
  • Enables modern format support (WebP, AVIF) with fallbacks
  • Allows resolution switching for high-DPI displays
  • Requires an <img> fallback element for browser compatibility

Usage:


 // Responsive image with convenience methods
 Picture picture = new Picture();
 picture.addSource("/images/photo-small.jpg", "(max-width: 600px)");
 picture.addSource("/images/photo-medium.jpg", "(max-width: 1200px)");
 picture.setFallbackImage("/images/photo-large.jpg", "A beautiful photo");

 // Format-based fallback (WebP with JPEG fallback)
 Picture modernImage = new Picture();
 modernImage.addSource("/images/photo.webp", null, "image/webp");
 modernImage.addSource("/images/photo.avif", null, "image/avif");
 modernImage.setFallbackImage("/images/photo.jpg", "Photo description");
Since:
2025
Version:
1.0
Author:
Marvin P. Warble Jr.
See Also:

  • Constructor Details

    • Picture

      public Picture()
      Constructs a new Picture element.

      Creates an empty HTML <picture> element. Source elements should be added using addSource(String, String, String), and a fallback <img> element should be added using setFallbackImage(String, String).

    • Picture

      public Picture(String fallbackSrc, String altText)
      Constructs a Picture element with a fallback image.

      Creates a <picture> element with the specified fallback image. Additional <source> elements should be added to provide responsive image options.

      Parameters:
      fallbackSrc - the URL of the fallback image
      altText - alternative text for the fallback image

  • Method Details

    • addSource

      public final void addSource(String srcset, String media, String type)
      Adds a source element with the specified attributes.

      Convenience method to add a <source> element with srcset, media query, and type attributes. Any parameter can be null if not needed.

      Parameters:
      srcset - the srcset attribute value (image URL or comma-separated list)
      media - the media query for conditional loading (e.g., "(max-width: 768px)"), or null
      type - the MIME type of the image (e.g., "image/webp"), or null

    • addSource

      public final void addSource(String srcset, String media)
      Adds a source element with srcset and media query.

      Convenience method to add a <source> element for responsive image sizing based on viewport.

      Parameters:
      srcset - the srcset attribute value (image URL or comma-separated list)
      media - the media query for conditional loading (e.g., "(max-width: 768px)")

    • setFallbackImage

      public final void setFallbackImage(String src, String altText)
      Sets the fallback image for the picture element.

      The fallback <img> element is required and will be displayed by browsers that don't support the <picture> element or when no <source> element matches. This should be called after adding all source elements.

      Parameters:
      src - the URL of the fallback image
      altText - alternative text describing the image for accessibility

    • setFallbackImage

      public final void setFallbackImage(String src, String altText, int width)
      Sets the fallback image with additional width specification.

      Creates a fallback <img> element with a specified width.

      Parameters:
      src - the URL of the fallback image
      altText - alternative text describing the image for accessibility
      width - the width of the image in pixels

    • setFallbackImage

      public final void setFallbackImage(String src, String altText, String width)
      Sets the fallback image with CSS width specification.

      Creates a fallback <img> element with a CSS width value.

      Parameters:
      src - the URL of the fallback image
      altText - alternative text describing the image for accessibility
      width - the width as a CSS value (e.g., "100%", "50vw", "300px")

    • removeAllElements

      public void removeAllElements()
      Removes all source and fallback elements from this picture.
      Overrides:
      removeAllElements in class Element<T extends Picture<T>>