MoSync is a tool from Mobile Sorcery that enables mobile developers to rapidly and easily create applications for a wide range of mobile devices without having to worry about porting issues. Thanks to an advanced and constantly updated device profiling system, MoSync ensures that the same code can be built to run on a multitude of mobile platforms and devices. With MoSync, the developer can finally concentrate on creating quality products and services that will be able to reach virtually any mobile device. MoSync aims to fill the gap currently present in the mobile development world and unify the fragmented market faced by developers when dealing with porting their applications to the diverse range of mobile devices, across both platforms and models.

Mobile Sorcery is a software development house that generates and develops tools for the mobile industry. Our tools are designed to enable faster, easier and more cost efficient development of mobile applications and content.

Microsoft Windows XP or Vista (tested and works on Windows 7 beta 1)
100MB free harddrive space.
Java SE Runtime Environment (JRE) 6 installed.

You can download MoSync from our website, http://www.mosync.com .
You are strongly encouraged to register an account to receive latest product updates, additional profile database and tips from our developers. You may register for an account for free through the MoSync IDE. Read the next section for instructions on how to install and register MoSync.

Before installing MoSync you will need to download and install the Java SE Runtime Environment which can be found at, http://java.sun.com/javase/downloads/index.jsp .
After you have retrived the MoSync installer, double-click the installer icon to begin the installation. Just wait while the installer configures itself. First the the unpacker needs to unpack the files which will be installed.



The MoSync package splash-screen, if you see this the package was succesfully unpacked.



Read the MoSync License Agreement. Agree to it if you would like to proceed with the installation.



Select the components you wish to install. Note that there isn't any options for the MoSync package, everything needs to be installed.



Select where you would like MoSync to be installed. Please note that MoSync needs to be installed to a directory which is not containing any spaces in its path.



If you have a previously uninstalled copy of MoSync you will get this warning. Please follow the instruction and make a copy of your project files if they are inside the MoSync installation folder. Even if they shouldn't be removed it's better to be safe than sorry.



If you had a previous installation it will first be removed. Now MoSync is installed on your computer. Please wait for the installation to complete.



MoSync is now installed. Press Finish to end the installer. Please note that the 'Open Documentation.' checkbox is set as default.

The first time you Launch the MoSync IDE

Congratulations, you have just installed MoSync which we hope you will like as much as we do. If you choose to have a desktop shortcut you can now use that, it's called MoSync. Otherwise you can use the shortcut in the startmenu. It's in the folder 'MoSync' and is named 'MoSync IDE'. If you choose to install without shortcuts the file is called 'mosync.exe' and is placed in the 'eclipse' folder in the root of the installation, default is C:\MoSync. When you start it you should see this splash-screen.



The MoSync IDE wants to know where you would like to have your Workspace. This is where your projects, by default, will be stored. If you wish to use the same Workspace for all your projects you can set the checkbox, 'Use this as the default and do not ask again', and you will not be asked the next time you start MoSync.



MoSync IDE is now loading, just wait for it to finish.



The MoSync IDE is now loaded.



Everytime you start the MoSync IDE it will ask you to register until you have. It won't cost you anything and the benefit of registering is that you will get access to the latest device profile updates. Everytime you start the MoSync IDE and have a working network connection it will also check for updates. This can be disabled when you register. Note that if you disable automatic updates you can miss important updates and fixes. Insert your name and a valid e-mail address, press 'OK' to proceed.



An e-mail with your registration code will be sent directly to the specified address. If you don't recieve the registration e-mail, your e-mail provider's spam filter might have blocked it. If that is the case, just check your spam mail for it.



Copy the Registration Confimation Code from the e-mail and click the 'Update profile database' shown below.



Paste the Registration Confirmation Code into the textbox and click 'OK'.



If you recieve this message it means that you already have the latest profile database.



When you recieve an update you will see this screen. Again, we strongly encourage you to accept all updates since they will provide both updates and fixes.

For now, MoSync support will be provided mainly through the MoSync forums. In the MoSync forums, you'll find the latest announcements regarding MoSync, along with FAQs, and Tutorials to get you started using MoSync. Also, you are able to submit Bug Reports and/or Feature Requests. And, if you write a really cool application in MoSync and would like to share it with the community, check out the Code Swapping section.
MoSync Homepage http://www.mosync.com/
MoSync Forums http://www.mosync.com/forum/

The default way of developing MoSync applications is to use the bundled MoSync IDE. All tutorials and examples can be built using this this. If you prefer other tools while developing we also provide our deprecated tool MoBuild, which exists as both a command-line and graphical tool taking care of all the building and packaging while you can use any text editor you like. There is also the possibility to use Microsoft Visual Studio C++ for building applications, which will be shown in the appendix. It's even possible to install MinGW with 'make' and build your applications from command-line.

MoSync applications are written in ANSI C/C++ to ensure a minimal learning curve for existing developers. To be able to port an application to a wide set of phones MoSync relies on it's specialized MoSync libraries. Since these are not exactly the same as the Standard C/C++ libraries you can't always just use existing C/C++ code in MoSync without porting it. The benefit is that you only has to do this once to be able to run it on almost all mobile phones.

Create a new project

To build a new project you have two options. Choose 'new' and then 'project' from the File menu or you can right-click the 'Project Explorer' and choose 'new' and then 'project'.



Expand the MoSync option. Here we can either import an older MoBuild project or choose to create a new 'MoSync Project'.
Choose the later and press 'Next'.



Choose a name for your project and press 'Next'. In this demonstration we will use the name, 'HelloWorld'.



In the MoSync IDE we provide you with three different project templates.

• MoSync C Project
• These are standard C projects. A main file with stub code will be generated.
• MAUI
• These are Moblet projects using MAUI, MoSync API User Interface, which is the Graphical User Interface used in MoSync. The project files and stub code are generated.
• Moblet
• These are C++ based event-driven applications using the Moblet class. A Moblet project is created with stub code.

In this demonstration we will use the Moblet. Choose that and click 'Finish'.



Your new project should now be created and loaded in the MoSync IDE. It's possible to run this template program by pressing the play button. The program will then be compiled and executed in the MoSync emulator.

Writing your first hello world

Copy and replace this code or add it manually to the moblet.cpp file in the newly created project.

In the constructor of the MyMoblet class the following three lines has been added:

The first line sets the color to white. 0xFFFFFF represents full intensity for red, green and blue. If you're not familiar with this way of representing colors you will find more information about it in the graphics tutorial.
The second line renders the text "Hello World!" to the backbuffer on the coordinates x=0 and y=32. Because it is drawin to a backbuffer the text will not be visible directly.
The third lines renders the contents of the back buffer to the screen. If you forget to add the maUpdateScreen function to your program you will only have a black screen.

In the function keyPressEvent this following two lines has been added:

This function gets notifications when a key has been pressed down. As you can see there is also a skeleton for a function that gets notified when a key is released. This first line checks if the pressed key was MAK_0 which is the 0(zero) button on your phone. If that's correct the second line is executed which exits the Moblet.
Read more about Moblets in the Development models section of this document.

Now press the play button (or ctrl-f11) to save, build and execute the project. If you get errors, please verify that your code looks exactly like the one above here.



Congratulations, you have now compiled and executed your first MoSync program!

MoSync comes with a comprehensive set of device profiles to help developers deploy their applications to the widest possible range of mobile devices. These profiles define the characteristics and capabilities of each individual mobile device and are used during build time to dynamically tailor the application for each device. Each device profile holds device information such as the screen size, memory capacity, and available features, such as Bluetooth



There is three different filter options available.


The first option is Vendor/Device. Here it's possible to choose which vendor and/or devices you want to include or exclude from your profiles.


The second option is Feature/Bug. Here it's possible to include and exclude devices according to the features and bugs that exist on the devices. It's also possible to select device OS's here.


The third option is Device Constant Condition. These are constant values set in all devices. This includes screen sizes and the available heap size of devices.


By adding multiple filter criteria you can select the devices that satisfy the requirements for your application. If you click on one of your selected criteria you can either remove it or edit it with the buttons above it.


It's possible to define a phone as a target phone. This way the emulator will use the profile information which the selected target device has. This is done by double-clicking the device in the device list.


It's also possible to right-click a device in the list and choose it as a target device. Here you can also view the profile information for the device. It's the header file which MoSync will use when it builds the application.


To access device profile definitions in your C/C++ code, write this:

Useful profile definitions include MA_PROF_STRING_VENDOR and MA_PROF_STRING_DEVICE, which are the names of the device and its vendor. For writing vendor- or device-specific code, MA_PROF_VENDOR_* and MA_PROF_DEVICE_* definitions are also available. For example MA_PROF_VENDOR_NOKIA and MA_PROF_DEVICE_6630.
MA_PROF_SUPPORT_JAVAPACKAGE_BLUETOOTH is defined if and only if the device supports Bluetooth.
MA_PROF_CONST_SCREENSIZE_X, MA_PROF_CONST_SCREENSIZE_Y are defined as integers that describe the screen size in pixels. MA_PROF_CONST_BITSPERPIXEL describes the color depth.

