VoltMXDataMapper

A VoltMXDataMapper class helps update UI widgets on an Apple Watch application. This class accepts a dictionary of information and automatically maps the dictionary contents on to the widget properties when the dictionary follows a pre-defined format. Typically, this dictionary is the response data received from a phone application using VoltMXWatchKitUtil APIs. The class has the following APIs:

initWithObject: This API helps initialize VoltMXDataMapper object. This API accepts an object that manages UI widgets (an object of WKInterfaceController class) as a parameter to map the widget properties with the dictionary contents.

Note: If you initialize VoltMXDataMapper object using the init function, an exception will result.
updateWidgetPropertiesFromDictionary: This API updates the widget properties with the input dictionary contents. This API relies on outlets (properties) defined in the controller object to map the dictionary contents. The keys in the dictionary are the names of the outlets in the object passed as a parameter in VoltMXDataMapper object creation. The values must be the dictionary with keys as properties of outlets and their corresponding values.

Note: Some widgets can accept string also as a value.

Sample code to create object and updating the properties

//Sample code
VoltMXDataMapper *dataMapper = [[VoltMXDataMapper alloc] initWithObject:self];//Here self is the InterfaceController
[dataMapper updateWidgetPropertiesFromDictionary:aDictioanry];

The followingare the widgets supported by VoltMXDataMapper class:

Button
Date
Group
Image
Label
Map
Switch
Separator
Slider
Timer
Table

Button

This widget (an instance of WKInterfaceButton class) represents a tappable area on the watch screen. A button supports actions that help invoke a method. For example, when you tap on the watch screen, an action associated with the button gets invoked. A button can be enabled or disabled dynamically. You can assign the styles for a title using attributed title.

You cannot add a Button widget to the following forms:

Notification Static
Notification Dynamic
Glances

Properties

The followingare the properties of the Button Widget.

Property	Description	Modifiable at Runtime
alpha	The opacity of the object. A value of 1.0 represents fully opaque and a value of 0.0 represents fully transparent.	Yes
backgroundColor	A string that specifies the background color of the button.	Yes
backgroundImage	A string that specifies the background image name for the button.	Yes
color	The color to apply to the button’s title.	No
enabled	A Boolean value that indicates whether the button is enabled. The default is true.	Yes
font	The font to apply to the button’s title.	Yes
height	The height of the object. Specify a fixed height or set the value of the object to be a percentage of its container’s height.	Yes
hidden	Indicates whether the item is hidden initially.	Yes
horizontal	The horizontal alignment of the item. Use this attribute to configure the horizontal position of the item relative to its immediate parent.	No
id	A string containing a unique identifier for the button.	No
image	A string containing the name of the image to use for the button.	Yes
installed	A Boolean value that indicates whether the item is rendered for the current device	No
mode	The image scaling mode to be used for the button’s image.	No
opacity	A numeric value that specifies the opacity of the widget. The value of this property must be in the range 0.0 (transparent) to 1.0 (opaque). Any values outside this range are fixed to the nearest minimum or maximum value.	Yes
render	A Boolean value that specifies whether the button will be rendered.	No
title	A string that specifies the title of the button.	Yes
vertical	The vertical alignment of the item. Use this attribute to configure the vertical position of the item relative to its immediate parent.	No
visible	A value that specifies whether the button is visible. It accepts a Boolean value in a case-sensitive string or nonstring formats such as "true" / "false" or true/false. You can also specify 0 for true or 1 for false.	Yes
widgetAlignment	Indicates how a widget is to be anchored with respect to its parent.	No
width	The width of the object. Specify a fixed width or set the value of the object to be a percentage of its container’s width.	Yes

Event

The button widget provides the following event.

Event	Description
onClick	Triggered when the button is clicked by the user.

Example

//Defining the button properties.
    "button": {
        "title": "button title",
        "backgroundColor": "#654321",
        "backgroundImage": "image"
    }

// You can also configure the button using the string.

        "button": "buttonName"

Note: Images must be placed in the "ImageAssests" folder, and the image name must be specified as values in a dictionary. By default, images have a higher priority than color. If the specified image name is not found, then the color is applied.

Date

