If you look at a openings_and_additions.txt file with an editor, you’ll see a section bordered by asterisks like this:
You’ve told the designer a great deal about your app and case. There’s no need for you to dig up that information again when putting instructions into the openings_and_additions.txt file. You can just use these variables and calculations.
Let’s look at a specific example of using variables when specifying raised features for the screen region of your keyguard.
This is an example of a keyguard for use with Lamp Words for Life – VI (LWFL-VI):
A LWFL-VI keyguard has several characteristic features. The app is a grid with 7 rows and 12 columns. The keyguard has 8 raised ridges around 8 openings. You can create a keyguard like this simply by entering values into the Customizer pane of the designer.
But a LWFL-VI keyguard has additional characteristics. It has 14 straight ridges around the outside of the grid area. There’s no way to use the Customizer pane to specify these ridges. We’ll create them by putting instructions into the screen_openings data structure.
[Note that you can also create these ridges by putting instructions into the case_openings data structure but you might get results that don’t make sense. For now, just accept that any features of your keyguard that are tied to the screen layout should go in the screen_openings data structure.]
You’ll add 14 instructions to the screen_openings data structure file, one for each ridge. Ten vertical ridges (“vridge”) and four horizontal ridges (“hridge”). Ridges have a length, height and thickness. You specify the length of vertical ridges by putting a value in the “height” column. Conversely, you specify the length of a horizontal ridge, by putting a value in the “width” column. The height and thickness of a ridge are specified by putting values in the “top slope” and “bottom slope” columns
The difficult part of specifying these ridges is determining exactly where the ridges should be placed. In other words, you need to specify the “x” and “y” coordinates for each ridge:
Fortunately, there’s some regularity to where the ridges are placed. They are centered along certain horizontal and vertical rails. We can use screen variables to calculate these coordinates of these rails.
Using the Grid Variables
You’ve given the designer lots of information about the layout of your app. Using this information, the designer knows the size of the grid area of the app:
The variable “gh” contains the height of the grid; and the variable “gw” contains the width.
The Free-form and Hybrid Keyguard Settings section
For this example we’ll be using millimeters as our unit of measure and making measurements relative to the upper left corner of the screen (i.e., the “y” value will get larger as you move down the screen). So we set the values in this section as follows:
[Note that these settings are only important for how the designer interprets the numbers you put in the screen_openings data structure. You can still use pixels to specify the layout of your app in the “App Layout in px” section of the Customizer pane.]
Calculating the x-coordinate for vertical ridges
There are 12 columns of openings in the grid so we can determine the distance between the centers of the vertical rails (i.e., the vertical rail distance) by dividing the grid width by 12:
vrd = gw/12;
We can put this statement at the beginning of the “openings_and_addtions.txt” file. Note that the line has a semicolon at the end.
Since the left edge of the grid is equal to the left edge of the screen, the x-coordinate for the first vertical rail is 0 + gw/12, and the x-coordinate for the left-most vertical ridge (both above and below the openings) is 2 * gw/12.
Similarly, we can calculate the distance between the centers of horizontal rails (i.e., the horizontal rail distance):
hrd = gh/7;
Measuring from the top of the screen, the grid starts at the bottom of the upper command bar:
The location of the bottom of the upper command bar is contained in the variable “ucbb” (upper command bar bottom):
[Note: if you set “unit of measure for screen” in the “Free-form and Hybrid Keyguard Settings” section to “mm” then this value will be in millimeters. If set to “px” then the value will be in pixels.]
The y-coordinate of the upper-most horizontal ridge can be calculated as:
ucbb + 3 * gh/7
In the example here, we’ve set “unit of measure for screen” to “mm” so the designer assumes that the “3” is in millimeters. [Note: if you want to put an instruction into the .txt file that includes a measurement in pixels, you can multiply that pixel measurement times another variable, “mpp” (millimeters per pixel), to turn your pixel measurement into a millimeter measurement.]
The x-coordinates of the horizontal ridges and the y-coordinates of the vertical ridges are best determined by eye and then repeated for ridges of the same type:
Benefits of using variables
The variables are much more valuable than just giving you a way to create a calculation using a data that you entered into the Customizer pane.
The best reason for using variables, and calculations based on the variables, is that they continue to be correct even if you change tablets and app layouts. For example, y-coordinate of the top-most horizontal ridge in a LWFL-VI keyguard will be “ucbb + 3 * gh/7” regardless of what tablet is being used or what upper message bar height setting is used. So, you can use the same screen_openings data structure with any LWFL-VI keyguard.
This can help you save time and avoid mistakes.