Touch Panel, Introduction

Well, I don't know exactly if you already know how the touchpanel works on the DCULx. The idea is that you can use the existing elements now with the touchpanel without any further work. For example you can simply use the touchpanel to select entries of a menu. Nothing has to be done, simply touch the menu entries.

But as we don't have a special button element, it still requires a few things to built such buttons that are sensitive to touchpanel input. But by using the new FIELDTAB element you can define rectangular regions on the display, that are recognized when you touch them or release them on the touchpanel. Usually you will draw some kind of button with rectangles, texts and/or graphics in each of these regions so that the user will see these regions as buttons.

Example:

So you have to give the upper left corner of the rectangular region and the width and height. By giving the attribute you can tell if the region will be recognized if the touchpanel is pressed or if it is released within this region. If a region is recognized as activated, then it works as if you had pressed a key on a matrix keyboard, so it generates a scan code. (1 to 4 in the example). By using the common features for matrix keys, this input data can be used to switch to other windows, enter data in an edit field, and so on. So by using this FIELDTAB element, you can do everything you can do with a matrix keyboard. The example above divides a 320x240 display into four quadrants. E.g. if you press on the upper right quarter, then key code 2 is generated (on press down), if you press on the lower right quarter of the display, the key code 4 is generated (when the panel is released again).

The first FIELDTAB in the source code is automatically the global FIELDTAB. But you can also "call" a FIELDTAB as an element in a GROUP or WINDOW. Then starting from there the new FIELDTAB is active.

There are a few other commands that are important when using the touchpanel. For example at the beginning the touchpanel must be calibrated once. This draws four marks on the display that have to be touched one after the other. This is required to get a correct mapping between analog input data from the panel and the screen coordinates. Calibrating is started by the commands:

Compilermode: QX<LF>
Terminalmode: <ESC>QX

The difference is that in Terminalmode the values determined during calibration are returned via the serial line. So you can store these values and set them again on the next start without having to do calibration again. The Compilermode variant does not return the values. In the future the DCUL7 will store the calibration data itself in flash memory in this case, but this feature is not yet implemented. So for the moment I recommend the Terminalmode version and storing the data in your application.

Another command may be interesting for you to react on arbitrary touchpanel action. If you switch on the touchpanel reporting by <ESC>QT<n>, every movement on the touchpanel bigger than <n> is reported via serial line. But be aware that this may generate quite a lot of data and the serial line may be a bottleneck then. Only use this if the built-in features (FIELDTAB) don't fit your needs at all.

So here is a summary of commands for touchpanel control.

Touchpanel commands for Compilermode
------------------------------------

"QX<LF>"
Start touchpanel calibration and store values in flash memory.

Touchpanel commands for Terminalmode
------------------------------------

"<ESC>QX"
Start touchpanel calibration. When this is done, the determined parame-
ters are automatically activated and reported as
QN<aV>,<bV>,<aW>,<bW>,<aR>,<bR>,
aV, bV: analog values V' of display vector V = (xmax, 0) - R
aW, bW: analog values W' of display vector W = (0, ymax) - R
aR, bR: analog values R' of reference point R(0, 0)

"<ESC>QP<aV>,<bV>,<aW>,<bW>,<aR>,<bR>,"
Set the analog parameters of vectors V', W' and reference point R'.

"<ESC>QT<thres>,"
Set the threshold value. Only changes bigger than this will be reported
to the user. By setting this threshold to zero, the reporting of values
is completely switched off (default: 0). However when fields or menus are
active in Compilermode, the touchpanel inputs converted to keys may still
be reported, depending on the keyboard settings.

"<ESC>QM<flag>"
Set raw reporting mode:
0 : Touchpanel values are reported converted to display coordinates
-1: Touchpanel values are reported raw (0..1023)

Regards
F&S Support Team

Using the touchpanel in compiler mode requires knowing how the DCU works with a matrix keyboard. So I'll explain shortly how this works and then we'll see how a touchpanel can replace a matrix keyboard.

The DCU is capable of reacting to user input from a keyboard itself, without the need of the main application (on your hardware) to do anything. For example when pressing a key, the DCU can automatically switch to a different window. Or it can move the selection in a menu. Or you can even enter values into an edit field.

You simply create a KEYBOARD element that lists all the meanings of the different keys on your keyboard. For example you can say that the key with scancode 0x12 should act as '4' when doing input into an edit field. Or when the key with scancode 0x25 is pressed, then an ANIMATION is shown. And so on. There is an example on our web site that shows this a little clearer:

<!-- m --><a class="postlink" href="http://www.fs-net.de/Home_Eng/Support_E/Samples/Counter/counter.html">http://www.fs-net.de/Home_Eng/Support_E ... unter.html</a><!-- m -->

