1 /* License, v. 2.0. If a copy of the MPL was not distributed with this 2 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 3 4 package org.mozilla.geckoview; 5 6 import androidx.annotation.AnyThread; 7 import androidx.annotation.IntDef; 8 import androidx.annotation.NonNull; 9 import java.lang.annotation.Retention; 10 import java.lang.annotation.RetentionPolicy; 11 12 /** 13 * ScreenLength is a class that represents a length on the screen using different units. The default 14 * unit is a pixel. However lengths may be also represented by a dimension of the visual viewport or 15 * of the full scroll size of the root document. 16 */ 17 public class ScreenLength { 18 @Retention(RetentionPolicy.SOURCE) 19 @IntDef({PIXEL, VISUAL_VIEWPORT_WIDTH, VISUAL_VIEWPORT_HEIGHT, DOCUMENT_WIDTH, DOCUMENT_HEIGHT}) 20 public @interface ScreenLengthType {} 21 22 /** Pixel units. */ 23 public static final int PIXEL = 0; 24 /** 25 * Units are in visual viewport width. If the visual viewport is 100 pixels wide, then a value of 26 * 2.0 would represent a length of 200 pixels. 27 * 28 * @see <a href="https://developer.mozilla.org/en-US/docs/Glossary/Visual_Viewport">MDN Visual 29 * Viewport</a> 30 */ 31 public static final int VISUAL_VIEWPORT_WIDTH = 1; 32 /** 33 * Units are in visual viewport height. If the visual viewport is 100 pixels high, then a value of 34 * 2.0 would represent a length of 200 pixels. 35 * 36 * @see <a href="https://developer.mozilla.org/en-US/docs/Glossary/Visual_Viewport">MDN Visual 37 * Viewport</a> 38 */ 39 public static final int VISUAL_VIEWPORT_HEIGHT = 2; 40 /** 41 * Units represent the entire scrollable documents width. If the document is 1000 pixels wide then 42 * a value of 1.0 would represent 1000 pixels. 43 */ 44 public static final int DOCUMENT_WIDTH = 3; 45 /** 46 * Units represent the entire scrollable documents height. If the document is 1000 pixels tall 47 * then a value of 1.0 would represent 1000 pixels. 48 */ 49 public static final int DOCUMENT_HEIGHT = 4; 50 51 /** 52 * Create a ScreenLength of zero pixels length. Type is {@link #PIXEL}. 53 * 54 * @return ScreenLength of zero length. 55 */ 56 @NonNull 57 @AnyThread zero()58 public static ScreenLength zero() { 59 return new ScreenLength(0.0, PIXEL); 60 } 61 62 /** 63 * Create a ScreenLength of zero pixels length. Type is {@link #PIXEL}. Can be used to scroll to 64 * the top of a page when used with PanZoomController.scrollTo() 65 * 66 * @return ScreenLength of zero length. 67 */ 68 @NonNull 69 @AnyThread top()70 public static ScreenLength top() { 71 return zero(); 72 } 73 74 /** 75 * Create a ScreenLength of the documents height. Type is {@link #DOCUMENT_HEIGHT}. Can be used to 76 * scroll to the bottom of a page when used with {@link PanZoomController#scrollTo(ScreenLength, 77 * ScreenLength)} 78 * 79 * @return ScreenLength of document height. 80 */ 81 @NonNull 82 @AnyThread bottom()83 public static ScreenLength bottom() { 84 return new ScreenLength(1.0, DOCUMENT_HEIGHT); 85 } 86 87 /** 88 * Create a ScreenLength of a specific length. Type is {@link #PIXEL}. 89 * 90 * @param value Pixel length. 91 * @return ScreenLength of document height. 92 */ 93 @NonNull 94 @AnyThread fromPixels(final double value)95 public static ScreenLength fromPixels(final double value) { 96 return new ScreenLength(value, PIXEL); 97 } 98 99 /** 100 * Create a ScreenLength that uses the visual viewport width as units. Type is {@link 101 * #VISUAL_VIEWPORT_WIDTH}. Can be used with {@link PanZoomController#scrollBy(ScreenLength, 102 * ScreenLength)} to scroll a value of the width of visual viewport content. 103 * 104 * @param value Factor used to calculate length. A value of 2.0 would indicate a length twice as 105 * long as the length of the visual viewports width. 106 * @return ScreenLength of specifying a length of value * visual viewport width. 107 */ 108 @NonNull 109 @AnyThread fromVisualViewportWidth(final double value)110 public static ScreenLength fromVisualViewportWidth(final double value) { 111 return new ScreenLength(value, VISUAL_VIEWPORT_WIDTH); 112 } 113 114 /** 115 * Create a ScreenLength that uses the visual viewport width as units. Type is {@link 116 * #VISUAL_VIEWPORT_HEIGHT}. Can be used with {@link PanZoomController#scrollBy(ScreenLength, 117 * ScreenLength)} to scroll a value of the height of visual viewport content. 118 * 119 * @param value Factor used to calculate length. A value of 2.0 would indicate a length twice as 120 * long as the length of the visual viewports height. 121 * @return ScreenLength of specifying a length of value * visual viewport width. 122 */ 123 @NonNull 124 @AnyThread fromVisualViewportHeight(final double value)125 public static ScreenLength fromVisualViewportHeight(final double value) { 126 return new ScreenLength(value, VISUAL_VIEWPORT_HEIGHT); 127 } 128 129 private final double mValue; 130 @ScreenLengthType private final int mType; 131 ScreenLength(final double value, @ScreenLengthType final int type)132 /* package */ ScreenLength(final double value, @ScreenLengthType final int type) { 133 mValue = value; 134 mType = type; 135 } 136 137 /** 138 * Returns the scalar value used to calculate length. The units of the returned valued are defined 139 * by what is returned by {@link #getType()} 140 * 141 * @return Scalar value of the length. 142 */ 143 @AnyThread getValue()144 public double getValue() { 145 return mValue; 146 } 147 148 /** 149 * Returns the unit type of the length The length can be one of the following: {@link #PIXEL}, 150 * {@link #VISUAL_VIEWPORT_WIDTH}, {@link #VISUAL_VIEWPORT_HEIGHT}, {@link #DOCUMENT_WIDTH}, 151 * {@link #DOCUMENT_HEIGHT} 152 * 153 * @return Unit type of the length. 154 */ 155 @AnyThread 156 @ScreenLengthType getType()157 public int getType() { 158 return mType; 159 } 160 } 161