Custom Drawn Interface/Android: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		(Android only)
2	2
3	3		> Warning: THIS INFORMATION IS DATED AND NEEDS UPDATING
4	4
5	5		Go back to [[Custom Drawn Interface]]
6	6
7	7		## Architecture
8	8
9	9		LCL-CustomDrawn-Android utilizes a minimal Java application which communicates with our Pascal library and sends all events to it and also obeys commands from it. The communication is done via JNI as supported by Google. The controls are not native, instead they are all drawing using TRawImage+TLazIntfImage+TLazCanvas and events and the painting are clipped using LazRegions. The drawing itself is done in Pascal using jnigraphics to draw on a Bitmap Java object which is then drawn by the minimal Java activity on a SurfaceView.
10	10
11	11		Our previous and short-lived attempt to write an LCL Interface for Android (LCL-Android) utilized a non-standard method of using native executables which communicated with a Java machine via Pipes. This method was abandoned because it was considered unsupported by Google. It is considered obsolete and people should use LCL-CustomDrawn-Android instead. This older interface was documented in [[Android Interface]].
12	12
13	13		## Roadmap
14	14
15	15		Part 1, until March 2012:
16	16
17		-	~~1. <s>Build the set of [[Lazarus Custom Drawn Controls]]</s>~~
18		-	~~2. <s>Initial bindings for the Android APIs</s>~~
19		-	~~3. <s>Create an application to automatically generate the bindings</s>~~
20		-	~~4. <s>Start the new widgetset</s>~~
21		-	~~5. <s>Implement support for JNI</s>~~
22		-	~~6. <s>Merge the Lazarus Custom Drawn Controls into the LCL and use them to implement all basic controls</s>~~
23		-	~~7. <s>Add text support for Android</s>~~
24		-	~~8. <s>Implement basic window client area scrolling</s>~~
	17	+	1. Build the set of [[Lazarus Custom Drawn Controls]]
	18	+	2. Initial bindings for the Android APIs
	19	+	3. Create an application to automatically generate the bindings
	20	+	4. Start the new widgetset
	21	+	5. Implement support for JNI
	22	+	6. Merge the Lazarus Custom Drawn Controls into the LCL and use them to implement all basic controls
	23	+	7. Add text support for Android
	24	+	8. Implement basic window client area scrolling
25	25		9. Add mobile emulator for desktop platforms
26	26		10. Improve the mobile scrolling
27		-	~~11. <s>Add text support in X11</s>~~
28		-	~~12. <s>Add DPI awareness and adaptation in the LCL</s>~~
29		-	~~13. <s>Add non-native text support via pasfreetype</s>~~
	27	+	11. Add text support in X11
	28	+	12. Add DPI awareness and adaptation in the LCL
	29	+	13. Add non-native text support via pasfreetype
30	30
31	31		Part 2: April, May, June 2012:
32	32
33		-	~~1. <s>TButton improve the Android visual</s>~~
	33	+	1. TButton improve the Android visual
34	34		2. TBitBtn
35		-	~~3. <s>TRadioButton finish the native look</s>~~
	35	+	3. TRadioButton finish the native look
36	36		4. Calendar dialog -\> Problematic as the LCL has no calendar dialog, it just opens a normal form and puts a calendar on it, so we need a TCDCalendar widget
37	37		5. MaskEdit
38		-	~~6. <s>Improve TComboBox</s>~~
	38	+	6. Improve TComboBox
39	39		7. TMemo
40	40		8. TListView as a list with columns
41		-	~~9. <s>TMainMenu</s>~~
	41	+	9. TMainMenu
