HMOS Lib Porting Guide
HarmonyOS is an operating systems developed by Huawei. It was described as a microkernel-based, distributed, embedded operating system designed to work on devices from IoT and smart home products to wearables, in-car infotainment systems, and mobile devices - including smartphones.
This document will provide a step-by-step guide to develop libraries for Harmony OS, in order to develop the libraries, it is good to have a fair understanding of Android, HarmonyOS or iOS Architecture.
Initial this document gives us a brief introduction about Android and Harmony Architecture and some deep understanding of the related API. Also, it is good to understand the key difference and information which is needed for developing libraries for HarmonyOS.
Now we will start with the Porting Process
- For the Library porting process from Android to HarmonyOS, we need to install the latest DevEco Studio IDE, the latest version of the DevEco Studio can be found here and the Setup process.
- Create a new HarmonyOS project in DevEco Studio as shown below (Image 8).
- Image 8
- Next you will be displayed with a list of available templates, choose "Phone" and in the Template section choose "Empty Feature Ability (Java)" as shown below (Image 9).
- Image 9
- Next you need to configure the Project and make sure you follow the same library name and the package details. In this case we have used "CircleimageView" for demonstration and it would be "de.hdodenhof.circleimageview".
Project name - name of the project - maintained same as android.
Package name - package name - maintained same as android.
Compatible API Version - Select latest SDK.
- Image 10
- Currently we have just created an "Entry" in the DevEco Studio to run the application, but our intention is to create the library so that we can port the android library core functionality here.
- Image 11
- we need to create a library module. Right Click on "Entry" -> New -> Module -> In the pop screen select Device as "Phone" and Template as " HarmonyOS library" as shown below (Image 12).
- Image 12
- Once created with configuration details it looks like the below screenshot (Image 13).
- Image 13
- A library module is created with module level build.gradle. Any external dependencies of this module can be added in this module build.gradle.
- Next, we need to drag drop or add files from original package from Android studio to HarmonyOS as shown below and the file name would be "CircleImageView.java"
- Image 14
- The import statements in original android lib will be showing as error, now replace each of these imports into corresponding hmos imports.
For example :
android.content.Context is mapped to ohos.app.Context
android.graphics.bitmap --> ohos.media.image.PixelMap
android.graphics.Matrix --> ohos.agp.utils.Matrix
- Image 14.1
Further details about each of these classes can be referred from the API docs which has more detailed explanation about the methods available in each of them.
Tools->SDK Manager-> Go to HarmonyOS SDK Location path/java/"version"/docs/default/index.html
- Image 15
- Even after imports are added, there could still be compilation errors as shown below, because we don't have methods like setImageDrawable, setImageBitmap, setImageResource etc. in the Harmony Image class.
- Image 16
- In these cases, we need to find the corresponding mapping method for these functions in Harmony.
setImageBitmap --> setPixelMap
setImageDrawable --> There is no mapping method in Image class, so we can remove the @Override to avoid compilation errors and create custom logic to implement this feature.
We can create custom logic to get pixelmap object from the element object passed in setImageDrawable and call the setPixelmap passing this created pixelMap as argument.
There is no setImageResource(int resId) in harmony, instead we have setPixelmap(int resId) which achieves the same functionality. This can be used instead.
- Image 17
You can find the updated open sourced code here
- You might still find missing methods like "RectF" and RectF '' are not present in harmony. So, in such cases we can create a custom class and extend the Harmony RectF class as shown below (Image 18).
- Image 18
- Image 19
- Image 20
- Some of the classes will be absent in the current version of SDK, in such cases we check if those classes are necessary for the core functionality of the library, if yes, we must check the feasibility of creating a custom class, else we can enhance this in the upcoming sdk versions.
Example: Outline, ViewOutlineProvider
- In Android, for custom Imageviews
onDraw()is called from the framework side whenever view is drawn or
invalidate()is called. For harmony, to get this callback from f/w we need to implement Component.DrawTask and use
addDrawtask(Component.DrawTask task). This will call onDraw(Component component, Canvas canvas) whenever a component is updated through a draw task.
- Image 21
- Instead of typing Array in android, we use AttrSet in harmony to access the custom attributes that we set in xml file.
- Image 22
- In android, bitmap is created using
Bitmap.createBimappassing in the drawable height , width, and Bitmap Config as arguments. In Harmony, we have
PixelMap.InitializationOptions, into which we fill in the size of the element and pixel format and then create pixelMap using
PixelMap.createpassing the initializationOptions as argument.
- Image 23
- Now you should find all the errors disappeared and no more squiggly red lines in the code.
- Once this is completed, we need to "build", you can build this using the "Build" option from the Menu option and "Build HAP".
- Check if the build is successful and this progress would be displayed in the "Terminal" window of your IDE.