Now sometimes the behaviour of keys should change depending on the context you are in. For example think about function keys or softkeys, that have a different meaning in every window. So a single KEYBOARD table is not enough. There are two more features that allow a more dynamic definition of the keys. First, you can define more than one KEYBOARD element and call one of them in a WINDOW. This replaces the current KEYBOARD table and from now on the new table is active. Or you can directly define some keys there, then these keys will be active together with the current keys of the KEYBOARD element but only until another window is called.

The idea is that you define all global keys, that means keys that keep their meaning in different windows, in a KEYBOARD element and all dynamic keys directly in the window itself. So for example if all keys are always the same but you want a special help key that shows help depending on the window you are in at the moment, then you can define this key in every window anew, and all other keys are in a KEYBOARD element.

Or another example: you want the user to enter a number, for example a parameter that you need for your main application. You have to do the following steps:

1. Define a variable that will hold the value 2. Define a text that shows the variable 3. Define a window that shows the text; probably also set EDITMODE in the window appropriately 4. Define a KEYBOARD element that defines the keys KEYNUM0 to KEYNUM9 and KEYENTER, probably also the KEYEDIT key to start editing and KEYLEFT and KEYRIGHT for cursor movement. For example to get the key with scancode 0x12 to be mapped to KEYNUM4, add the following line to the KEYBOARD element:

KEY: 0x12 KEYNUM4

Now when this window is shown and you press the KEYEDIT key, then you can edit the value of the variable by entering the digits 0 to 9 and moving the cursor with the left and right keys. When you're done, you type KEYENTER and the new value is stored in the variable. If you defined the variable with AutoSend: confirm, then you'll automatically get a message sent to your application showing the new value.

Now the touchpanel. The idea is that you define virtual keys on the display and these keys then behave exactly like keys on a matrix keyboard. By using the FIELDTAB element, you can give rectangular regions on the screen and define which (virtual) key scancode this region should create when pressed and/or released.

So when using a touchpanel, you do as if you have a matrix keyboard, but you also have to define the FIELDTAB where your matrix keys are on the display. So let's extend the example of entering the value by using a touchpanel on a virtual keypad. In addition to the 4 steps above (which are still needed), you have to do two more steps:

5. Draw buttons 0 to 9 on the display, also an EDIT and an ENTER key and probably also a left and right arrow. How you draw the button does not matter. You can simply draw a text with a rectangle, or create bitmaps for them, as you like.
6. Define a FIELDTAB that gives every of these buttons a virtual scancode. You should of course use the scancodes of step 4 above. For example if the button '4' is drawn at coordinates 30,70 and is 40 pixels wide and 30 pixels high, and it should create scancode 0x12 when pressed, you add the following line to the FIELDTAB element:

X: 30 Y: 70 WIDTH: 40 HEIGHT: 30 ATTRIB: down KEY: 0x12

That's all.

So how does it work then? Let's do an example: you press the touchpanel on button '4'. The DCU recognizes that you've touched the touchpanel. It converts the analog touchpanel values to display coordinates (this mapping is initialized with the touchpanel calibration) and then checks the current FIELDTAB. It finds that there is a field entry defined for these coordinates and event "down" and takes the corresponding scancode 0x12 from the table entry. Now the DCU does the usual key checking. This means it looks into the current KEYBOARD definitions and finds that this scancode 0x12 is mapped to KEYNUM4. KEYNUM4 means that if the DCU is currently editing a value, it should insert the digit 4 into the value.

So to summarize, when you press somewhere inside of button '4' on the touchpanel, the DCU enters digit 4 into the currently edited value.

Now that's not too difficult, is it?

What remains to be said are two hints that are usually required to fine tune the touchpanel usage. Please make sure you have understood everything up to here before reading on.

First you usually want a visible feedback that you successfully pressed the button on the screen. This is the reason why we allow to define an action for "up" and "down" in a FIELDTAB entry. The idea is to react on "down" and draw the button somehow different like a pressed button. The final action is then executed when the button is released.

So for example when the user is a little off the button to the side, probably the neighbouring button is recognized. Then the user can move the finger while still on the touchpanel towards the correct button and when the correct button is highlighted, he can release the touchpanel and the correct key is executed.

The second hint has exactly to do with this motion while pressing the touchpanel. You should not rely on the fact that you get both, the down *and* the up event on the same field. If the user moves from one button to the next button without releasing the finger from the touchpanel, then you get first the down event for the first button, and then directly the down event for the second button, without getting an up event for the first button between these. You may get an up event for the second button if the user releases the touchpanel there.

But even more. If the user moves his finger outside of any button, you will never see any up event for any key. This makes it very difficult to draw a previously pressed button as unpressed again. And here is where the hint comes: as last entry in the FIELDTAB, define an entry that spans the whole display with event "down". When this event happens, redraw all buttons us "unpressed". Why? When the user moves his finger outside of any normal button, he automatically presses this special full screen button. So this is a good method of recognizing this.

Regards
F&S Support Team