Best Practices EMDVBoard.NET 2006

Transkript

1 emd emd software inc. Best Practices EMDVBoard.NET 2006

2 emd software inc. Page 2 of 12 Table of Contents 1. Overview Use a built-in dialog or create your own Control Sizing Repeat Delay Password Character Transparency and Positioning Caps Lock Advanced Event Handling within a Multithreaded Application Language Property vs. Windows Keyboard Layout Windows Keyboard Layout Language Property of EMDStandard Keyset Different Applications Sending/Receiving Keystrokes Same Application Sending/Receiving Keystrokes... 11

3 emd software inc. Page 3 of Overview Computer kiosks with touch screen technology are appearing in more and more places everyday. Airports, hotels, machinery on the plant floor, even the local grocery store. And although these systems are designed to be used without a physical keyboard, sometimes you still need to be able to type in a number or as string. Creating a keyboard or number pad using individual controls or control arrays can be tedious work. We built the VBoard.NET controls to simplify this task and allow the programmer to get back to the core functionality of his/her application. 2. Use a built-in dialog or create your own The keyset controls allow you drop a keyboard directly on a windows form. The Dialog control gives you the ability to Pop-Up predefined dialogs to get new data from the user, one value at a time. In general the 2 types of controls provided support both edit in place data entry as well as pop-up style data entry. One neat feature of the keyset controls is the ability to send keystrokes directly to the control that has focus. So if I have a windows form with several textboxes and a Standard keyset control with the SendKeysEnabled property set to true, any keystrokes you make on the standard keyset control will automatically be sent directly to the textbox that has focus. Also, the tab key on the control will cycle through the various fields, and all of this happens with no code in your application. By using the Dialog control instead of placing the keyboard directly on the screen, I use less screen real-estate because the keyboard is only displayed when I need to enter a new value. But, I will need to write a small amount of code to make this work, where as no code was needed for the keyset example above. In the click event handler for the textbox, you must place a call to the GetText function of the dialog control. And the result of that function is the new value. For example: Label1.Text = EmdvBoardDlg1.GetText(Label1. Text)

4 emd software inc. Page 4 of 12 If I need to limit the user input to being a number, I can use the GetNumber function, and the dialog control will display a Pop-Up window with a numeric key pad instead of the full alpha numeric keyset. Examples for this can be found in the EMD VBoard 2006 TestApp Sample Project that comes with the install. 3. Control Sizing Because an individual button on the keyboard control really needs to be sized relative to the dimensions of the average person s index finger, we have made the Size property of the control read only, and instead the control is automatically sized based on the value of the ButtonWidth and ButtonHeight Properties. The ButtonWidth and ButtonHeight properties determine the number of pixels in a single button unit. A button unit is the size of the smallest key. Most of the keys are a single button unit with exceptions like the space bar (8 button units wide), the Enter key (2 button units wide), the Ctrl Key (2 button units wide), Alt Key (1.5 button units wide) and some others. A standard size button on most physical keyboard is about 3/4 of an Inch for both height and width. The optimum ButtonWidth and ButtonHeight, in pixels, depends on several factors like the size of the monitor, its resolution, and the aspect ratio. As a starting point we usually use the following. ButtonWidth = Screen Width / 20 ButtonHeight = Screen Height / 15 Screen Resolution ButtonWidth ButtonHeight 800 x /20 = /15 = x /20 = /15 = x /20 = /15 = x /20 = /15 = x /20 = /15 = Repeat Delay If you look at keyboard properties in the control panel you will see that the operating system has a long and a short repeat delay. If you press a key on the keyboard and hold it down, that key will be repeated. The long repeat delay is the delay before the key is repeated the first time. Once the key has been repeated once, the system uses the short repeat delay for consecutive repeats. The longer delay for the first repeat helps people who type slowly to not have unintended repeats. The short delay makes it much faster when you want to type a whole series of the same character. In the VBoard.NET controls the repeat rates are controlled by the LongRepeatDelay and ShortRepeatDelay properties. LongRepeatDelay is the time elapsed before the first time the character is repeated. ShortRepeatDelay is the time interval at which it is repeated every time after that.

