This object accepts inputs from touchscreen panels or mice. For each recognized input, the object will generate an roTouchEvent object.
Not all touchscreens are supported, but we are always working to extend driver support. Please see this FAQ for a full list of supported touchscreens, or contact firstname.lastname@example.org if you want to know whether a specific touch-screen model is supported. The roTouchScreen object responds to the clicks of a USB mouse in the same way it responds to touch events on a touchscreen.
To set up touchscreen/mouse interactivity, follow this outline:
- Create an roTouchScreen instance.
SetPort()to specify an roMessagePort instance to receive the roTouchScreen events.
- Define one or more touch regions.
- A touch region may be rectangular or circular.
- When a touch or click occurs anywhere inside the area of a touch region, an event will be sent to the message port.
- If touch regions overlap such that a click or touch hits multiple regions, an event for each affected region will be sent.
- Process the events.
The roTouchScreen object supports rollover regions. Rollovers are based around touch regions. When a rectangular or circular region is added, it defaults to having no rollover. You can use the
EnableRollover() method to add an on and off image for a region. Whenever the mouse cursor is within that region, the on image is displayed. In all other cases, the off image is displayed. This allows buttons to be highlighted as the mouse cursor moves over them.
SetResolution(x As Integer, y As Integer) As Void
AddRectangleRegion(x As Integer, y As Integer, w As Integer, h As Integer, region_id As Integer) As Void
Adds a rectangular touch region to the screen. The region_id is used to associate the touch region with roTouchEvent events and to link the region with rollover images.
AddCircleRegion(x As Integer, y As Integer, radius As Integer, region_id As Integer) As Void
Adds a circular touch region to the screen. The
region_id is used to associate the touch region with roTouchEvent events and to link the region with rollover images.
ClearRegions() As Void
Clears the list of regions added using
AddCircleRegion() so that any contacts in those regions no longer generate events. This call has no effect on the rollover graphics.
GetDeviceName() As String
SetCursorPosition(x As Integer, y As Integer) As Void
SetCursorBitmap(filename As String, x As Integer, y As Integer) As Void
Specifies a BMP or PNG file as the mouse cursor icon. This method also accepts a "hot spot" (i.e. the point within the icon rectangle that will trigger events when the mouse is clicked) as a set of x,y coordinates. The icon can be a rectangle of any width or height. The colors are specified internally in YUV (6-4-4 bits respectively), but pixels in the passed image file can be one of 16 different colors. These colors are 16 bits, with 14 bits of color and 2 bits of alpha. If you use all of the alpha levels on all shades, then you limit the number of available shades to five (five shades at three alpha levels plus one fully transparent color gives 16).
EnableCursor(enable As Boolean) As Void
Displays a cursor on screen if passed True.
EnableRollover(region_id As Integer, on_image As String, off_image As String, cache_image As Boolean, image_player As Object) As Void
Enables a rollover for a touch region. This method accepts the ID of the touch region, as well as two strings specifying the names of the on and off bitmap images, a cache setting, and the image player that draws the rollover. The
cache_image parameter simply tells the script whether to keep the bitmaps loaded in memory or not. This setting uses up memory very quickly, so we recommend that
cache_image normally be set to 0.
SetRollOverOrigin(region_id As Integer, x As Integer, y As Integer) As Void
Changes the origin so that more (or less) of the screen changes when the mouse rolls in and out of the region. This means that bitmaps that are larger than the region can be drawn. The default requirement is that rollover bitmaps be the same size and position as the touch region. Note that the bitmap is square for circular regions. The default origin for circular regions is [x - r], [y – r], where x, y is the center of the circle, and r is the radius.
SetRollOverOrigin()methods have been deprecated. As of OS8, the end points exist but do not perform any function.
EnableRegion(region_id As Integer, enabled As Boolean) As Void
Enables or disables a rollover region. This method accepts the ID of the touch region, as well as a Boolean value (True or False). The rollover regions default to "enabled" when created, but you can set up all of the regions at the start of your script and then enable regions as required.
IsMousePresent() As Boolean
Returns True if a relative pointing device is attached to the player. This does not work for absolute devices like touchscreens.
SetMouseRotation(rotation As Integer) As Boolean
Transforms mouse-movement inputs to account for screen rotation. This method can accept the following integers:
- 0: Inputs are unchanged (i.e. landscape orientation).
- 1, 90: Rotated 90 degrees (i.e. clockwise portrait orientation).
- 2, 180: Rotated 180 degrees.
- 3, 270: Rotated 270 degrees (i.e. counter-clockwise portrait orientation).
EnableSerialTouchscreen(a As Integer) As Boolean
SetSerialTouchscreenConfiguration(a As String) As Boolean
GetDiagnosticInfo() As String
Returns an HTML string with captured information describing hardware that was connected and events that occurred during the calibration process. This method is used by the calibration script to diagnose touchscreen issues.
SetPort(port As roMessagePort)
Posts messages of type roTouchEvent and roTouchCalibrationEvent to the attached message port.
StartCalibration() As Boolean
GetCalibrationStatus() As Integer
GetDiagnosticInfo() As String
ClearStoredCalibration() As Boolean
StartEventLogging() As Boolean
StopEventLogging() As Boolean
ClearEventLogs() As Boolean
SetCalibrationRanges(x-min As Integer, x-max As Integer, y-min As Integer, y-max As Integer) As Boolean
Overrides the screen range values provided by the touchscreen. This method is useful when the entirety of the video output is not being displayed on the touch surface. Practical use of this method usually requires a custom calibration script, appropriate images, and a calibration setting matched to a particular setup.
SetBaudRate(baud_rate As Integer) As Boolean
Sets the baud rate of the device. The supported baud rates are as follows: 50, 75, 110, 134, 150, 200, 300, 600, 1200, 1800, 2400, 4800, 9600, 19200, 38400, 57600, 115200, 230400.
NotUsed1(a As String)
SetMode(a As String) As Boolean
NotUsed2(a As Boolean) As Boolean
This script loops a video and waits for a mouse click or touchscreen input. It outputs the coordinates of the click or touch to the shell if it is located within the defined region.
This script includes mouse support.
This script includes a rollover region and mouse support.