android_manifest/compatible_screens.rs
1use serde::{Deserialize, Serialize};
2
3/// Specifies each screen configuration with which the application is
4/// compatible.
5///
6/// Only one instance of the `<compatible-screens>` element is
7/// allowed in the manifest, but it can contain multiple `<screen>` elements.
8/// Each <screen> element specifies a specific screen size-density combination
9/// with which the application is compatible.
10///
11/// The Android system does not read the `<compatible-screens>` manifest element (neither
12/// at install-time nor at runtime). This element is informational only and may be used by
13/// external services (such as Google Play) to better understand the application's
14/// compatibility with specific screen configurations and enable filtering for
15/// users. Any screen configuration that is not declared in this element is a
16/// screen with which the application is not compatible. Thus, external services (such as
17/// Google Play) should not provide the application to devices with such screens.
18///
19/// ## Caution
20/// Normally, you should not use this manifest element. Using this
21/// element can dramatically reduce the potential user base for your
22/// application, by not allowing users to install your application if they have
23/// a device with a screen configuration that you have not listed. You should
24/// use it only as a last resort, when the application absolutely does not work
25/// with specific screen configurations. Instead of using this element, you
26/// should follow the guide to [`Supporting Multiple Screens`] to provide scalable
27/// support for multiple screens using alternative layouts and bitmaps for
28/// different screen sizes and densities.
29///
30/// If you want to set only a minimum screen size for your your application,
31/// then you should use the [`<supports-screens>`] element. For example, if you
32/// want your application to be available only for large and xlarge screen
33/// devices, the [`<supports-screens>`] element allows you to declare that your
34/// application does not support small and normal screen sizes. External
35/// services (such as Google Play) will filter your application accordingly. You
36/// can also use the [`<supports-screens>`] element to declare whether the system
37/// should resize your application for different screen sizes.
38///
39/// Also see the [`Filters on Google Play`] document for more information about how Google
40/// Play filters applications using this and other manifest elements.
41///
42/// ## XML Syntax
43/// ```xml
44/// <compatible-screens>
45/// <screen android:screenSize=["small" | "normal" | "large" | "xlarge"]
46/// android:screenDensity=["ldpi" | "mdpi" | "hdpi" | "xhdpi"
47/// | "280" | "360" | "420" | "480" | "560" ] />
48/// ...
49/// </compatible-screens>
50/// ```
51///
52/// ## Contained in
53/// * [`<manifest>`]
54///
55/// ## Introduced in
56/// API Level 9
57///
58/// [`Supporting Multiple Screens`]: https://developer.android.com/guide/practices/screens_support
59/// [`<supports-screens>`]: crate::SupportsScreens
60/// [`Filters on Google Play`]: https://developer.android.com/google/play/filters
61/// [`<manifest>`]: crate::AndroidManifest
62#[derive(Debug, Deserialize, Serialize, YaSerialize, YaDeserialize, PartialEq, Eq, Clone)]
63pub struct CompatibleScreens {
64 pub screen: Vec<Screen>,
65}
66
67/// Specifies a single screen configuration with which the application is
68/// compatible.
69///
70/// At least one instance of this element must be placed inside the
71/// `<compatible-screens>` element. This element must include both the
72/// `android:screenSize` and `android:screenDensity` attributes (if you do not
73/// declare both attributes, then the element is ignored).
74///
75/// ## XML Example
76/// If your application is compatible with only small and normal screens, regardless of
77/// screen density, then you must specify twelve different <screen> elements, because each
78/// screen size has six different density configurations. You must declare each one of
79/// these; any combination of size and density that you do not specify is considered a
80/// screen configuration with which your application is not compatible. Here's what the
81/// manifest entry looks like if your application is compatible with only small and normal
82/// screens:
83/// ```xml
84/// <manifest ... >
85/// ...
86/// <compatible-screens>
87/// <!-- all small size screens -->
88/// <screen android:screenSize="small" android:screenDensity="ldpi" />
89/// <screen android:screenSize="small" android:screenDensity="mdpi" />
90/// <screen android:screenSize="small" android:screenDensity="hdpi" />
91/// <screen android:screenSize="small" android:screenDensity="xhdpi" />
92/// <screen android:screenSize="small" android:screenDensity="xxhdpi" />
93/// <screen android:screenSize="small" android:screenDensity="xxxhdpi" />
94/// <!-- all normal size screens -->
95/// <screen android:screenSize="normal" android:screenDensity="ldpi" />
96/// <screen android:screenSize="normal" android:screenDensity="mdpi" />
97/// <screen android:screenSize="normal" android:screenDensity="hdpi" />
98/// <screen android:screenSize="normal" android:screenDensity="xhdpi" />
99/// <screen android:screenSize="normal" android:screenDensity="xxhdpi" />
100/// <screen android:screenSize="normal" android:screenDensity="xxxhdpi" />
101/// </compatible-screens>
102/// <application ... >
103/// ...
104/// <application>
105/// </manifest>
106/// ```
107///
108/// Contained in:
109/// [`<compatible-screens>`]
110///
111/// [`<compatible-screens>`]: crate::CompatibleScreens
112#[derive(Debug, Deserialize, Serialize, YaSerialize, YaDeserialize, PartialEq, Eq, Clone)]
113pub struct Screen {
114 /// `Required`. Specifies the screen size for this screen configuration.
115 ///
116 /// For information about the different screen sizes, see [`Supporting Multiple
117 /// Screens`].
118 ///
119 /// [`Supporting Multiple Screens`]: https://developer.android.com/guide/practices/screens_support#range
120 #[yaserde(attribute, prefix = "android", rename = "screenSize")]
121 pub screen_size: ScreenSize,
122 /// `Required.` Specifies the screen density for this screen configuration.
123 ///
124 /// For information about the different screen densities, see [`Supporting Multiple
125 /// Screens`].
126 ///
127 /// Accepted values:
128 /// * "ldpi" (approximately 120 dpi)
129 /// * "mdpi" (approximately 160 dpi)
130 /// * "hdpi" (approximately 240 dpi)
131 /// * "xhdpi" (approximately 320 dpi)
132 /// * "280"
133 /// * "360"
134 /// * "420"
135 /// * "480"
136 /// * "560"
137 ///
138 /// [`Supporting Multiple Screens`]: https://developer.android.com/guide/practices/screens_support#range
139 #[yaserde(attribute, prefix = "android", rename = "screenDensity")]
140 pub screen_density: String,
141}
142
143/// Android runs on a variety of devices that have different screen sizes and pixel
144/// densities. The system performs basic scaling and resizing to adapt your user interface
145/// to different screens.
146#[derive(Debug, Deserialize, Serialize, YaSerialize, YaDeserialize, PartialEq, Eq, Clone)]
147#[serde(rename_all = "camelCase")]
148#[derive(Default)]
149pub enum ScreenSize {
150 /// Screens that are of similar size to a low-density QVGA screen. The minimum layout
151 /// size for a small screen is approximately 320x426 dp units. Examples are QVGA
152 /// low-density and VGA high density.
153 #[yaserde(rename = "small")]
154 Small,
155 /// Screens that are of similar size to a medium-density HVGA screen. The minimum
156 /// layout size for a normal screen is approximately 320x470 dp units. Examples of
157 /// such screens a WQVGA low-density, HVGA medium-density, WVGA high-density.
158 #[yaserde(rename = "normal")]
159 #[default]
160 Normal,
161 /// Screens that are of similar size to a medium-density VGA screen. The minimum
162 /// layout size for a large screen is approximately 480x640 dp units. Examples are VGA
163 /// and WVGA medium-density screens.
164 #[yaserde(rename = "large")]
165 Large,
166 /// Screens that are considerably larger than the traditional medium-density HVGA
167 /// screen. The minimum layout size for an xlarge screen is approximately 720x960 dp
168 /// units. In most cases, devices with extra-large screens would be too large to carry
169 /// in a pocket and would most likely be tablet-style devices. Added in API level 9.
170 #[yaserde(rename = "xlarge")]
171 Xlarge,
172}