42	42		10. Database with sqlite
43	43		11. Barcode reading
44	44		12. Windows add-on installer
45	45
46	46		## Using the Android SDK, Emulator and Phones
47	47
48	48		[[Custom Drawn Interface/Using the Android SDK, Emulator and Phones]]
49	49
50	50		## Android Programming
51	51
52	52		See [[Android Programming]], also includes caracteristics of the various phones relevant for programming.
53	53
54	54		## Configuring the Free Pascal Compiler for Android
55	55
56	56		\| NOTE: \|
57	57		\|----\|
58	58		\| The cross-compiler instructions below are probably obsolete, since support for the [[Android\|Android target]] is present in the trunk (development) version 2.7.1 of FPC. Here are up to date instructions: [[Android\|building a cross-compiler for Android target]]. \|
59	59
60	60		### Use the ready Virtual Box Image with FPC and Lazarus
61	61
62	62		The fastest way to configure Free Pascal and Lazarus for Android development is simply using a pre-configured virtual machine image which already includes Mageia Linux 1, KDE, Lazarus 0.9.31, Subversion, Free Pascal for both x86-linux and arm-linux (targetting Android), the Android SDK, the Android NDK, Java, Ant, Gtk2 and all it's development packages, the GNU debugger (GDB), subversion and everything else necessary for building Android applications with Lazarus.
63	63
64	64		The download like for the virtual machine image is: <https://sourceforge.net/projects/p-tools/files/Lazarus_for_Android_VM_Image/snapshot_30_dez_2011/> (warning: the VirtualBox image was created using the Mac OS X default Zip utility and not all zip applications can handle it. The Mac OS X default zip application can, and [PeaZip](https://peazip.github.io/) too and [WinRAR](http://win-rar.com/download.html) too. Both 7-Zip and the Windows 7 default unzipper fail.
65	65
66	66		The virtual machine image is composed by two files: “Android Devel VM.vbox” and “Android Devel VM.hdd”. Both need to be located in the same folder and also note that the source forge download is a zipped file, so it needs to be unzipped. After unzipping the VM image has 5,2GB. To use this virtual machine one should install Virtual Box and then use it to open the .vbox file. Then one can already use this Linux virtual machine to build Android applications. The process of building an application involves first opening Lazarus and building the application in Lazarus, for example the example project available on ~/Programas/lazarus/example/androidlcl/ and then going into the Linux terminal, navigating to ~/Programas/lazarus/example/androidlcl/android and issuing the command “ant debug” which will generate the APK file in ~/Programas/ lazarus/example/androidlcl/android/bin/LCLExample-debug.apk. There are two users in the virtual machine: “root” and “pascaldev” and both of them use the password “root”.
67	67
68	68		Note that the virtual machine contains the Lazarus source code from when it was created, but one can also use svn update to get the latest code. Note that this involves some risks, however, as the trunk version might ocasionally contain problems.
69	69
70	70		### Building the compiler yourself in Windows
71	71
72	72		Step 1 - Install the Android SDK and NDK
73	73
74	74		Download from Google and install both the SDK and the NDK for Windows.
75	75
76	76		Check your path to the binutils installed by the NDK. For example, for NDK r7 installed in C:\Programas\android-ndk-r7\\ the path is C:\Programas\android-ndk-r7\toolchains\arm-linux-androideabi-4.4.3\prebuilt\windows\bin
77	77
78	78		Also check your path to the libraries installed by the NDK. For example, for NDK r7 installed in C:\Programas\android-ndk-r7\\ the path is C:\Programas\android-ndk-r7\platforms\android-8\arch-arm\usr
79	79
80	80		Step 2 - Download FPC 2.5.1 from January 19th
81	81
82	82		Create a folder to store the FPC trunk source code and checkout revision 16790
83	83
84	84		Or if you want support for database and many other nice fixes use the branch fpc4android from here:
85	85
86	86		svn co <https://p-tools.svn.sourceforge.net/svnroot/p-tools/fpc4android> fpc4android
87	87
88	88		Step 3 - Install FPC 2.4.4
89	89
90	90		An easy way to obtain a good FPC 2.4.4 is installing Lazarus 0.9.30.2. For example, let's say you install this Lazarus version in C:\Programas\lazarusfpc244
91	91
92	92		Step 4 - Create the build script and built it
93	93
94	94		Create the output directory, for example: C:\Programas\fpcandroid\output
95	95
96	96		Next create a file called build.bat in the fpc root folder, in our example C:\Programas\fpcandroid and copy to it:
97	97
98	98		SET PATH=C:\Programas\lazarusfpc244\fpc\2.4.4\bin\i386-win32\
99	99		make crossinstall CPU_TARGET=arm OS_TARGET=linux CROSSBINDIR=C:\Programas\android-ndk-r7\toolchains\arm-linux-androideabi-4.4.3\prebuilt\windows\bin OPT=-dFPC_ARMEL BINUTILSPREFIX=arm-linux-androideabi- INSTALL_PREFIX=C:\Programas\fpcandroid\output
100	100		pause
101	101
102	102		Next run this batch script and you should have FPC installed into C:\Programas\fpcandroid\output
103	103
104	104		Step 5 - Copy some cross-binutils into the bin dir
105	105
106	106		You now should have a FPC binary in C:\Programas\fpcandroid\output\bin\i386-win32
107	107
108	108		Now get these 3 files:
109	109
110	110		C:\Programas\android-ndk-r7\toolchains\arm-linux-androideabi-4.4.3\prebuilt\windows\bin\arm-linux-androideabi-as.exe C:\Programas\android-ndk-r7\toolchains\arm-linux-androideabi-4.4.3\prebuilt\windows\bin\arm-linux-androideabi-ld.exe C:\Programas\android-ndk-r7\toolchains\arm-linux-androideabi-4.4.3\prebuilt\windows\bin\arm-linux-androideabi-strip.exe
111	111
112	112		And copy and then rename to have:
113	113
114	114		C:\Programas\fpcandroid\output\bin\i386-win32\arm-linux-as.exe C:\Programas\fpcandroid\output\bin\i386-win32\arm-linux-ld.exe C:\Programas\fpcandroid\output\bin\i386-win32\arm-linux-strip.exe
115	115
116	116		Step 6 - Merge this into a Lazarus FPC setup
117	117
118	118		Let's say you have the following Lazarus C:\Programas\lazarus31 with the following fpc installed inside it: C:\Programas\lazarus31\fpc\2.6.1\bin\i386-win32 and C:\Programas\lazarus31\fpc\2.6.1\units\\
119	119
120	120		Now create a directory C:\Programas\lazarus31\fpc\2.5.1\units\arm-linux and copy C:\Programas\fpcandroid\output\units\arm-linux there
121	121
122	122		Copy all .exe files from C:\Programas\fpcandroid\output\bin\i386-win32\\ into C:\Programas\lazarus31\fpc\2.6.1\bin\i386-win32
123	123
124	124		(! copy the exe-files to FPC 2.6.1 !)
125	125
126	126		Now you can already build the example project androidlcltest.lpi using the Windows-Release build mode
127	127
128	128		### Using the pre-compiled compiler in Windows
129	129
130	130		Step 1 - Download and unzip the pre-compiled compiler
131	131
132	132		The download is available here: <https://sourceforge.net/projects/p-tools/files/Free%20Pascal%20for%20ARM/Windows/>
133	133
134	134		Step 2 - Merge it into the FPC installation
135	135
136	136		Let's say you have the following Lazarus C:\Programas\lazarus31 with the following fpc installed inside it: C:\Programas\lazarus31\fpc\2.6.1\bin\i386-win32 and C:\Programas\lazarus31\fpc\2.6.1\units\\
137	137
138	138		Now create a directory C:\Programas\lazarus31\fpc\2.5.1\units\arm-linx and copy fpc4android_2_5_1_26_mar_2012\units\arm-linux there
139	139
140	140		Copy all .exe files from fpc4android_2_5_1_26_mar_2012\bin\i386-win32\\ into C:\Programas\lazarus31\fpc\2.6.1\bin\i386-win32 (the version here should be of the installed Windows compiler, not the version of the cross-compiler, so might be 2.6.0 or 2.7.1 or something else)
141	141
142	142		Step 3 - Install the Java JDK and the Android SDK and NDK
143	143
144	144		If you haven't done so already, then install the Java JDK and the Android SDK and NDK. I recommend the JDK 6 (JDK 7 doesnt work!), latest SDK and the NDK version 7. The Windows NDK 7b has a serious bug: [1](https://groups.google.com/group/android-ndk/browse_thread/thread/d8c88bd58ad6df87/5396d1223f0c65b1?hl=pl&lnk=gst&q=Felipe+Monteiro+de+Carvalho#5396d1223f0c65b1) Some people also report that 7c works fine, and I tested that 8c works fine.
145	145
146	146		- Java JDK (!WARNING! Download JDK version 6! Version 7 does not work!!!): <http://www.oracle.com/technetwork/java/javase/downloads/index.html>
147	147		- Android SDK Download (!WARNING! Instead of clicking in the first download link that you see, go to "Use an existing IDE"!): <http://developer.android.com/sdk/index.html> !WARNING! The SDKs r21 and superior removed the nice apkbuilder.bat script which is utilized in our build system in Windows. If you want to use our Windows build scripts, download the SDK r20 from this link: <http://dl.google.com/android/installer_r20-windows.exe>
148	148		- Android NDK version 7 download link: <http://dl.google.com/android/ndk/android-ndk-r7-windows.zip>
149	149
150	150		Now you can already build the example project androidlcltest.lpi using the Windows-Release build mode and these instructions: [[Custom Drawn Interface/Android\|Custom Drawn Interface/Android#Compiling_the_example_LCL_Android_Application]]
151	151
152	152		### Building the compiler yourself in Linux
153	153
154	154		See [[Setup Cross Compile For ARM]] and make sure to use the option OPT="-dFPC_ARMEL" for building the compiler.
155	155
156	156		### Using the pre-compiled compiler in Linux
157	157
158	158		A pre-compiled compiler is provided for convenience for users. The following steps were tested in Mandriva Linux 2010.0 and 2010.1:
159	159
160	160		Required Environment
161	161
162	162		- The latest stable FPC installed in the system via the RPM / DEB / TAR package
163	163
164	164		Step 1 - Install the cross-binutils
165	165
166	166		For Mandriva Linux the RPM package containing arm-linux-as, arm-linux-ld, etc, which are the cross-binutils can be found here: <http://rpm.pbone.net/index.php3/stat/4/idpl/14252825/dir/mandriva_2010/com/cross-arm-binutils-2.20.51.0.4-2mnb2.i586.rpm.html>
167	167
168	168		Just download the RPM package and install it using:
169	169
170	170		`rpm -ivh cross-arm-binutils-2.20.51.0.4-2mnb2.i586.rpm `
171	171
172	172		In Mandriva Linux 2010.0 the dependencies won't match, as the package is for 2010.1, but one can simply ignore this problem and it works fine using --nodeps:
173	173
174	174		`rpm -ivh --nodeps cross-arm-binutils-2.20.51.0.4-2mnb2.i586.rpm `
175	175
176	176		For other distributions use the corresponding package, or else read the instructions for building the cross-binutils yourself at [[Setup Cross Compile For ARM]]
177	177
178	178		Step 2 - Configure the cross-binutils
179	179
180	180		The assembler needs a parameter to tell it which ARM ABI to use. A choice which works good is EABI-5, which is compatible with all Android devices available as of Jan 2011. To set this, we will rename the original assembler and substitute it with a shell script which passes the desired parameter. These commands will do it:
181	181
182	182		`su`\
183	183		`mv /usr/bin/arm-linux-as /usr/bin/arm-linux-as_org`\
184	184		`gedit /usr/bin/arm-linux-as`
185	185
186	186		Now paste into the editor this code:
187	187
188	188		`#!/bin/sh`\
189	189		`/usr/bin/arm-linux-as_org -meabi=5 $@`
190	190
191	191		And don't forget to then make it executable:
192	192
193	193		`chmod 755 /usr/bin/arm-linux-as`
194	194
195	195		Step 3 - Install the Free Pascal Cross-Compiler
196	196
197	197		At this point the pre-compiled FPC can be download from here: <http://sourceforge.net/projects/p-tools/files/Free%20Pascal%20for%20ARM/>
198	198
199	199		Then use these commands to install the pre-compiled Free Pascal cross-compiler into /usr:
200	200
201	201		`[felipe@localhost Programas]$ ls -l`\
202	202		`total 20664`\
203	203		`-rw-rw-r-- 1 felipe felipe 17098552 2010-10-25 08:17 fpc-2.5.1.arm-linux.tar.gz`\
204	204		`[felipe@localhost Programas]$ su`\
205	205		`Password: `\
206	206		`[root@localhost Programas]# cp fpc-2.5.1.arm-linux.tar.gz /usr/`\
207	207		`[root@localhost Programas]# cd /usr/`\
208	208		`[root@localhost usr]# tar -xvf fpc-2.5.1.arm-linux.tar.gz `\
209	209		`[root@localhost usr]# ln -s /usr/lib/fpc/2.5.1/ppcrossarm /usr/bin/ppcrossarm`
210	210
211	211		Step 4 - Verify if your Cross-Compiler works
212	212
213	213		If you made no errors in the previous steps, it should work, so try to call it like this:
214	214
215	215		`[felipe@localhost Programas]$ /usr/bin/ppcrossarm`
216	216
217	217		If this command works and fpc shows its options, then you configured the cross-compiler correctly, if not, then try to find out if your symbolic link points to a correct location with this command:
218	218
219	219		\[felipe@localhost Programas\]\$ ls -ls /usr/bin/ppc*
220	220
221	221		Now we are ready to compile Android applications using the Lazarus IDE! Configuring the fpc.cfg file isn't necessary, the old compiler will automatically find the new compiler and it's object files.
222	222
223	223		## Install the Java JDK and the Android SDK and NDK
224	224
225	225		If you haven't done so already, then install the Java JDK and the Android SDK and NDK. I recommend the JDK 6 (JDK 7 doesnt work!), latest SDK and the NDK version 7. The Windows NDK 7b has a serious bug: [2](https://groups.google.com/group/android-ndk/browse_thread/thread/d8c88bd58ad6df87/5396d1223f0c65b1?hl=pl&lnk=gst&q=Felipe+Monteiro+de+Carvalho#5396d1223f0c65b1) Some people also report that 7c works fine, and I tested that 8c works fine.
226	226
227	227		- Java JDK (Choose version 6!): <http://www.oracle.com/technetwork/java/javase/downloads/index.html>
228	228		- Android SDK Download (Choose Use an existing IDE!): <http://developer.android.com/sdk/index.html>
229	229		- Android NDK version 7 download link: <http://dl.google.com/android/ndk/android-ndk-r7-windows.zip>
230	230
231	231		Now you can already build the example project androidlcltest.lpi using the Windows-Release build mode and these instructions: [[Custom Drawn Interface/Android\|Custom Drawn Interface/Android#Compiling_the_example_LCL_Android_Application]]
232	232
233	233		## Compiling the example LCL Android Application
234	234
235	235		Step 1 - Download the source code
236	236
237	237		The source code of the example is located inside the Lazarus sources in lazarus/examples/androidlcl/androidlcltest.lpi
238	238
239	239		Step 2 - Make sure you have the Java JDK and the Android SDK and NDK installed
240	240
241	241		Read here: [[Custom Drawn Interface/Android\|Custom_Drawn_Interface/Android#Install_the_Java_JDK_and_the_Android_SDK_and_NDK]]
242	242
243	243		Step 3 - Build the project using the Lazarus IDE
244	244
245	245		Configuring Lazarus itself to use the new compiler should not normally be necessary because fpc should be able to find the symlink created, but if you have trouble in this part you can try to hard code the compiler path to use the new crosscompiler. To hardcode the compiler path in cause of trouble go to the menu "Tools-\>Options" and change the "Compiler Path" to "/usr/bin/ppcrossarm"
246	246
247	247		But it is necessary to configure the LPI file to build the example. Open the Project Options dialog of the androidlcltest.lpi project and go to the section Paths and change the libraries path to reflect the correct paths of where your Android NDK was installed and where your jnigraphics.so, libc.so, etc, libraries are located for your target Android API level. For LCL-CustomDrawn-Android API level 8 is the best choice, because it supports Android 2.2+ like the LCL. The image below shows where to configure this:
248	248
249		-	~~<figure>~~
250		-	~~<img src="Configure_androidlcl_libraries.jpg" title="Configure_androidlcl_libraries.jpg" />~~
251		-	~~<figcaption>Configure_androidlcl_libraries.jpg</figcaption>~~
252		-	~~</figure>~~
	249	+	![](/wiki-images/b/b0/Configure_androidlcl_libraries.jpg)
253	250
254	251		The actual lazarus release contains a error, they create a .so.so - file instead of a .so - file. So you have to change this manually in lazarus.
255	252
256	253		Step 4 - Build the APK
257	254
258	255		If you are using Windows, use these instructions to build the APK: [[Custom Drawn Interface/Android\|Custom Drawn Interface/Android#Step_4_-_Creating_the_APK_package_in_Windows]]
259	256
260	257		If you are using Linux follow these instructions instead: Before going to the command line to build the APK open the file lazarus/examples/androidlcl/android/local.properties and change it to reflect your Android SDK path. The file says you should not modify it, but ignore that and modify it anyway. Here is how the file looks like:
261	258
262	259		# This file is automatically generated by Android Tools.
263	260		# Do not modify this file -- YOUR CHANGES WILL BE ERASED!
264	261		#
265	262		# This file must NOT be checked in Version Control Systems,
266	263		# as it contains information specific to your local configuration.
267	264
268	265		# location of the SDK. This is only used by Ant
269	266		# For customization when using a Version Control System, please read the
270	267		# header note.
271	268		sdk.dir=/home/felipe/Programas/android-sdk-linux
272	269
273	270		After configuring that one, go to the command line and issue these commands:
274	271
275	272		` cd lazarus/examples/androidlcl/android`\
276	273		` ant debug`
277	274
278	275		The APK will be located in lazarus/examples/androidlcl/android/bin
279	276
280	277		Step 5 - Install the APK in your phone and run it
281	278
282	279		You can install via ADB or by copying the file to the sdcard. You should see this:
283	280
284		-	~~<figure>~~
285		-	~~<img src="lcl_android_30_mar.png" title="lcl_android_30_mar.png" />~~
286		-	~~<figcaption>lcl_android_30_mar.png</figcaption>~~
287		-	~~</figure>~~
	281	+	![](/wiki-images/4/4c/Lcl_android_30_mar.png)
288	282
289	283		## How to create an LCL Android Application
290	284
291	285		To create a new LCL-CustomDrawn-Android application simply copy all of the file structure and build and java files from the example project called "androidlcl". This example can be obtained from the Lazarus source tree in lazarus/examples/androidlcl
292	286
293	287		Then you will need to modify the build files to change them to your new project name and your new Java package name.
294	288
295	289		### Step 1 - Creating the LPI
296	290
297	291		You need a separate LPI at the moment for the Android version of the application but all the rest of the code can be shared. Create it using the template for a "Library" and then adapt the code from the example located in the lazarus source code in lazarus/examples/androidlcl
298	292
299	293		You need to adapt the exported JNI method names to your Android Package Name.
300	294
301	295		### Step 2 - Building the library
302	296
303	297		First of all, build the Pascal executable without debug information. This debug information is not so useful in Android and makes the executable much bigger. Open the menu Project-\>Project Options and set the build mode, widgetset, architecture and operating system targets, as shown in these screenshots:
304	298
305		-	~~<figure>~~
306		-	~~<img src="Android_project_options_1.png" title="Android_project_options_1.png" />~~
307		-	~~<figcaption>Android_project_options_1.png</figcaption>~~
308		-	~~</figure>~~
	299	+	![](/wiki-images/6/64/Android_project_options_1.png)
309	300
310		-	~~<figure>~~
311		-	~~<img src="Android_project_options_2.png" title="Android_project_options_2.png" />~~
312		-	~~<figcaption>Android_project_options_2.png</figcaption>~~
313		-	~~</figure>~~
	301	+	![](/wiki-images/f/f7/Android_project_options_2.png)
314	302
315		-	~~<figure>~~
316		-	~~<img src="Android_project_options_3.png" title="Android_project_options_3.png" />~~
317		-	~~<figcaption>Android_project_options_3.png</figcaption>~~
318		-	~~</figure>~~
	303	+	![](/wiki-images/9/9f/Android_project_options_3.png)
319	304
320	305		### Step 3 - Create the Android project structure
321	306
322	307		Besides the LCL project building, such as configuring a proper LPI and having a library main project file, one also needs to add all of the android project structure. Simply copy from the example project in lazarus/examples/androidlcl and adapt it to the new project. Things to change are the path to the SDK, the package name. The package name needs to be updated in the build files, in the directory structure android/src/packagename, in the activity java source code and also in the main library pascal source in the exports section.
323	308
324	309		### Step 4 - Creating the APK package
325	310
326	311		#### Step 4 - Creating the APK package in Linux
327	312
328	313		To create the APK package in Linux simply go to the directory "android" inside the project folder and issue the command "ant debug". The package will be in android/bin/MyProject.apk
329	314
330	315		`cd myproject/android ant debug`
331	316
332	317		Ant and all dependencies must be installed using the package management of your linux distribution.
333	318
334	319		#### Step 4 - Creating the APK package in Windows
335	320
336	321		Pre-requisites:
337	322
338	323		- Java JDK installed: <http://www.oracle.com/technetwork/java/javase/downloads/index.html>
339	324		- Android SDK Installed
340	325
341	326		Instructions:
342	327
343	328		In Windows we provide a APK build system which uses only the tools provided in the Android SDK and therefore does not require ANT.
344	329
345	330		First it is necessary to create a debug key to use. To do this use this script:
346	331
347	332		`lazarus/examples/androidlcl/android/generate_debug_key.bat`
348	333
349	334		which can be copied from the example application to your own project folder.
350	335
351	336		it contains following:
352	337
353	338		`REM Adjust these paths to yours`\
354	339		`SET PATH=C:\Programme\Android\android-sdk\tools;C:\Programme\Android\android-sdk\platform-tools\;C:\Programme\Java\jdk1.6.0_38\bin`\
355	340		`SET APP_NAME=androidlcltest`\
356	341		`SET ANDROID_HOME=C:\Programme\Android\android-sdk`\
357	342		`SET APK_SDK_PLATFORM=C:\Programme\Android\android-sdk\platforms\android-9`\
358	343		`SET APK_PROJECT_PATH=C:\Programme\lazarus\examples\androidlcl\android`\
359		-	\
	344	+
360	345		`mkdir bin`\
361		-	\
	346	+
362	347		`keytool --help`\
363		-	\
	348	+
364	349		`keytool -genkey -v -keystore bin\LCLDebugKey.keystore -alias LCLDebugKey -keyalg RSA -validity 10000`\
365		-	\
	350	+
366	351		`REM call and pause together allow us to see the results in the end`\
367	352		`pause`\
368	353
369	354		You have to fix everything after SET to your own paths. Don't forget adjusting the android version from APK_SDK_PLATFORM!
370	355
371	356		After generating the key, use the other script:
372	357
373	358		`lazarus/examples/androidlcl/android/build_debug_apk.bat`
374	359
375	360		To build the APK file. Also remember to edit this batch file to reflect your paths.
376	361
377	362		This script contains the following:
378	363
379	364		`REM Adjust these paths to yours`\
380	365		`SET PATH=C:\Programme\Android\android-sdk\tools;C:\Programme\Android\android-sdk\platform-tools\;C:\Programme\Java\jdk1.6.0_38\bin`\
381	366		`SET APP_NAME=androidlcltest`\
382	367		`SET ANDROID_HOME=C:\Programme\Android\android-sdk`\
383	368		`SET APK_SDK_PLATFORM=C:\Programme\Android\android-sdk\platforms\android-9`\
384	369		`SET APK_PROJECT_PATH=C:\lazarus\examples\androidlcl\android `\
385		-	\
	370	+
386	371		`REM Create necessary directory Structure`\
387	372		`mkdir bin`\
388	373		`mkdir bin\classes`\
389	374		`mkdir gen`\
390	375		`mkdir gen\com`\
391	376		`mkdir gen\com\pascal`\
392	377		`mkdir gen\com\pascal\lcltest`\
393	378		`mkdir raw`\
394	379		`mkdir raw\lib`\
395	380		`mkdir raw\lib\armeabi`\
396		-	\
	381	+
397	382		`REM Cleanup`\
398	383		`del bin\%APP_NAME%.ap_`\
399	384		`del bin\%APP_NAME%.apk`\
400	385		`del raw\lib\armeabi*.so`\
401		-	\
	386	+
402	387		`REM More directory preparation`\
403	388		`copy libs\armeabi*.so raw\lib\armeabi\ `\
404		-	\
	389	+
405	390		`REM Resource compilation`\
406	391		`call aapt p -v -f -M AndroidManifest.xml -F bin\%APP_NAME%.ap_ -I %APK_SDK_PLATFORM%\android.jar -S res -m -J gen raw`\
407		-	\
	392	+
408	393		`REM Java compiler`\
409	394		`call javac -verbose -classpath %APK_SDK_PLATFORM%\android.jar -d bin\classes src\com\pascal\lcltest\LCLActivity.java`\
410		-	\
	395	+
411	396		`REM DX to convert the java bytecode to dalvik bytecode`\
412	397		`call dx --dex --verbose --output=%APK_PROJECT_PATH%\bin\classes.dex %APK_PROJECT_PATH%\bin\classes `\
413		-	\
	398	+
414	399		`REM It seams that dx calls echo off`\
415	400		`@echo on`\
416	401		`REM Now build the unsigned APK`\
417	402		`del %APK_PROJECT_PATH%\bin\%APP_NAME%-unsigned.apk`\
418	403		`call apkbuilder %APK_PROJECT_PATH%\bin\%APP_NAME%-unsigned.apk -v -u -z %APK_PROJECT_PATH%\bin\%APP_NAME%.ap_ -f %APK_PROJECT_PATH%\bin\classes.dex`\
419		-	\
	404	+
420	405		`REM Generating on the fly a debug key`\
421	406		`rem keytool -genkey -v -keystore bin\LCLDebugKey.keystore -alias LCLDebugKey -keyalg RSA -validity 10000 -dname NAME -storepass senhas -keypass senhas`\
422		-	\
	407	+
423	408		`REM Signing the APK with a debug key`\
424	409		`del bin\%APP_NAME%-unaligned.apk`
425	410
426	411		`REM Change keypass and storepass pw here\| and here\|`\
427	412		`jarsigner -verbose -keystore bin\LCLDebugKey.keystore -keypass senhas -storepass senhas -signedjar bin\%APP_NAME%-unaligned.apk bin\%APP_NAME%-unsigned.apk LCLDebugKey`\
428		-	\
	413	+
429	414		`REM Align the final APK package`\
430	415		`zipalign -v 4 bin\%APP_NAME%-unaligned.apk bin\%APP_NAME%.apk `\
431		-	\
	416	+
432	417		`REM call and pause together allow us to see the results in the end`\
433	418		`pause`
434	419
435	420		Don't forget changing the set-variables in the top AND change the pw (see above where).
436	421
437	422		### Building an LCL Android application with debug info
438	423
439	424		It is useful to add another Android build mode which has debug info. Use all of the same options as shown above, except for the debug information:
440	425
441		-	~~<figure>~~
442		-	~~<img src="Android_project_options_4.png" title="Android_project_options_4.png" />~~
443		-	~~<figcaption>Android_project_options_4.png</figcaption>~~
444		-	~~</figure>~~
	426	+	![](/wiki-images/1/11/Android_project_options_4.png)
445	427
446	428		## Oh no! My LCL Android application doesn't work
447	429
448	430		There are various reasons why the app may not work. The most important thing to do when an app doesn't work is to open the logcat and see what the log says. This can be done by running this command line command:
449	431
450	432		``` bash
451	433		./adb logcat
452	434		```
453	435
454	436		And then test one of the hypotheses in the next subsections.
455	437
456	438		### The Pascal executable was compiled for a wrong architecture, operating system and/or widgetset
457	439
458	440		This is the leading cause of executables not running. Always verify that you compiled the program to the "android" widgetset, "linux" operating system and "arm" architecture. This is done by going into the menu Project-\>Project Options. Then set these in the dialog all options as explained in this section:
459	441
460	442		[[How to build an LCL Android application]]
461	443
462	444		To check if you library is arm-linux or not, execute the following commands:
463	445
464	446		``` bash
465	447		cd libs/armeabi
466	448		ls -l
467	449		file liblclapp.so
468	450		ldd liblclapp.so
469	451		```
470	452
471	453		If it mentions anything like 80386 or gtk, then your program was compiled for linux-x86 and gtk2, not for Android like it should.
472	454
473	455		### My Pascal application crashed. How to get a stacktrace?
474	456
475	457		If a Pascal application crashes you should use the command "adb logcat" to obtain the stack
476	458
477	459		Read also this thread in the Google NDK group about converting addresses to lines: <http://groups.google.com/group/android-ndk/msg/2ed2286e85f4ccdd>?
478	460
479	461		### The indispensable build options
480	462
481	463		- -Xd This build option is indispensable when cross-compiling from x86-linux to Android or else FPC will try to link the application against for example /usr/lib/libc.so instead of the libc.so in the NDK, even if you specify a -Fl library path
482	464		- -CpARMV6 This build option is indispensable because code generated for older ARM versions is unsupported by Android and might crash in some devices. See <http://groups.google.com/group/android-ndk/browse_thread/thread/ba542483f062a828>
483	465		- -dAndroid in the package LCLBase.lpk
484	466		- -Parm -Tlinux for the process and target operating system
485	467		- -Fl should contain the path to the NDK directory with the target link shared object, such as libc.so, liblog.so, libjni.so, etc
486	468
487	469		### Wrong package name
488	470
489	471		If you change the package name of the project, then you need to adapt the main project file to inform the widgetset of the change. In the example project this is done in the main project file, androidlcltest.lpr in this part:
490	472
491	473		CDWidgetset.ActivityClassName := 'com/pascal/lcltest/LCLActivity';
492	474
493	475		If your new package name is com.pascal.myapp, then you should change the command above to this:
494	476
495	477		CDWidgetset.ActivityClassName := 'com/pascal/myapp/LCLActivity';
496	478
497	479		## Free Pascal Bugs on Android Support
498	480
499	481		The following summarizes the state of Android Support in Free Pascal:
500	482
501	483		- The pre-compiled snapshot for x86-linux -\> Android is known to work very well and it was built on 19th January 2011: <https://sourceforge.net/projects/p-tools/files/Free%20Pascal%20for%20ARM/>
502	484		- On February this revision <http://svn.freepascal.org/cgi-bin/viewvc.cgi?view=rev&revision=16981> introduced this bug: <http://mantis.freepascal.org/view.php?id=18833>
503	485		- In the end of 2011 this revision <http://svn.freepascal.org/cgi-bin/viewvc.cgi?view=rev&revision=19036> broke linking Android projects
504	486
505	487		We are in contact with FPC developers to fix the situation as can be seen in: <http://mantis.freepascal.org/view.php?id=20726>
506	488
507	489		### FPC4Android Branches
508	490
509	491		Because of FPC bugs related to Android support I have rolled my own branches.
510	492
511	493		#### FPC4Android 2.5.1
512	494
513	495		FPC4Android 2.5.1 has the following fixes applied to it:
514	496
515	497		<http://bugs.freepascal.org/view.php?id=21208> <http://bugs.freepascal.org/view.php?id=21341> <http://bugs.freepascal.org/view.php?id=19559>
516	498
517	499		And I have created a pre-compiled x86-linux -\> android-arm cross-compiler and hosted it here (it is the -v2 cross-compiler);
518	500
519	501		<https://sourceforge.net/projects/p-tools/files/Free%20Pascal%20for%20ARM/>
520	502
521	503		To download the source execute:
522	504
523	505		`svn co `[`https://p-tools.svn.sourceforge.net/svnroot/p-tools/fpc4android`](https://p-tools.svn.sourceforge.net/svnroot/p-tools/fpc4android)` fpc4android`
524	506
525	507		#### FPC4Android 2.6.1
526	508
527	509		This branch is not finished, it lacks patches to fix Android support, patches are welcome. SVN link:
528	510
529	511		`svn co `[`https://p-tools.svn.sourceforge.net/svnroot/p-tools/fpc4android_2_6`](https://p-tools.svn.sourceforge.net/svnroot/p-tools/fpc4android_2_6)` fpc4android_2_6`
530	512
531	513		## Android SDK and NDK bugs
532	514
533	515		### Android NDK for Windows broken linker
534	516
535	517		The linker in android-ndk-r7b (path C:\Programas\android-ndk-r7\toolchains\arm-linux-androideabi-4.4.3\prebuilt\windows\bin\arm-linux-androideabi-ld.exe) crashes for no reason while linking LCL apps =( The linker from android-ndk-r7 and r5 work correctly.
536	518
537	519		See <http://groups.google.com/group/android-ndk/browse_thread/thread/d8c88bd58ad6df87>
538	520
539	521		### Error while calling DX: Trouble processing: bad class file magic (cafebabe)
540	522
541	523		If while using the build script you get the following errors:
542	524
543	525		D:\djsystem\djpalm\android>call dx --dex --verbose --output=D:\djsystem\djpalm\a
544	526		ndroid\bin\classes.dex D:\djsystem\djpalm\android\bin\classes
545	527		processing D:\djsystem\djpalm\android\bin\classes\.\com\pascal\djpalm\LCLActivit
546	528		y$1.class...
547	529
548	530		trouble processing:
549	531		bad class file magic (cafebabe) or version (0033.0000)
550	532		...while parsing com/pascal/djpalm/LCLActivity$1.class
551	533		...while processing com/pascal/djpalm/LCLActivity$1.class
552	534		processing D:\djsystem\djpalm\android\bin\classes\.\com\pascal\djpalm\LCLActivit
553	535		y$2.class...
554	536
555	537		trouble processing:
556	538		bad class file magic (cafebabe) or version (0033.0000)
557	539		...while parsing com/pascal/djpalm/LCLActivity$2.class
558	540		...while processing com/pascal/djpalm/LCLActivity$2.class
559	541		processing D:\djsystem\djpalm\android\bin\classes\.\com\pascal\djpalm\LCLActivit
560	542		y$3.class...
561	543
562	544		This probably means that you are using JDK 7. Unfortunatelly the current Android SDK r20 is not compatible with JDK 7, only with JDK 5 and 6. Please install JDK 6 and use that instead. See:
563	545
564	546		- <http://stackoverflow.com/questions/8538891/bad-class-file-magic-when-using-dx-bat>
565	547		- <http://www.oracle.com/technetwork/java/javase/downloads/jdk6-downloads-1637591.html>
566	548
567	549		## Development Notes
568	550
569	551		### The mysterious JNI Crash (SIGILL - illegal instruction)
570	552
571	553		See the thread: <http://groups.google.com/group/android-ndk/browse_thread/thread/ba542483f062a828>
572	554
573	555		The problem was that vm^^.GetEnv would crash in HTC Wildfire, Alcatel and in the emulator with SIGILL but not in Xperia Mini, HTC Desire HD, Motorola Atrix and other smartphones.
574	556
575	557		The answer was that one needs to specify -CpARMV6 when building because older instructions might fail in some devices. Also try restarting the emulator or running on a different device.
576	558
577	559		### NDK Libraries available in Android 2.2 (API level 8)
578	560
579	561		LCL-CustomDrawn targets Android 2.2+ and in this API level the following libraries are supported by the NDK:
580	562
581	563		1. libc.so
582	564		2. libdl.so (linker)
583	565		3. OpenGL ES 1
584	566		4. OpenGL ES 2
585	567		5. libjnigraphics.so
586	568		6. liblog.so
587	569		7. libm.so
588	570		8. libz.so
589	571		9. libthread_db.so
590	572		10. libstdc++.so
591	573
592	574		LCL-CustomDrawn-Android uses libjnigraphics.so and liblog.so at the moment.
593	575
594	576		### Native text drawing
595	577
596	578		Native text drawing is a bit convoluted in Android and the documentation is quite bad too. Some gotchas already found:
597	579
598	580		- It draws text starting on a Y coordinate which represents the baseline, which is the bottom of strings like "abc", but not the bottom of strings like "qg". See <http://code.google.com/p/android/issues/detail?id=393>
599	581		- There is no documentation about what the size in Paint.setTextSize represents. Some people say it is pixels, but to me it looks something else because it seams to differ across devices.
600	582
601	583		But there are also good things about it:
602	584
603	585		- It can draw on a transparent bitmap and use alpha transparency to implement anti-aliasing and subpixel rendering. The text gets quite beaultiful.
604	586		- It can draw on the ARGB 32-bits non-premultiplied format which is a pretty good one
605	587
606	588		### Flood of garbage collector messages when the caret is visible
607	589
608	590		Something like this:
609	591
610	592		D/dalvikvm( 6364): GC_EXTERNAL_ALLOC freed 188 objects / 6664 bytes in 94ms
611	593		D/dalvikvm( 6364): GC_EXTERNAL_ALLOC freed 170 objects / 6160 bytes in 78ms
612	594		D/dalvikvm( 6364): GC_EXTERNAL_ALLOC freed 162 objects / 5904 bytes in 82ms
613	595		D/dalvikvm( 6364): GC_EXTERNAL_ALLOC freed 162 objects / 5856 bytes in 78ms
614	596		D/dalvikvm( 6364): GC_EXTERNAL_ALLOC freed 162 objects / 5872 bytes in 80ms
615	597		D/dalvikvm( 2825): GC_EXPLICIT freed 371 objects / 18480 bytes in 91ms
616	598		D/dalvikvm( 6364): GC_EXTERNAL_ALLOC freed 162 objects / 5896 bytes in 78ms
617	599		D/dalvikvm( 6364): GC_EXTERNAL_ALLOC freed 162 objects / 5896 bytes in 78ms
618	600		D/dalvikvm( 6364): GC_EXTERNAL_ALLOC freed 162 objects / 5896 bytes in 81ms
619	601		D/dalvikvm( 6364): GC_EXTERNAL_ALLOC freed 162 objects / 5920 bytes in 78ms
620	602		D/dalvikvm( 6364): GC_EXTERNAL_ALLOC freed 162 objects / 5920 bytes in 83ms
621	603
622	604		In my investigation this happens probably because the TCDEdit will request a full control invalidate on each timer tick, which currently will main a full form invalidate, so the GC needs to collect the bitmaps and other paint objects when painting that often.
623	605
624	606		### Why the caret of a TEdit keeps blinking after clicking on the form
625	607
626	608		When clicking on the form the LCL focus will refuse to move from the Edit to the Form because this behavior seems to be hard coded in the LCL, although maybe we might change this for Android. So even while we set focus into the form, the LCL refuses to do that and keeps its focus in the Edit, thus we have a focus mismatch. This might eventually be fixed in the future.
627	609
628	610		### Android ComboBox
629	611
630	612		For adding Android combobox support a new method was added to LCLIntf along with a global variable to store the callback of this dialog:
631	613
632	614		``` pascal
633	615		var
634	616		OnShowSelectItemDialogResult: TOnShowSelectItemDialogResult;
635	617
636	618		function ShowSelectItemDialog(const AItems: TStrings): Boolean; override;
637	619		```
638	620
639	621		This method will run a native item selection dialog, if the platform has one, or result false without doing anything otherwise.
640	622
641		-	~~<figure>~~
642		-	~~<img src="Android_combobox.png" title="Android_combobox.png" />~~
643		-	~~<figcaption>Android_combobox.png</figcaption>~~
644		-	~~</figure>~~
	623	+	![](/wiki-images/8/82/Android_combobox.png)
645	624
646	625		### Using the Native ListView Dialog
647	626
648	627		To allow the user to select items from a list more easily we offer a routine which launch dialog with the native ListView.
649	628
650	629		``` pascal
651	630		{$ifdef LCLCustomDrawn}
652	631		uses customdrawnint, lclintf;
653	632		{$endif}
654	633
655	634		procedure TForm2.Button3Click(Sender: TObject);
656	635		begin
657	636		{$ifdef LCLCustomDrawn}
658	637		LCLIntf.OnListViewDialogResult := @MyOnListViewDialogResult;
659	638		CDWidgetSet.ShowListViewDialog('Dialog Title',
660	639		['Title1', 'Title2', 'Title3', 'Title4', 'Title5', 'Title6'],
661	640		['Descr1', 'Descr2', 'Descr3', 'Descr4', 'Descr5', 'Descr6']);
662	641		{$endif}
663	642		end;
664	643
665	644		procedure TForm2.MyOnListViewDialogResult(ASelectedItem: Integer);
666	645		begin
667	646		DebugLn(Format('[MyOnListViewDialogResult] ASelectedItem=%d', [ASelectedItem]));
668	647		end;
669	648		```
670	649
671	650		LCLIntf.OnListViewDialogResult will be called with the selected item, with a zero-based index, or -1 if the dialog was cancelled by the user. One way to cancel the dialog is when the user pressed the back button.
672	651
673	652		Note that there are 2 more parameters in the end of this routine with default values, which allow choosing the color for the odd and the other for the even rows. The color is an integer of 32-bits in the ARGB format, don't use TColor here!
674	653
675	654		``` pascal
676	655		procedure TCDWidgetSet.ShowListViewDialog(ATitle: string; ATitles,
677	656		ADescriptions: array of string;
678	657		AColorOddRow: jint = $ff292C29; AColorEvenRow: jint = $ff424542);
679	658		```
680	659
681		-	~~<figure>~~
682		-	~~<img src="Android_ListView.png" title="Android_ListView.png" />~~
683		-	~~<figcaption>Android_ListView.png</figcaption>~~
684		-	~~</figure>~~
	660	+	![](/wiki-images/2/2c/Android_ListView.png)
685	661
686	662		### LazDeviceAPIs
687	663
688	664		See: [[LazDeviceAPIs]]
689	665
690	666		---
691	667		From the Free Pascal wiki, page "Custom Drawn Interface/Android", as it stood on 2021-01-08 after a change by Giorgio Tani, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
692	668		Category: Android
693	669		Category: Custom Drawn

Back to history