C/C++ Guides

Home

The NativeUI C++ Library

The MoSync NativeUI C++ Library is built on our Widget C API. It provides classes and functions for high-level control of native user-interface elements.

Platform and Emulator Support

The NativeUI C++ Library and the underlying Widget C API are designed to work with native user-interface controls. The library is designed to support platforms with native (i.e. proprietary) touch and graphical interfaces such as Android, iOS, and Windows Phone 7. Some widgets are specific to one particular platform.

You can test your NativeUI Library application directly from the MoSync IDE as long as you have installed at least one native emulator. (NativeUI applications will not, of course, work in the MoSync MoRE emulator.)

Not all of the widget types are supported on all platforms — they are, after all, native widgets! For a list of the platforms on which this Library is supported, see Feature/Platform Support.

The Widget API

The NativeUI Library is built on our Widget API which provides a comprehensive range of low-level functions (syscalls), event types, and constants for creating and working with native user-interface widgets like screens, layouts, buttons, and many more.

Example Applications

We provide many example applications that make use of the Widget API or the NativeUI Library (which is itself a high-level wrapper for the Widget API). The examples and the API/Library they use include:

  • NativeUIDemo -- NativeUI Library
  • VideoNativeUIExample -- NativeUI Library
  • DeviceFontsNativeUI -- NativeUI Library
  • MoCamera -- NativeUI Library
  • WikiSearchNativeUI -- Widget API
  • HelloNativeUI -- NativeUI Library
  • RockPaperScissors -- Widget API

The NativeUI Library

The library is a high-level wrapper that supports all the widgets in the Widget API. It includes:

  • Support for all types of widgets, along with their specific properties and events.
  • A base Widget class that takes care of instantiated objects and their destruction. This class also provides methods for managing widgets, like addChild, insertChild, and removeChild, and methods for manipulating widgets like setHeight, setVisiblefillSpaceHorizontally and fillSpaceVertically.
  • A background widget manager that handles widget events. You do not have to use the CustomEventListener to catch widget events: you can receive only widget specific events by setting listeners to widget objects, for example: buttonObject->addButtonListener(this).
  • A set of base widget functions (setPropertyInt, getPropertyString) that can be called at any time instead of the specific functions.
  • Support for adding modal dialogs via the Dialog class. A dialog object acts like a container for any kind of widgets. Remember that a Dialog modal widget cannot have parents, so adding a dialog to a layout will have no effect.
  • Support for Fonts:
    • Access all fonts stored on the device.
    • Setting the font based on font type and font style.

Widgets Available Through NativeUI

  • Activity Indicator
  • Button
  • CameraPreview
  • Check box
  • Date Picker
  • Edit box
  • GL View
  • Horizontal layout
  • Image
  • Image Browser
  • Image Button
  • Label
  • List View
  • List View Item
  • Navigation Bar
  • Number Picker
  • Panorama View
  • Progress Bar
  • Relative Layout
  • Screen  
  • Screen Options Menu
  • Search Bar
  • Slider
  • Stack Screen
  • Tab Screen
  • Time Picker
  • ToggleButton
  • Vertical layout
  • Video View
  • Web View

Widget Creation

For each type of widget there is a corresponding class, so the routine in which a widget is instantiated is very simple:

WidgetType* myNewWidget = new WidgetType().

Do not forget to include the header file for all widgets, Widgets.h, or each widget class one by one.

Widget Properties

The shared methods implemented across all widgets include:

  • setProperty and getProperty for true property types.
  • getWidth(), getHeight()
  • setWidth(width), setHeight(height)
  • setSize(width, height)
  • wrapContent and fillAvailableSpace for a certain dimension.
  • setBackgroundColor
  • setVisible(visible)
  • setEnabled(enabled)
  • setBackgroundColor(color)
  • setBackgroundGradient(color1, color2)
  • getLastError: get details about the last error that has occurred, in a structure. Causes might be any of the following:
    • A widget was instantiated but it's type is not yet available on the target platform.
    • A property was set/get on a widget that is not yet available on the target platform.
    • A setter/getter method received an invalid property name.
    • A syscall has failed due to invalid parameters.
    • NOTE: In order to have this structure empty, make sure you read carefully the documentation before you use the NativeUI library.

For all properties, we have endeavoured to implement them as separate methods, rather than as setProperty/getProperty function calls.

Widget Events

The library implements separate listeners for each widget that can receive events. Take, for instance the EditBoxListener. The EditBox widget might send 4 types of events:

  • EDITING_DID_BEGIN
  • EDITING_DID_END
  • TEXT_CHANGED
  • RETURN

Those events will notify the user with respectively the callbacks:

  • editBoxEditingDidBegin(editBox)
  • editBoxEditingDidEnd(editBox)
  • editBoxTextChanged(editBox,text)
  • editBoxReturn(editBox)

More than just one listener can be attached to a widget. Attaching a listener to a widget can be done in this way:

EditBox* myEditBox = new EditBox();
myEditBox->addEditBoxListener(this);

Dialogs

A Dialog is a modal view that can look different depending on the platform:

  • On Android it is a modal alert dialog
  • On iPad it is a PopoverController
  • On the iPhone it is a modal view.
  • On WP7 is not currently available

When a Dialog widget is created it is empty, it has no content. Use setMainWidget(mainLayout) to set the main widget of the dialog.

A Dialog gets visible only after calling show() method.

Usage example:

Dialog* myDialog = new Dialog();
myDialog->setTitle("My Form");
// Set specific iPad property for position, so that
// the dialog arrow points up.
myDialog->setArrowPosition(MAW_CONSTANT_ARROW_UP);
// Set its content.
myDialog->setMainWidget(mainLayout);
...
// Display the dialog at the right time.
myDialog->show();

Fonts Support

Access to device fonts can be acomplished via font syscalls (see maFontGetCount, maFontLoadDefault, maFontGetName, maFontLoadWithName, etc).

After getting the desired font using maFontLoadDefault or maFontLoadWithName, the handle to the font can be applied via the method setFont to the widgets:

  • Label
  • Button
  • ImageButton
  • ListViewItem
  • Navigation bar's title.

Example:

// Get the first available font of the device.
if ( maFontGetCount() > 0 )
{
    char buf[256];
    maFontGetName(0, buf, 256);
    // Load the font with size 10 and get it's handle.
    int fontHandle = maFontLoadWithName(buf, 10);
        myLabel->setFont( fontHandle );
}

At any time the font color can be set by calling the method setFontColor:

enum Colors
{
    INTENSE_BLUE = 0x104E8B ,
    LIGHT_BLUE = 0xB2DFEE
};
myLabel->setFontColor(LIGHT_BLUE);

Also, the font size can be set for the widget in use, without having to actually modify the font resource:

#define FONT_SIZE_REGULAR 15.3

myLabel->setFontSize(FONT_SIZE_REGULAR);

Note: When building applications that use Native UI,  remember to select an iOS, Android or WP7 target in the right-hand device profile panel.

MoSync SDK 3.3
Copyright © 2013 MoSync AB
www.mosync.com