This widget (an instance of WKInterfaceDate class) displays the date or time on the watch screen. A date can be configured by time zone and calendar. You can dynamically change the color of the date. The iOS-supported calendar and time zones must be specified as string.

The followingare the supported calendar formats:

GregorianCalendar
BuddhistCalendar
ChineseCalendar
CopticCalendar
EthiopicAmeteMihretCalendar
EthiopicAmeteAlemCalendar
HebrewCalendar
ISO8601Calendar
IndianCalendar
IslamicCalendar
IslamicCivilCalendar
IslamicTabularCalendar
IslamicUmmAlQuraCalendar
JapaneseCalendar
PersianCalendar
RepublicOfChinaCalendar

Properties

The followingare the properties of Date Widget.

Property	Description	Modifiable at Runtime
alpha	The opacity of the object. A value of 1.0 represents fully opaque and a value of 0.0 represents fully transparent.	Yes
calendar	A string that specifies the type of calendar to use.	Yes
contentAlignment	A value that specifies the alignment of the content. Can be set to one of the following: Left, Right, Center, Justify.	No
date	The date information to display. The date options correspond to the values of the NSDateFormatterStyle type defined in the Apple documentation. kCFDateFormatterNoStyle, kCFDateFormatterShortStyle, kCFDateFormatterMediumStyle, kCFDateFormatterLongStyle, kCFDateFormatterFullStyle	No
format	A selector for choosing between standard and custom formats. For standard formats, you use the Date and Time attributes to configure the information you want to display. Changing the value of this attribute to Custom lets you configure the date exactly the way you want based on the format options.	No
height	The height of the object. Specify a fixed height or set the value of the object to be a percentage of its container’s height.	Yes
hidden	Indicates whether the item is hidden initially.	Yes
horizontal	The horizontal alignment of the item. Use this attribute to configure the horizontal position of the item relative to its immediate parent.	No
id	A string containing a unique identifier for the widget.	No
installed	A Boolean value that indicates whether the item is rendered for the current device	No
opacity	A numeric value that specifies the opacity of the widget. The value of this property must be in the range 0.0 (transparent) to 1.0 (opaque). Any values outside this range are fixed to the nearest minimum or maximum value.	Yes
preview	A preview of what the date and time will look like.	No
render	A Boolean value that specifies whether the widget will be rendered.	No
textColor	A hexadecimal string that specifies the color of the date.	No
time	The time information to display. The time options correspond to the values of the NSDateFormatterStyle type	No
timeZone	A string that specifies the time zone for the date.	Yes
vertical	The vertical alignment of the item. Use this attribute to configure the vertical position of the item relative to its immediate parent.	No
visible	A value that specifies whether the item is visible. It accepts a Boolean value in a case-sensitive string or nonstring formats such as "true" / "false" or true/false. You can also specify 0 for true or 1 for false.	Yes
width	The width of the object. Specify a fixed width or set the value of the object to be a percentage of its container’s width.	Yes

Example

//Defining the date properties.
        "date": {
            "textColor": "#123456",
            "timeZone": "Asia/Kolkata",
            "calendar": "IndianCalendar"
        }

Note: The order of the keys is not mandatory. You can use only the required key-value pairs.

Group

This widget (an instance of WKInterfaceGroup class) helps group one or more widgets. The group acts as a container. Configure a group by setting image, color, and cornerRadius.

You can add the Group widget to the following forms:

App forms
Glance Forms
Notification Static Notification Dynamic

Properties

The followingare the properties of the Group Widget.

