Pebble Watch Face SDK #7: ScrollLayers

Previous Tutorial Sections

All six previous parts of this tutorial series can be found on the ‘Pebble SDK Tutorial’ page link at the top of the page. Please read them if you are not already up to speed!

Introduction

By request, this part of the tutorial will focus on using the ScrollLayer structure provided by the Pebble SDK. This is the Layer type used for menus, such as the main menu or settings menu. In fact, the MenuLayer itself contains a ScrollLayer!

The features of a ScrollLayer are thus:

  • It can be controlled with the up and down buttons to show more content that can fit on the screen at any one time.
  • It automatically shows ‘shadows’ at the top and bottom of the screen to indicate there is more to see in both the up and down direction.
  • It can contain all the Layers that it scrolls, making parent-child layer management easier.

Lets get started!

Using a ScrollLayer

To make use of this Layer type in a watch app, you will need something to display inside it. For this example, I’ll be using a snippet of text from getpebble.com, in a char array as shown below (using the fiendishly hidden WordPress code tags!):

char scrollText[] = "Pebble is the first watch built for the 21st century. It's infinitely customizable, with beautiful downloadable watchfaces and useful internet-connected apps. Pebble connects to iPhone and Android smartphones using Bluetooth, alerting you with a silent vibration to incoming calls, emails and messages. While designing Pebble, we strove to create a minimalist yet fashionable product that seamlessly blends into everyday life.";

You can use other Layer types, but this is good for simplicity.

As is usual for the Pebble SDK, we call functions to initialize and setup our Window and Layers, in the handle_init() function. I’ll show this process below, but first here are the constants and globals that will be making an appearance:

//Globals
Window window;
ScrollLayer sLayer;
TextLayer tLayer;

//Maximum dimensions
static int WIDTH = 144;
static int MAX_HEIGHT = 1000;

//Compensate for top window bar
static int TOP_BAR_PADDING = 20;

And now the main code segment:

/**
	* Resource initialisation handle function
	*/
void handle_init(AppContextRef ctx) {
	(void)ctx;

	//Init window
	window_init(&window, "Main window");
	window_set_background_color(&window, GColorWhite);
	
	//Init ScrollLayer and attach button click provider
	scroll_layer_init(&sLayer, GRect(0, 0, 144, 168));
	scroll_layer_set_click_config_onto_window(&sLayer, &window);
	
	//Init TextLayer
	text_layer_init(&tLayer, GRect(0, 0, WIDTH, MAX_HEIGHT));
	text_layer_set_text(&tLayer, scrollText);
	text_layer_set_background_color(&tLayer, GColorClear);
	text_layer_set_text_color(&tLayer, GColorBlack);
	text_layer_set_text_alignment(&tLayer, GTextAlignmentLeft);

	//Get size used by TextLayer
	GSize max_size = text_layer_get_max_used_size(app_get_current_graphics_context(), &tLayer);
  
	//Use TextLayer size
	text_layer_set_size(&tLayer, max_size);
  
	//Use TextLayer size for ScrollLayer - this has to be done manually for now!
	scroll_layer_set_content_size(&sLayer, GSize(WIDTH, max_size.h + TOP_BAR_PADDING));
	
	//Add TextLayer to ScrollLayer to Window
	scroll_layer_add_child(&sLayer, &tLayer.layer);
	layer_add_child(&window.layer, (Layer*)&sLayer);

	//Show Window
	window_stack_push(&window, true);
}

Read through the code above line by line and see the new additions that you might not have seen before. Below are the ones of note:

  • scroll_layer_init() – This does the same sort of actions as window_init() or text_layer_init() and initializes the ScrollLayer supplied as the first argument.
  • scroll_layer_set_click_config_onto_window() – This gives the ScrollLayer the button click information from the containing window, so that it can respond to button pressed while in this window.
  • text_layer_get_max_size_used() – This returns a GSize that is the dimensions that the TextLayer that the ScrollLayer contains uses. The alternative here is to find the point size of the font and find by trial and error the vertical height from the number of lines the text ends up using – a waste of time!
  • scroll_layer_set_content_size() – This function uses the GSize created before to set the size of the ScrollLayer. Without this information it would not be able to tell how far to be able to scroll up or down. At the moment this must be done manually.
  • scroll_layer_add_child() – This function does the same as the layer_add_child() function we’ve used before for TextLayers being added to the Window, but this time the Layer supplied as an argument is added to the layout inside the ScrollLayer, and will therefore be scrollable.

Finally, after using layer_add_child() to add the ScrollLayer to the Window, you should be all set!

Conclusion

The ScrollLayer can be useful for showing a lot of information or a list. It does require some extra thinking about and setup, but it is worth it for the convenience!

Full source code for a sample watch app (derived from the ‘demos’ supplied with the SDK) can be found here.

Happy scrolling!

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: