< prev index next >
src/java.desktop/share/classes/java/awt/Toolkit.java
Print this page
*** 32,41 ****
--- 32,42 ----
import java.awt.event.*;
import java.awt.im.InputMethodHighlight;
import java.awt.image.ColorModel;
import java.awt.image.ImageObserver;
import java.awt.image.ImageProducer;
+ import java.awt.image.MultiResolutionImage;
import java.beans.PropertyChangeEvent;
import java.beans.PropertyChangeListener;
import java.beans.PropertyChangeSupport;
import java.io.File;
import java.io.FileInputStream;
*** 45,55 ****
import java.util.HashMap;
import java.util.Map;
import java.util.MissingResourceException;
import java.util.Properties;
import java.util.ResourceBundle;
- import java.util.StringTokenizer;
import java.util.WeakHashMap;
import sun.awt.AWTAccessor;
import sun.awt.AWTPermissions;
import sun.awt.AppContext;
--- 46,55 ----
*** 625,645 ****
--- 625,796 ----
* <p>
* This method first checks if there is a security manager installed.
* If so, the method calls the security manager's
* {@code checkRead} method with the file specified to ensure
* that the access to the image is allowed.
+ * <p>
+ * Note: some {@code Toolkit}s may load image with provided resolution variants
+ * using media resolution naming scheme(see {@link #getImageUsingNamingSchemes}).
+ * All built-in {@code Tookit}s use the following media resolution naming scheme:
+ * <ul>
+ * <li>{@code @125pct} - scale 1.25</li>
+ * <li>{@code @150pct} - scale 1.5</li>
+ * <li>{@code @2x} synonym for {@code @200pct} - scale 2</li>
+ * <li>{@code @250pct} - scale 2.5</li>
+ * <li>{@code @3x} synonym for {@code @300pct} - scale 3</li>
+ * </ul>
+ *
* @param filename the name of a file containing pixel data
* in a recognized file format.
* @return an image which gets its pixel data from
* the specified file.
* @throws SecurityException if a security manager exists and its
* checkRead method doesn't allow the operation.
* @see #createImage(java.lang.String)
+ * @see #getImageUsingNamingSchemes
+ * @see MultiResolutionImage
*/
public abstract Image getImage(String filename);
/**
+ * The MediaResolutionNamingScheme class stores the resolution variant
+ * qualifier as well as scaled factors associated with it.
+ *
+ * @see #getImageUsingNamingSchemes
+ * @see MultiResolutionImage
+ *
+ * @since 9
+ */
+ public static class MediaResolutionNamingScheme {
+
+ private final String qualifier;
+ private final float scale;
+
+ /**
+ * Creates a new instance of MediaResolutionNamingScheme.
+ *
+ * @param qualifier the resolution-variant qualifier
+ * @param scale the scale associated with the resolution variant qualifier
+ *
+ * @since 9
+ */
+ public MediaResolutionNamingScheme(String qualifier, float scale) {
+ this.qualifier = qualifier;
+ this.scale = scale;
+ }
+
+ /**
+ * @return the resolution-variant qualifier
+ *
+ * @since 9
+ */
+
+ public String getQualifier() {
+ return qualifier;
+ }
+
+ /**
+ * @return scale factor
+ *
+ * @since 9
+ */
+ public float getScale() {
+ return scale;
+ }
+ }
+
+ /**
+ * Returns an image with resolution variants based on the provided media
+ * resolution naming scheme. This method is useful when it is necessary to
+ * provide an image with resolution variants for HiDPI displays.
+ * <p>
+ * For example, if HiDPI display supports scales 1.5 and 2 the following steps
+ * can be used to provide an image together with its high resolution variants.
+ * Put scaled versions of the original image in the same directory using
+ * naming convention {@literal @150pct} for scale 1.5 and {@literal @2x}
+ * for scale 2 The qualifier need to be placed between the image
+ * name and extension:
+ * <ul>
+ * <li>{@literal image_name.ext} - original image</li>
+ * <li>{@literal image_name@150pct.ext} - resolution variant for scale 1.5
+ * and qualifier {@literal @150pct}</li>
+ * <li>{@literal image_name@2x.ext} - resolution variant for scale 2 and
+ * qualifier {@literal @2x}</li>
+ * </ul>
+ * Call {@code getImageUsingNamingSchemes(...)} method providing only path to the
+ * original image and naming schemes which include defined qualifiers and scales.
+ * <pre> {@code
+ * Image image = toolkit.getImageUsingNamingSchemes(fileName,
+ * new Toolkit.MediaResolutionNamingScheme("@150pct", 1.5f),
+ * new Toolkit.MediaResolutionNamingScheme("@2x", 2f)
+ * );
+ * } </pre>
+ * <p>
+ * The resolution variant is not added if an image for the given naming scheme
+ * is missed. If all resolution variants are missed the returned result
+ * will be the same as call to the {@code getImage(fileName)} method.
+ *
+ * @param fileName file path to the original image
+ * @param namingSchemes array of naming scheme that contains resolution
+ * variant qualifier and associated with it scale factor
+ * @return an image with with resolution variants
+ *
+ * @see #getImage
+ * @see MediaResolutionNamingScheme
+ * @see MultiResolutionImage
+ */
+ public Image getImageUsingNamingSchemes(String fileName,
+ MediaResolutionNamingScheme... namingSchemes) {
+ return SunToolkit.getImageUsingNamingSchemes(this, fileName, namingSchemes);
+ }
+
+ /**
+ * Returns an image with resolution variants based on the provided media
+ * resolution naming scheme. This method is useful when it is necessary to
+ * provide an image with resolution variants for HiDPI displays.
+ * <p>
+ * For example, if HiDPI display supports scales 1.5 and 2 the following steps
+ * can be used to provide an image together with its high resolution variants.
+ * Put scaled versions of the original image in the same jar file using
+ * naming convention {@literal @150pct} for scale 1.5 and {@literal @2x}
+ * for scale 2 The qualifier need to be placed between the image
+ * name and extension:
+ * <ul>
+ * <li>{@literal image_name.ext} - original image</li>
+ * <li>{@literal image_name@150pct.ext} - resolution variant for scale 1.5
+ * and qualifier {@literal @150pct}</li>
+ * <li>{@literal image_name@2x.ext} - resolution variant for scale 2 and
+ * qualifier {@literal @2x}</li>
+ * </ul>
+ * Call {@code getImageUsingNamingSchemes(...)} method providing only url to the
+ * original image and naming schemes which include defined qualifiers and scales.
+ * <pre> {@code
+ * Image image = toolkit.getImageUsingNamingSchemes(url,
+ * new Toolkit.MediaResolutionNamingScheme("@150pct", 1.5f),
+ * new Toolkit.MediaResolutionNamingScheme("@2x", 2f)
+ * );
+ * } </pre>
+ * <p>
+ * The resolution variant is not added if an image for the given naming scheme
+ * is missed. If all resolution variants are missed the returned result
+ * will be the same as call to the {@code getImage(fileName)} method.
+ *
+ * @param url file path to the original image
+ * @param namingSchemes array of naming scheme that contains resolution
+ * variant qualifier and associated with it scale factor
+ * @return an image with with resolution variants
+ *
+ * @see #getImage
+ * @see MediaResolutionNamingScheme
+ * @see MultiResolutionImage
+ */
+ public Image getImageUsingNamingSchemes(URL url,
+ MediaResolutionNamingScheme... namingSchemes) {
+ return SunToolkit.getImageUsingNamingSchemes(this, url, namingSchemes);
+ }
+
+ /**
* Returns an image which gets pixel data from the specified URL.
* The pixel data referenced by the specified URL must be in one
* of the following formats: GIF, JPEG or PNG.
* The underlying toolkit attempts to resolve multiple requests
* with the same URL to the same returned Image.
*** 666,682 ****
--- 817,847 ----
* with pre-1.2 security managers, if the access is denied with
* {@code FilePermission} or {@code SocketPermission},
* the method throws the {@code SecurityException}
* if the corresponding 1.1-style SecurityManager.checkXXX method
* also denies permission.
+ * <p>
+ * Note: some {@code Toolkit}s may load image with provided resolution variants
+ * using media resolution naming scheme(see {@link #getImageUsingNamingSchemes}).
+ * All built-in {@code Tookit}s use the following media resolution naming scheme:
+ * <ul>
+ * <li>{@code @125pct} - scale 1.25</li>
+ * <li>{@code @150pct} - scale 1.5</li>
+ * <li>{@code @2x} synonym for {@code @200pct} - scale 2</li>
+ * <li>{@code @250pct} - scale 2.5</li>
+ * <li>{@code @3x} synonym for {@code @300pct} - scale 3</li>
+ * </ul>
+ *
* @param url the URL to use in fetching the pixel data.
* @return an image which gets its pixel data from
* the specified URL.
* @throws SecurityException if a security manager exists and its
* checkPermission method doesn't allow
* the operation.
* @see #createImage(java.net.URL)
+ * @see #getImageUsingNamingSchemes
+ * @see MultiResolutionImage
*/
public abstract Image getImage(URL url);
/**
* Returns an image which gets pixel data from the specified file.
< prev index next >