pebble-scalable 1.6.0 → 2.1.0

package/README.md

@@ -1,15 +1,19 @@
 # pebble-scalable
 
 Package aiming to make it easy to make scaling layouts for different display
-sizes by defining their dimensions only once.
+sizes by defining their dimensions only once in an app.
 
+- [Features](#features)
 - [Setting up](#setting-up)
 - [Layout](#layout)
+- [Constants](#constants)
 - [Centering](#centering)
 - [Fonts](#fonts)
 - [Images](#images)
 
-See `include/pebble-scalable.h` for function documentation.
+## Features
+
+See `include/pebble-scalable.h` for full function documentation.
 
 ## Setting up
 
@@ -31,38 +35,50 @@ Get values for layout dimensions based on display size:
 
 > To convert existing layouts, simply divide the raw coordinate by either the
 > width or height of the preferred screen size to get a percentage.
-> For example, a Y coordinate of 40px - 40 / 168 = 0.238 = 23.8%, so the correct
-> call would be `scalable_y(235)`.
+> For example, a Y coordinate of 40px: 40 / 168 = 0.238 = 23.8%, so the correct
+> call would be `scl_y(238)`.
 
 ```c
 // Get a percentage (thousands) of the display width and height
-const int half_w = scalable_x(500);
-const int half_h = scalable_y(500);
+const int half_w = scl_x(500);
+const int half_h = scl_y(500);
 
 // Get a GRect based only on percentage width/height
-const GRect center_rect = scalable_grect(330, 330, 330, 330);
+const GRect center_rect = scl_grect(330, 330, 330, 330);
 ```
 
 If a single percentage isn't precise enough, use 'per platform' variants to
 specify values up to 5% (50/1000 thousands) in precision for each platform
-(order is 'regular' shape, then 'emery' shape):
+(order is 'regular' shape, then 'emery' shape). 
 
 > In actuality, thousandths values should allow per-pixel precision until a
 > display shape is larger than 1000px in any direction.
 
+This is done with members of a struct for each distinct platform shape:
+
+- `o` - "Original size": aplite, basalt, diorite, flint
+- `c` - Chalk
+- `e` - Emery
+
+> This method allows transparently adding more platforms in the future without
+> breaking existing code!
+
 ```c
-// Larger only on Emery (x/y: 10%, w/h per platform)
-const GRect emery = scalable_grect_pp(
-  GRect(100, 100, 200, 200),
-  GRect(100, 100, 250, 250)
+// Larger only on Emery
+const GRect emery = GRect(
+  0, 0,
+  scl_x_pp({.o = 200, .e = 250}),
+  scl_y_pp({.o = 200, .e = 250})
 );
 
 // Further to the right and down on Emery
-const int x = scalable_x_pp(110, 120);
-const int y = scalable_y_pp(450, 480);
+const int x = scl_x_pp({.o = 110, .e = 120});
+const int y = scl_y_pp({.o = 450, .e = 480});
 ```
 
-The library also exports constants:
+## Constants
+
+The library also exports constants for all platforms:
 
 * `PS_DISP_W` - current display width.
 * `PS_DISP_H` - current display height.
@@ -72,16 +88,24 @@ The library also exports constants:
 A GRect can be centered in either the X or Y axis, or both:
 
 ```c
-const GRect r = scalable_grect(100, 500, 200, 200);
+const GRect r = scl_grect(100, 500, 200, 200);
 
 // Center horizontally
-const GRect centered_h = scalable_center_x(r);
+const GRect centered_h = scl_center_x(r);
 
 // Center vertically
-const GRect centered_v = scalable_center_y(r);
+const GRect centered_v = scl_center_y(r);
 
 // Or both!
-const GRect centered = scalable_center(r);
+const GRect centered = scl_center(r);
+```
+
+On any display shape, you can get the largest completely visible square, which
+is useful on round displays if you want to avoid things being obscured by the
+corners:
+
+```c
+const GRect visible = scl_largest_square();
 ```
 
 ## Fonts
@@ -108,33 +132,33 @@ Next, define identifiers for each of your size categories:
 
 ```c
 typedef enum {
-  MFS_Small = 0,
-  MFS_Medium,
-  MFS_Large
-} MyFontSizes;
+  FID_Small = 0,
+  FID_Medium,
+  FID_Large
+} FontIds;
 ```
 
 Now set which font to use per-platform shape for each category:
 
 ```c
 // The small font - regular screens use Gothic 14, Emery uses Gothic 18
-scalable_set_fonts(MFS_Small, &s_gothic_14, &s_gothic_18);
+scl_set_fonts(FID_Small, {.o = s_gothic_14, .e = s_gothic_18});
 
 // Same with larger categories
-scalable_set_fonts(MFS_Medium, &s_gothic_18, &s_gothic_24);
-scalable_set_fonts(MFS_Large, &s_gothic_24, &s_gothic_28);
+scl_set_fonts(FID_Medium, {.o = s_gothic_18, .e = s_gothic_24});
+scl_set_fonts(FID_Large, {.o = s_gothic_24, .e = s_gothic_28});
 ```
 
 During layout or drawing, simply use the font by ID:
 
 ```c
-// Text in the vertical middle third!
+// Choose size ID, font is selected automatically
 graphics_context_set_text_color(ctx, GColorBlack);
 graphics_draw_text(
   ctx,
   "This text should appear in the middle third on any platform or display size",
-  scalable_get_font(MFS_Small),
-  scalable_grect(0, 330, 1000, 330),
+  scl_get_font(FID_Small),
+  scl_grect(0, 330, 1000, 330),
   GTextOverflowModeTrailingEllipsis,
   GTextAlignmentCenter,
   NULL
@@ -153,7 +177,7 @@ and size. For example, `icon.png` and `icon~emery.png`.
 graphics_draw_bitmap_in_rect(
   ctx,
   s_icon_bitmap,
-  scalable_center_x(scalable_grect(0, 850, 150, 150))
+  scl_center_x(scl_grect(0, 850, 150, 150))
 );
 ```
 
@@ -161,4 +185,7 @@ graphics_draw_bitmap_in_rect(
 
 - [x] Support per-platform (per shape) values
 - [x] Solution for picking bitmaps (to work with their scalable GRects)
-- [ ] Chalk? It's so different layouts might not be at all similar...
+- [x] Find solution to 'ever expanding args' problem for new platforms
+- [x] Chalk support
+- [ ] Gabbro support
+- [ ] Can we save devs loading all fonts when only some are used on a platform?

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pebble-scalable",
   "author": "Chris Lewis",
-  "version": "1.6.0",
+  "version": "2.1.0",
   "files": [
     "dist.zip"
   ],