This BlackBerry 10 WebWorks extension provides additional APIs supplying information about the device screen display.
The API returns the information about the screen directly from the device. The returned values are the physical metrics of the screen without the browser applying any scaling etc.
The single most valuable figure returned from this API is ppi. The ppi value allows you to make the text and images in your app look the same size on any device by adjusting the font-size and image widths / heights based on the ppi.
A simple example is that you design for a 36px font on a device with 356 ppi (a Z10). If you get a 600 ppi device all you have to do is alter the font-sizes using newFontSize = Math.round((device.ppi / 356) * 36) giving a 61px font size on a 600 ppi device. The same holds true for lower ppi devices - a Q10 would end up with a 34px font.
** Tested On **
BlackBerry Z10 10.0.9.2372 BlackBerry Z10 10.0.10.82 (Same device - downgrade DA-B for tests)
BlackBerry 10 Dev Alpha B 10.0.9.2372
BlackBerry 10 Dev Alpha C 10.1.0.1483
** Author **
Building and Testing the Sample
- Deploy the extension into your BB10 WebWorks SDK by copying the community.screendisplay folder from the ext folder to the Framework/ext folder in your WebWorks SDK, or run the Ant build script in the /ext folder to do so.
- Package the sample in the sdtest folder. Use the Ant Build Script, or you can do this with the WebWorks packager command: bbwp sdtest -g signingpassword
- Load it on your phone using the Ant Build Script, or with the blackberry-deploy command found in the dependencies/tools folder of your WebWorks SDK.
- When the application runs, an informational page will be displayed as in the screenshots below.
Including the feature in your application
Whenever you use the below feature id in any of your WebWorks applications this extension will be loaded for use.
<feature id="community.screendisplay" required="true" version="22.214.171.124" />
The Extension API
The Screen Display Extension provides the following API:
The first four numbers are returned from the device. The other numbers are calculated from these four base readings.
The device may return numbers indicating non-square pixels if either the physical sizes are not accurate or the device truly has non-square pixels.
The ppmm and ppi values are calculated from the screen diagonal to get one easy number
The pixelShape (aspect ratio) figure is based calculated figures and so may be slightly off as well.
pixelShape = 1 means square, 2 means twice as wide as high, 0.5 means twice as wide as high (it is doubtful you'll ever see anything far from 1)
Building the extension from source
Copy the extension folder to a location on your computer to start working with it.
Momentics NDK setup
- Open the Momentics IDE. Navigate to the workbench and from the program menu select File -> Import and choose "Existing Projects into Workspace".
- Choose "Select root directory: " and browse to the NDK_project directory where you copied the extension. Select the screendisplay project in the Projects list and uncheck "Copy projects into workspace". Click Finish.
- Follow these next steps to build the extension to be sure the setup is working.
How to build your native Extension
- Right click your project and select the Clean Project option.
- Right click your project again and select Build Configurations -> Build Selected... .
- A window will appear that shows all the available build configurations for the project. Select Device-Release and Simulator-Debug and click ok.
- You should see the shared libraries generated in the folders for each Build Configuration that you selected.
- Copy the .so file(s) to the device and simulator folders under the ext/community.screendisplay directory. Or you can use the Ant build script to do so.
Copying the Extension to the SDK
- Under the ext folder in this project should be the community.screendisplay folder with the following file structure underneath it:
If you wish to do the copying manually, continue with these steps:
- The device and simulator folders should contain the libScreenDisplay.so files built by the NDK.
- Copy the community.screendisplay folder into your WebWorks SDK, placing it in the Framework/ext directory.
If you have Ant installed and would like to use the build script provided, edit the script as follows (you will find it in the /ext directory, called build.xml ).
- Change the project name to match the extension name in manifest.json.
- Change the bbwp.native.dir value to match the SDK you want to deploy to.
- Type ant at a command prompt while in the /ext directory of the Extension.
The build script will clean any old extension from your SDK, copy the .so files build by the NDK into the correct locations, and finally copy the whole extension into the SDK.
Using the Extension in an Application
With the extension copied into your WebWorks SDK as explained above, you can use it in your applications by referencing it as a feature in your config.xml file.
<feature id="community.screendisplay" />
Modifying the Extension
See the examples in the Template Extension for how to add additional features to this extension
When making changes, rebuild regularly so you don't make a really hard to find typo.
To contribute code to this repository you must be signed up as an official contributor.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.