Attribute	Description	Modifiable at Runtime
animate	A Boolean value indicating whether the background image can be animated. Set the value to Yes to configure the animation parameters, including its duration (in seconds) and whether it starts immediately when the parent interface controller appears onscreen. Animations started at load time run continuously in a loop.	No
background	A string containing the name of the image to use for the image that is displayed behind the group’s items.	Yes
backgroundColor	A string that specifies the background color of the widget.	Yes
backgroundImage	A string that specifies the background image name for the button.	Yes
border	The border style for the group.	No
bottom	The number of pixels to pad on the bottom of the widget.	No
height	The height of the object. Specify a fixed height or set the value of the object to be a percentage of its container’s height.	Yes
id	A string containing a unique identifier for the widget.	No
insets	The amount of space (in points) to insert between the edges of the group and its parent container. Selecting Custom lets you specify different values for the top, bottom, left, and right edges.	Yes
layout	A value that specifies how items in the group are laid out. Can be set to FlowHorizontal or FlowVertical.	No
left	The number of pixels to pad on the left side of the widget.	No
mode	The content mode for the group’s background image. Use this option to specify whether the image is scaled or pinned to a particular edge of the group.	No
opacity	A numeric value that specifies the opacity of the widget. The value of this property must be in the range 0.0 (transparent) to 1.0 (opaque). Any values outside this range are fixed to the nearest minimum or maximum value.	Yes
radius	The corner radius to apply to the group’s rectangle. Content inside the group is clipped to the corner radius. If you do not specify a custom value, WatchKit applies a 6-point radius by default.	Yes
render	A Boolean value that specifies whether the widget will be rendered.	No
right	The number of pixels to pad on the right side of the widget.	No
spacing	Additional spacing (in points) to include between items in the group.	No
top	The number of pixels to pad on the top of the widget.	No
visible	A value that specifies whether the item is visible. It accepts a Boolean value in a case-sensitive string or nonstring formats such as "true" / "false" or true/false. You can also specify 0 for true or 1 for false.	Yes
width	The width of the object. Specify a fixed width or set the value of the object to be a percentage of its container’s width.	Yes

Example

//Defining the group properties.
        "group": {
            "backgroundColor": "#123456",
            "backgroundImage": "image",
            "cornerRadius": "2.0"
        }

Note: The order of the keys is not mandatory. You can use only the required key-value pairs.

Image

The Image widget (an instance of WKInterfaceImage class) is non-interactive widget that you can use to display a bitmapped image on the watch. The Image widget can display either a single image or sequence of images to play an animation.

Note: Images must be present in the ImageAssests folder.

Supported Image formats:

All the image formats supported by iOS. Preferabley PNG or JPEG. Other supported formats can introduce performance issues.

File Naming conventions

Single image:

Ex: sample.png

Image sequence :

Ex: sample1.png, sample2.png, sample3.png…etc

Properties

The followingare the properties of the Image Widget.

Attribute	Description	Modifiable at Runtime
alpha	The opacity of the object. A value of 1.0 represents fully opaque and a value of 0.0 represents fully transparent.	Yes
animate	A Boolean value indicating whether the image can be animated. Set the value to Yes to configure the animation parameters, including its duration (in seconds) and whether it starts immediately when the parent interface controller appears onscreen. Animations started at load time run continuously in a loop.	No
height	The height of the object. Specify a fixed height or set the value of the object to be a percentage of its container’s height.	Yes
hidden	Indicates whether the item is hidden initially	Yes
horizontal	The horizontal alignment of the item. Use this attribute to configure the horizontal position of the item relative to its immediate parent.	No
imageName	The name of the image to be displayed. This image must be in the WatchKit app’s bundle.	Yes
installed	Indicates whether the item is rendered for the current device	No
mode	The content mode for the image. This mode defines how the image scales or fills the image area.	No
tint	The color applied to a template image.	Yes
vertical	The vertical alignment of the item. Use this attribute to configure the vertical position of the item relative to its immediate parent.	No
width	The width of the object. Specify a fixed width or set the value of the object to be a percentage of its container’s width.	Yes

Example

//Defining the image properties.
        "image": {
            "imageName": "imageName",
            "tintColor": "#654321"
        } 

// You can also configure the Image using the string.
            "image": "imageName"

Note: The order of the keys is not mandatory. You can use only the required key-value pairs.

Label

This widget (an instance of WKInterfaceLabel class) displays text on the watch screen. The text is displayed using the system default font, scale, and alignment. To use custom values for text, use attributed text. The default label color is white.

The following are the properties of the Label Widget:

Attribute	Description	Modifiable at Runtime
alignment	The alignment of the text within its bounding rectangle. Use this attribute to align text when the width of the label is greater than the width of the text itself.	No
alpha	The opacity of the label. A value of 1.0 represents fully opaque and a value of 0.0 represents fully transparent.	Yes
font	The font information to be applied to the text. You can specify one of the predefined styles or provide custom