5 emd software inc. Page 5 of 12 The default values are 500ms for the LongRepeatDelay and 50ms for the ShortRepeatDelay. There may be times when you want to disable the repeat behavior. Setting these properties to 0 will disable the repeat; when disabled the character will be sent to the display only once. The Repeat Delays can be set to any large number but it is not recommended to set it higher than 2000ms. 5. Password Character EMDVBoardDlg has a PasswordChar property. When this property is assigned a value, any key pressed will show up as the character assigned to the PasswordChar property. But this is applicable only to the Number Pad and the Text Pad (when multi-line is false). This is particularly useful when using the dialogs for entering a password or a pin. To return the Vboard dialog control to normal operation delete any value entered in the PasswordChar property. 6. Transparency and Positioning The dialogs can be made semi-transparent by setting the Opacity property of the EMDVBoardDlg. The opacity property set to 10 makes the dialog almost invisible and a value of 100 makes it appear as normal. With the GetText, GetNumber or GetCalculated methods, a location for the dialog can be specified. When this is used in conjunction with the Opacity Property, it provides a data entry dialog that allows the user to still see the entire screen through the dialog.

6 emd software inc. Page 6 of 12 For example to position a semitransparent text entry dialog over a TextBox, simply set the Opacity property and then call the GetText method using the following values: Position and Transparency Example Code (Visual Basic 2005) EMDVboardDlg.Opacity = 80 MyTextBox.Text = EMDVBoardDlg.GetText(MyTextBox.Text, _ MyTextBox.PointToScreen(New Point(0, 0)), _ MyTextBox.Size) 7. Caps Lock When an application using the EMDStandard control is used with a physical keyboard, please make sure that the Caps Lock on the physical keyboard is not on. If it is on, the operating system will invert the send key value of the key pressed on the EMDStandard control. That is when c (lower case) is pressed on the EMDStandard control with Caps Lock pressed on the physical keyboard; the character that is displayed will be C (Upper Case). 8. Advanced Event Handling within a Multithreaded Application.NET enables easy multithreaded development and because of this the developer can run into some difficulty accessing components from a different thread. Here s how we recommend you to handle that. Events raised by EMDVBoard 2006 controls may occur on a different thread than the one that created the control. When a thread other than the creating thread of a control tries to access one of that control s methods or properties, it may lead to undesirable results. So if you would like to access properties or methods of any other control (like textbox.appendtext) on the form, use of delegates is the preferred method. You could set the Control.CheckForIllegalCrossThreadCalls to false on the load of the form but that is not recommended. Event Handling Example The event handler for the KeyDown needs to be processed on the same thread as the component(s) you wish to access, the example code below demonstrates this.

7 emd software inc. Page 7 of 12 Code (Visual Basic 2005) Private Delegate Sub EMDCalculatorVKeyDownDelegate (ByVal sender As Object, ByVal e As KeyEventArgs) Private Sub EMDCalculator_VkeyDown(ByVal sender As Object, ByVal e As KeyEventArgs) '// Check if call is on the same thread as the one that created the TextBox1. If TextBox1.InvokeRequired Then '// Call not on the same thread as the creating thread. Invoke delegate Dim MyDelegate As New EMDCalculatorVKeyDownDelegate(AddressOf Me.EMDCalculator_VkeyDown) Invoke(MyDelegate, New Object() {sender, e}) Else // User Code directly accessing other control s properties/methods TextBox1.AppendText( ) End If End Sub Controls in Windows Forms are bound to a specific thread and are not thread safe. Therefore, if you are calling a control's method from a different thread, you must use one of the control's invoke methods to marshal the call to the proper thread. The InvokeRequired returns a value indicating whether the caller must call an invoke method when making method calls to the control because the caller is on a different thread than the one the control was created on. If the InvokeRequired returns true then the delegate is invoked else the property can be accessed directly. The EMDCalculatorVKeyDownDelegate is a delegate that represents the method EMDCalculator_VkeyDown with a specific signature and return type. Note that the parameters for the delegate and the method/event are the same. If InvokeRequired is true then the method is invoked by means of an instance of the delegate. Also the parameters {sender, e} need to be included in the Invoke method in the right order. The system will not provide a compile error if it is not included. It is not advisable to open any modal dialogs in the event handlers (this includes a message box) as this takes away the focus from the form that has the control and keys remain pressed till the next key is pressed. 9. Language Property vs. Windows Keyboard Layout When the SendKeysEnabled property is set to true for any EMD VBoard control, the control uses Microsoft s SendKeys method to send keystrokes to the application/control that has focus. If the characters that appear when the keys are pressed are not what you expected then double check the following. The first step is to check if the Caps Lock is on, on the Physical Keyboard as discussed in the earlier section. If it s not being caused by Caps Lock then it is probably a mismatch of the Windows Keyboard Layout and the Language Property on the keyset. The remainder of this section is an attempt to explain and clarify the differences and interactions between