By default the automatic build feature of the MoSync IDE is turned off. This feature enables automatical building of the project as soon as a file in the project is saved. If you would want this behaviour you can of course turn it on. The setting is in the Project menu and is called Build Automatically. If you wish to rebuild everything you can select Clean.. in the Project menu.


When Build Automatically is turned off, you will get two ways of building your applications. You can use the Build Project function in the Project menu.


You can also right-click your project in the Project Explorer and choose Build Project. It's also possible to Clean from there now as well. Finally a build is always forced when the play button is press to run the program in the emulator. The left menu is the one with Build Automatically enabled and the right is when it's disabled.

In MoSync you have the possibility to build for multiple devices at once, which we refer to as "finalizing the application". Just click the Finalizer tab, located to the right of the Device Profiles.


When you press the Propagate button a build script is generated based on the devices listed in the Device Profiles tab. The script is editable so you can make changes such as adding and removing devices manually to it.


To build the application just press the Finalize button. Bear in mind that this opeartion can take a lot of time depending on the of devices and the size of your project. A progress bar will indicate the building progress.


The built files are placed in a directory called FinalOutput in your project folder. Each device package will be placed in a directory hierarchy sorted by vendor and model.

It's also possible to directly send an application to a device for testing. This requires that both the computer and the device have bluetooth and that they are enabled. Also make sure that the device is set to be discoverable so that the computer may find it.



Press the 'Select Target Phone' button and make sure that you press the left region of the button, the one with the telephone and the magnifying glass on. Select your device in the 'Select Bluetooth Device' window that pop ups. If no error dialogs is shown the connection was successfull.



After you have connected to a device it will be possible to select that device by clicking the right part of the button, the one with the arrow. This is convinient if you are sending files to more than one device since sending to multiple devices at the same time isn't supported.

When you have a connection with your device you are now able to send you application directly to it. First you must make sure that you have set your device profile to the target device or to a similar device profile to the target device. If you have selected a wrong target profile, your application might not be able to install on the device or have unintended behaviours.



Now you can send the application to your device by pressing the 'Send To Target Device' button. How the actual installation on the device works is platform and device specific. If you are not sure how this is done or where your application is located after installation, consult the user manual for your device.

Introduction

The MoSync C/C++ environment supports several application development models. We call them the "classic procedural", "event driven, object oriented" and "full GUI-based". Which one to choose when developing an application depends both on the type of application and personal preference.

Classic procedural

Using the classic procedural approach means you start out with an empty main function, and implement your own main loop, including all of the event handling.
Advantages

• * Offers full control of the program flow.
• * Provides ultimate flexibility in the design of the application.
• * Supports programming in pure C, without C++.
• * Resembles popular, procedural frameworks.

Disadvantages

• * All the burden of constructing well-behaved, resource efficient applications is on the programmer.
• * Sometimes requires the programmer to reinvent the wheel.
• * Might be unintuitive to people with a OOP background.

When to use

• * Your application requires full control of the program flow and events.
• * You want to implement your own higher-level layer on top.
• * You prefer C over C++.
• * You're porting existing code to MoSync.

Event driven, object oriented

This approach is embodied in the use of the MAUtil::Moblet class. Inheriting it lets you implement functions such as keyPressEvent() instead of explicitly implementing an event loop yourself, while providing TimerListeners and IdleListeners to facilitate execution of code outside of responding to events.
Advantages

• * Takes care of boilerplate event handling correctly.
• * Provides higher-level abstraction of program flow.
• * Produces well-behaved, resource efficient programs by default.
• * Resembles popular, event driven frameworks.

Disadvantages

• * Imposes a predefined application lifecycle model.
• * Migh be awkward for frame-based applications such as games.
• * Requires use of C++.

Use when

• * Most of the time when the GUI based approach below is overkill.

Full GUI based

Using the MAUI library, you gain access to a variety of ready-made widgets such as labels, list boxes, text edit boxes, images and layouts. You add logic by registering different types of listeners with the widgets, thus responding to higher-level events than with Moblets - things like selection changes, slider position changes etc.
Advantages

• * Allows rapid development of GUI applications.
• * Reduces program flow programming to responding to GUI events.

Disadvantages

• * Imposes a predefined UI model.
• * Requries familiarity with the MAUI library.
• * Requires use of C++.

Use when

• * Whenever you're developing a reasonably traditional GUI application.
• * When radically cutting development time outweighs full customizability.

When developing applications with this model, you have full control of - and responsibility for - how the application behaves. Therefore, it is important to understand how to correctly implement a MoSync event loop. There three most important points to consider are:

• * Checking for events often enough. The MoSync event queue is not infinite, so if you don't check often enough you might miss events.
• * Using maWait() rather than busy-waiting, to conserve CPU usage and battery power.
• * Responding to and handling the close event. After a close event is posted, your application will be forcibly terminated within a short period of time. However, your application should voluntarily exit as soon as possible, having saved any important data. Note that after the close event has been posted, no further events will be posted and most syscalls will have no effect. See the syscall reference for further information on this topic.

Example 1. A simple example of a well-behaved application

This example only checks for key presses, but note that results of asynchronous operations are also passed as events and should be handled similarily. See the syscall reference for more information.
Working with connections in classic applications involves responding to events whose type is EVENT_TYPE_CONN. Connection operations are executed asynchronously, and these events are the way in which your application is notified of their progress, results and termination.

Example 2. A simple example of a classic application using connections

The MAUtil::Moblet class takes care of the application main loop for you. All you need to do is subclass it and implement virtual functions to respond to the events.
Example 3. A basic Moblet application

The static function Moblet::run() implements the actual event loop. When it gets events, it distributes them to all registered listeners. The Moblet, being both a KeyListener and a CloseListener, will recieve these event types. It is recommended to handle other event types by letting your moblet inherit the corresponding listener types, such as BluetoothListener and ConnectionListener.
Working with connections in Moblet-based applications invloves using the ConnectionListener interface. You inherit the class and implement the connEvent() function. You can use one listener for several connections, but each connection can only be associated with one listener. Once the events are received, you should process them in the same way as in the classic model.

Example 4. A simple example of a moblet application using connections

MAUI development is based on the Moblet system. So in order to create an application, you first need to make a moblet as in the previous example. The fundamental building block of a MAUI application is called MAUI::Screen. Each screen has their own root widget. Each time show() is called on a screen that screen is shown and all the others are hidden. When a screen is shown, it means that the root widget of that screen is made active. It can often be very useful to group your application into several screens in order to give your program a logical structure. When a screen is shown, key events are sent to that screen only. When a screen is hidden, each widget that belongs to it is disabled. This normally means that any timer events etc. are unregistered.

Example 5. A simple example of a well-behaved application

There is also the possibility to use MoSync with Visual Studio. All functionality concerning building for mobile devices will be lost this way. The gain is that you will be able to use the debugger in visual studio since MoSync, for the time being, lacks a debugger.

Please note that it's only possible to use Visual Studio 2005 for the moment!

The Visual Studio Express Edition 2005 can be downloaded from Microsoft's website without any charge here.
You will also need to download the Windows Platform SDK from here.

Setting up Visual Studio

If you haven't installed Visual Studio 2005 you will need to install it first.
Also check so that you have installed the Platform SDK.



First we need to add the correct search paths to Visual Studio. Choose Options from the Tools menu.



Expand Projects and Solutions and choose VC++ Directories. Add the search path for the MoSync library files as shown.



Choose 'Include Files' and add the path for MoSync include files.

If you use the Visual Studio 2005 Express edition you will need to follow these steps before closing the dialog

To be able to build you will also need to add the following search paths for the Windows Platform SDK:

• To executable files
• • C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Bin

• To include files
• • C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Include

• To library files
• • C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Lib

Now you have added all the correct search paths so that Visual Studio will be able to build your applications.

Close the Options window by pressing the OK button at the bottom.

Now you just have to make one more adjustment before you will be able to create new projects. Inside the directory C:\Program Files\Microsoft Visual Studio 8\VC\VCProjectDefaults you will need to edit the file corewin_express.vsprops.
Locate the following string:
AdditionalDependencies="kernel32.lib"
You will need to change that line to:
AdditionalDependencies="kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib"

More information about this can be found at msdn.microsoft.com, here.

How to configure a MoSync project in Visual C++

Start with a Win32 project.

• In the Application Wizard, in Application Settings, select Empty Project.
• • Add a C/C++ file. This allows you to access C/C++ project properties.

• In Project Properties:
• • Select All Configurations.

• In General:
• • Change Output Directory from $(SolutionDir) to $(ProjectDir).
  • Change Character Set to Not Set.

• In C/C++, General:
• • Set Detect 64-bit Portability Issues to No.
  • Optional but Recommended: Set Treat Warnings As Errors to Yes.

• In Linker, add the libraries needed (mosynclib.lib and MAStd.lib are required) Input:
• • Set Additional Dependencies to mosynclib.lib MAStd.lib MAUtil.lib MAUI.lib

• In Linker, System:
• • Set SubSystem to Windows.

Building and debugging an application

If you build and run your project, the MoSync emulator will start with your project running in it. You will also be able to debug your application using the Visual Studio debugger so you are able to set breakpoints and single step through your code. Note that the program is compiled as pure x86 code, so the execution envionment may be more forgiving to badly behaved code.