WxAndroid/docs

From WxWiki
Jump to: navigation, search
You can check out status of wxWidgets classes in Android port on this status page.


About

wxWidgets for Android implementation requires use of JNI calls and specific Java classes that ease communication between two languages. Illustrated bellow is currently used design.

WxWidgets for Android design.png

Here it can be seen that java components will use static methods of WXNative when ever needed to update wxWidgets's components, while wxWidgets uses WXCalls to update Java components. Files wrappers.h and native.h located in private directory of include/wx/android contain macros and definitions of functions that are used to communicate with Android.
Further reading:

Here is brief example of two objects communicating:

wxButton * btn = new wxButton(frame, wxID_ANY);

Here, new object wxButton is being constructed with wxFrame instance as his parent. This is all done in traditional wxWidgets way, with all regular constructors and base class initialization. However, once wxWidgets is ready it needs to show new button on screen. To do that object Android's Button object needs to be created and passed to Activity that represents frame.
This is done through WXCall, by wxButton instance executing following code:

CALL_STATIC_VOID("addView", "(IIIIIILjava/lang/String;)V", 
    id, parent->GetId(), size.GetWidth(), size.GetHeight(), pos.x, pos.y, wxAndroid::Env->NewStringUTF(WXBUTTON_C));

WXCalls must ensure that button with given parameters is shown on screen.
CALL_STATIC_VOID is one of many wrappers that are supposed to ease use of WXCalls methods, and is part of "wx/android/private/wrappers.h"

Java classes

Class Description
WXApp
WXCalls
WXFrameActivity
WXLayout
WXNative
WXPair
WXTextWatcher
WXView

Adding new files

Android port of wxWidgets contains both CPP and Java files. Files are located in src/android/jni for CPP and src/android/java for java. Headers required for CPP classes are found in include/wx/android and private android-only private files are found in /private sub-directory.

As with any wxWidgets supported platform, build/bakefiles/files.bkl needs to be updated with new files. After updating bakefiles, its required to update makefiles by running bakefile_gen in bakefiles directory.
After that it is required to run autoconf in main directory where configuration files are located.

Example of files being added to files.bkl, new class is "newclass" and new private file is "newprivate":

<set var="ANDROID_LOWLEVEL_SRC" hints="files">
    ...
    src/android/jni/newfile.cpp
    src/android/jni/newprivate.cpp
    ...
</set>
 
<set var="ANDROID_LOWLEVEL_HDR" hints="files">
    ...
    wx/android/newfile.cpp
    wx/android/private/newprivate.cpp
    ...
</set>

Adding new wxControl

Process of adding new control may vary but there are steps that are required in all cases.
First it is required to find "corresponding" Android Widget class.
For example wxButton's widget class is "android.Widget.Button", you can find all widgets on this link.


Frames/Windows and application life cycle

To understand how wxWidgets behaves on Android, general knowledge of Android's app life cycle is required.
From Android's documentation:
"An activity is a single, focused thing that the user can do. Almost all activities interact with the user, so the Activity class takes care of creating a window for you in which you can place your UI with setContentView(View)."
As such activity in this implementation is used as Window,

TO-DO: EVENTS

Not yet finished:
wxWidgets code is compiled into .so library that must be loaded into java project. Full C++ implementation was/is possible but would require implementing each control and app life cycle on our own.