Creating a menu for the native DR-menu is very easy. The code in hello-world is using the helper functions in ipc.c, which I would also advice to use. The process of making menu-groups and items is split in two part in hello-world, this to allow easy internationalisation of the menu. In the first pass, menu_init(), the menu is created and every item gets its name and icon. In the second pass menu_set_text(), the 'correct' labels will be set. The 2nd function can now easily be called when the user changes the language to use. (More on internationalisation later.)
In version R1.5 the firmware had a problem with adding icons, only the icons available in the system could be used. In R1.6 it is allowed to use a full path.
You have to make sure that the correct bitmaps for your menu and the toolbar are available. You need up to 6 bitmaps:
- the orginal bitmap, lets call it icon.png
- a 'bold' version if you want to support state for the menu item (i.e. does it represent something that can be on and off). The icon should be called icon_selected.png.
- a grayed-out value of the icon, if you want to be able to disable the menu. This icon should be called icon_disabled.png.
And three icons for the toolbar called:
- toolbar_icon.png
- toobar_icon_selected.png and
- toolbar_icon_disabled.png.
When creating the menu, you only give the path and name for the first bitmap, the other names will be created by the firmware when needed.
Tuesday, August 4, 2009
Sunday, August 2, 2009
DBUS
As explained in section 5.1.1 of the iOn development document, the DBUS is the mechanism for inter process communication. Most system components are implemented as seperate programs. When you do a ps, you will see among others
sysd : The system deamon
/usr/bin/popupmenu : the popup menu shown when pressing the menu-button
/usr/bin/uds : the universal document viewer
/usr/bin/ctb : the content browser, basically, this is that application that allows you to browse thru the content of the SD-card.
To show our own icon in the TaskManager or to show our own menu we need to communicate with the popupmenu application via the DBUS.
Take a look at the ipc.c source-file from hello-world, which has all the functions you need to communicate with the 'out-side' world. Most of the available functions are explained in the iOn Development document, chapter 8.
In ipc.c @ 71 DBUS_APPL_NAME is defined as "helloworld" when using the file for your own application, you should give this another name. At line 76-80 you see that every 'system'-application has its own name.
A structure is defined at line 138 indicating the messages to which the hello-world application will react. The first parameter is the name of the (local) function that is called when the event occurs, the second is the name of the event and the third is the application that sends the event (which is not always needed). Different system components will broadcast these messages. The list makes a difference between message handlers and signal handlers, to me it is not completely clear what the difference is.
The function at line 169 ipc_set_services() installs the message and signal handlers using the DBUS. From this point onwards the installed call-back functions, as indicated in the structure at line 138, can be called from the system.
The function ipc_sys_startup_complete() at line 244 should be called to show the icon in the TaskManager-row of the Menu.
From line 371 functions to install menus in the popupmenu are implemented. These should be called from the application to install your own menu. The advantage of using this menu, is that its items can also be dragged to the toolbar and are thus quickly available when running an application. When installing a menu, one should also install a message handler for the "menuItemActivated" message, that will be send by the popupmenu-application.
sysd : The system deamon
/usr/bin/popupmenu : the popup menu shown when pressing the menu-button
/usr/bin/uds : the universal document viewer
/usr/bin/ctb : the content browser, basically, this is that application that allows you to browse thru the content of the SD-card.
To show our own icon in the TaskManager or to show our own menu we need to communicate with the popupmenu application via the DBUS.
Take a look at the ipc.c source-file from hello-world, which has all the functions you need to communicate with the 'out-side' world. Most of the available functions are explained in the iOn Development document, chapter 8.
In ipc.c @ 71 DBUS_APPL_NAME is defined as "helloworld" when using the file for your own application, you should give this another name. At line 76-80 you see that every 'system'-application has its own name.
A structure is defined at line 138 indicating the messages to which the hello-world application will react. The first parameter is the name of the (local) function that is called when the event occurs, the second is the name of the event and the third is the application that sends the event (which is not always needed). Different system components will broadcast these messages. The list makes a difference between message handlers and signal handlers, to me it is not completely clear what the difference is.
The function at line 169 ipc_set_services() installs the message and signal handlers using the DBUS. From this point onwards the installed call-back functions, as indicated in the structure at line 138, can be called from the system.
The function ipc_sys_startup_complete() at line 244 should be called to show the icon in the TaskManager-row of the Menu.
From line 371 functions to install menus in the popupmenu are implemented. These should be called from the application to install your own menu. The advantage of using this menu, is that its items can also be dragged to the toolbar and are thus quickly available when running an application. When installing a menu, one should also install a message handler for the "menuItemActivated" message, that will be send by the popupmenu-application.
Initialising the SD-card on the Emulator
You might have noticed that you do not see the 'Documents' folder that you see on your own DR. The Documents-folder is the root of the SD-card, so we need an SD-card for our emulator. Ofcource we will not use a real SD-card. See section 3.5.6 of the iOn development document. From the terminal window that is connected to the emulator create the root of the SD-card: 'mkdir -p /media/mmcblk0p1'.
To copy files to the 'SD-card' of the emulator we can use the scp-command (secure copy).
Here an example from the iOn Development document to copy the hello-world program to the emulator (open another terminal window, not the one that is 'connected' to the emulator):
scp ./src/hello-world root@qemu:/usr/bin
Or to copy the desktop-file to the root of the SD-card
scp ./data/hello-world.desktop root@qemu:/media/mmcblk0p1
The emulator might not immediately show the new file that you copied. If you were already looking at the Documents-folder, go one folder up and back to Documents again, the icon should now show up.
Click on the icon and .... you will get some strange error message...
If you look into the hello-world.desktop file that you just copied, you will notice that there is a problem in the name of the hello-world application. It is called hello_world i.s.o. hello-world. Fix this and copy the file to the emu. (Or fix on the emu, which has vi :-)
When you click now, hello-world should be started again. You will notice also that the Task Manager row in the menu now contains an icon for the hello-world application, which is not there when you started the application 'manually' from the terminal window.
The iOn Development document section 3.5.7 explains some method that would probably also show the icon in the task-manager when started from the terminal window, but for me this did not work as expected.
You can now download the content of an 'empty' SD-card from the iRex site and copy it to the SD-card of the emulator. To copy complete directories use the -r option:
scp -r anyFolder root@qemu:/media/mmcblk0p1/anyFolder
To copy files to the 'SD-card' of the emulator we can use the scp-command (secure copy).
Here an example from the iOn Development document to copy the hello-world program to the emulator (open another terminal window, not the one that is 'connected' to the emulator):
scp ./src/hello-world root@qemu:/usr/bin
Or to copy the desktop-file to the root of the SD-card
scp ./data/hello-world.desktop root@qemu:/media/mmcblk0p1
The emulator might not immediately show the new file that you copied. If you were already looking at the Documents-folder, go one folder up and back to Documents again, the icon should now show up.
Click on the icon and .... you will get some strange error message...
If you look into the hello-world.desktop file that you just copied, you will notice that there is a problem in the name of the hello-world application. It is called hello_world i.s.o. hello-world. Fix this and copy the file to the emu. (Or fix on the emu, which has vi :-)
When you click now, hello-world should be started again. You will notice also that the Task Manager row in the menu now contains an icon for the hello-world application, which is not there when you started the application 'manually' from the terminal window.
The iOn Development document section 3.5.7 explains some method that would probably also show the icon in the task-manager when started from the terminal window, but for me this did not work as expected.
You can now download the content of an 'empty' SD-card from the iRex site and copy it to the SD-card of the emulator. To copy complete directories use the -r option:
scp -r anyFolder root@qemu:/media/mmcblk0p1/anyFolder
Hello World
The hello-world from R1.6 has some problems, so I will use the version from R1.5, which is not that much different from R1.6.
You can find the example program hello-world here. Unzip it somewere and double-click the hello-world.anjuta icon, Anjuta will be started and at the left-side show the files from hello-world. The first thing to do now is to enable the Poky Plug-in, see also section 3.3.2 of the 'iOn Development Environment'-document which explains nicely how to do this. You will now have an extra Tools-menu. If you have not yet configured the Poky Anjuta PlugIn, follow the instructions from the iRex document.
The steps to follow after starting a Anjuta project are always the same:
1) Choose Builds->Autogenerate to update the makefiles
2) Choose Builds->Configure to update the configure file. As a parameter use --prefix=/usr. This will put the generated program and its data in /usr/bin and /usr/share.
Watch for the 'Completed Sucessfully'.
3) Choose Build->Build Project to generate the applciation and the resources it needs.
4) Start the emulator using Tools->Start QEMU. (This will take some time and ask you for the su password.)
5) Deploy to target: Tools->Deploy, this will prepare everything and copy it to the emulator into the location that was indicated with the Configure call (--prefix=/usr). It will ask you for the qemu-password which is empty.
6) Start a new Terminal window and open a connection with the emulator: 'ssh root@qemu' it will prompt for the password, which is empty.
7) Start the application: In the terminal window first type 'export DISPLAY=:0.0' (0=zero, not so obvious in this font) and then type 'hello-world' it will print a lot of logging in the terminal window and start the hello-world application in the emulator.
The procedure explained in the iRex develoment document, using Tool->Debug Remote, did not work well for me, so you will have to experiment yourself with that.
The application does not do that much (at least not that you can see). You can select 'Close Application' from the menu to close the application. That's that, first application build, downloaded and started on the emulator.
You can find the example program hello-world here. Unzip it somewere and double-click the hello-world.anjuta icon, Anjuta will be started and at the left-side show the files from hello-world. The first thing to do now is to enable the Poky Plug-in, see also section 3.3.2 of the 'iOn Development Environment'-document which explains nicely how to do this. You will now have an extra Tools-menu. If you have not yet configured the Poky Anjuta PlugIn, follow the instructions from the iRex document.
The steps to follow after starting a Anjuta project are always the same:
1) Choose Builds->Autogenerate to update the makefiles
2) Choose Builds->Configure to update the configure file. As a parameter use --prefix=/usr. This will put the generated program and its data in /usr/bin and /usr/share.
Watch for the 'Completed Sucessfully'.
3) Choose Build->Build Project to generate the applciation and the resources it needs.
4) Start the emulator using Tools->Start QEMU. (This will take some time and ask you for the su password.)
5) Deploy to target: Tools->Deploy, this will prepare everything and copy it to the emulator into the location that was indicated with the Configure call (--prefix=/usr). It will ask you for the qemu-password which is empty.
6) Start a new Terminal window and open a connection with the emulator: 'ssh root@qemu' it will prompt for the password, which is empty.
7) Start the application: In the terminal window first type 'export DISPLAY=:0.0' (0=zero, not so obvious in this font) and then type 'hello-world' it will print a lot of logging in the terminal window and start the hello-world application in the emulator.
The procedure explained in the iRex develoment document, using Tool->Debug Remote, did not work well for me, so you will have to experiment yourself with that.
The application does not do that much (at least not that you can see). You can select 'Close Application' from the menu to close the application. That's that, first application build, downloaded and started on the emulator.
Getting Started
I did only have limited experience with linux, but that was enough for me to get started. People at MobileReader already made it easy to start developping/porting programs for the DR1000.
- First you will need the correct development environment. Since I wanted to use my 'down-stairs' PC for development I needed the environment to work under windows. Fortunately Adam B. created a VMWare-image that is easy to install and use.
- Next you need to update the VMWare-image with the lastest development tools that are supplied by iRex (The original VMWare image contains the V1.03 tools). On the website of iRex a document explains how to start development for the DR1000.
This document very well explains how to get started. It also explains how to start if you do not want to use the VMWare image, but use a linux installation. (I think it is wise to use the recommended Ubuntu 8.04 and not another/newer version.)
Now it is time to look at HelloWorld...
- First you will need the correct development environment. Since I wanted to use my 'down-stairs' PC for development I needed the environment to work under windows. Fortunately Adam B. created a VMWare-image that is easy to install and use.
- Next you need to update the VMWare-image with the lastest development tools that are supplied by iRex (The original VMWare image contains the V1.03 tools). On the website of iRex a document explains how to start development for the DR1000.
This document very well explains how to get started. It also explains how to start if you do not want to use the VMWare image, but use a linux installation. (I think it is wise to use the recommended Ubuntu 8.04 and not another/newer version.)
Now it is time to look at HelloWorld...
First Post
In my spare time I am porting and developing applications for the iRex DR1000s EBook reader. In this blog I want to log my experience so others can benifit from it. I also want to use the blog to get feedback on my current project and get ideas for new projects. I will keep posting my applications to the MobileReader forum, here I will tell my progress and problems.
My main projects are:
- mxSudoku, which is based on gtk-sudoku (the sudoku generator and solver is from that project) but its user-interface is completely new (based on the helloworld example of iRex).
- xournal, which was originally ported to the DR1000 by UtterInanity. I added the task-manager icon, 'native-menu' and 'quick-scribbling' support.
- leafpad, to which I added the task-manager icon and enabled the use of gtk_file_selection to work around the problems of the file_chooser.
In other posts I will come back on the term used above and explain what/how I did it.
PS: My native language is not English, so forgive me if I use strange words or constructs.
My main projects are:
- mxSudoku, which is based on gtk-sudoku (the sudoku generator and solver is from that project) but its user-interface is completely new (based on the helloworld example of iRex).
- xournal, which was originally ported to the DR1000 by UtterInanity. I added the task-manager icon, 'native-menu' and 'quick-scribbling' support.
- leafpad, to which I added the task-manager icon and enabled the use of gtk_file_selection to work around the problems of the file_chooser.
In other posts I will come back on the term used above and explain what/how I did it.
PS: My native language is not English, so forgive me if I use strange words or constructs.
Subscribe to:
Posts (Atom)