8 emd software inc. Page 8 of 12 the Language property of the keyboard controls, and the Windows operating system settings for Keyboard Layout. 9.1 Windows Keyboard Layout This is a specification of the arrangement of keys on a physical keyboard and the characters produced when those keys are pressed. The operating system has a default Keyboard layout. But this can be changed on an application level. To view the keyboard layout for an application - In Windows XP Right Click on the task bar and select Toolbars Language Bar if it is not already checked. This will show the keyboard layout for the application that has focus. If no application has focus then it will show the default Keyboard Layout. To see a list of all available Keyboard layouts on your PC or to change the default Keyboard Layout, right click on the language bar and select settings.

9 emd software inc. Page 9 of 12 Fig Language bar Settings To change the keyboard layout for a specific application, click on the application to give it focus and then click on the language bar. This brings the list of available layouts that can be chosen from.

10 emd software inc. Page 10 of Language Property of EMDStandard Keyset Just like the keyboard layout, the language property of the EMDStandard keyset determines the physical arrangement of keys on the keyset and the values that are sent when the individual keys are pressed. Changing the language property on the EMDStandard keyset does not change the operating systems keyboard layout and vice versa. Language Property of the EMDStandard Keyset English US French German Spanish Greek Dutch (Netherlands) Dutch (Belgium) Danish Italian English UK Russian Czech Polish Windows Keyboard Layout English (United States) - US French (France) - French German (Germany) - German Spanish (Traditional Sort) - Spanish Greek - Greek Dutch (Netherlands) - US International Dutch (Belgium) Belgian Period Danish - Danish Italian (Italy) - Italian English (United Kingdom) - United Kingdom Russian - Russian Czech - Czech Polish Polish Programmers 9.3 Different Applications Sending/Receiving Keystrokes If the application sending the keystrokes is different from the application receiving the keystrokes, it is advisable to use the EMD on-screen keyboard as the sending application (or refer to it for sample code on how to get it working with the SendInput API call on the VKeyUp and VKeyDown events of the control instead of the SendKeys by setting the SendKeysEnabled property to false. EMD s On-screen keyboard is an application that does not have focus. This enables it to send keystrokes to the application that has focus. The On-screen keyboard application sets the value of SendKeysEnabled to False for all keyset controls and uses the SendInput API call to send key strokes. The SendInput API call

11 emd software inc. Page 11 of 12 uses the keycodes for each key which are different for different Windows Keyboard layouts. So the On-screen keyboard checks the Windows keyboard layout for the application that has focus and sets itself to the same keyboard layout if different before sending keystrokes. If you would like to develop your own version of the On- Screen Keyboard please refer to the code for EMD On-Screen Keyboard application. 9.4 Same Application Sending/Receiving Keystrokes In the table below, the first column lists the keys pressed on the EMDStandard keyset irrespective of the value selected for the language property (if applicable to the language). The other columns show the value displayed on the textbox for the key (when pressed) if the application has that keyboard layout selected. For example when the French Keyboard layout is selected, if % is pressed it shows up as a 5 on the textbox. Key French Keyboard Layout German Keyboard Layout Italian Keyboard Layout Dutch Keyboard Layout Danish Keyboard Layout ^ 6 & & & & & % 5 % % % % % ~ ~ ~ ~ ~ ~ Spanish Keyboard Layout ~ The ones in red are the ones with an issue. an accent indicates that the value for the key appears after the next key is pressed.

12 emd software inc. Page 12 of 12 One of the workarounds would be to ensure that the application always runs with the English Keyboard layout. This can be accomplished with the ActivateKeyboardLayout API call. (Examples can be found in EMD On-Screen Keyboard)