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
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 |