Getting Introspective

Getting Introspective

Sitting alone in front of a crackling fire, sipping a glass of cabernet, listening to William Shatner s rendition of Mr. Tambourine Man life, the universe what does it all mean? OK, that s actually not what s being referred to here. Rather, we re going to talk about how your tablet-aware application might find it useful to know more about the hardware environment it s running in perhaps find out how many tablet devices are installed, what their capabilities are, and so on.

This section covers the Platform SDK support to introspect the system, in order to garner all the information you d ever need about the installed tablet devices.

Tablets Collection

We briefly saw earlier that the Tablets class encapsulates the collection of installed tablet devices in the system. The collection s elements are Tablet objects, representing a single installed tablet device. You obtain an instance of Tablets simply by allocating it Tablet PC Platform will automatically fill in the contents.

Besides having the normal collection properties and methods, the Tablets class also has a DefaultTablet property that identifies the primary tablet device installed in the system.

Tablet Class

Tablet devices installed in the system have various attributes, such as a name, a coordinate system, a list of all the packet properties it can report, and other capabilities such as being able to uniquely identify pens.

The Tablet class encapsulates the properties of an installed tablet device. Let s take a look at each of these properties in Table 4-11:

Table 4-11. The Properties of the Tablet Class

Property Name	Type	Description
HardwareCapabilities	TabletHardwareCapabilities	A bitfield of various device capa- bilities, defined in the TabletHardwareCapabilities enumeration
MaximumInputRectangle	System.Drawing.Rectangle	The coordinate space of the entire surface of the tablet device
Name	String	A human-readable form of the tablet s name
PlugAndPlayId	String	The device name reported to the system by the device

The HardwareCapabilities property is a bitfield of values found in the TabletHardwareCapabilities enumeration. The various capabilities of tablet hardware that the Tablet PC Platform currently enumerates are as listed in Table 4-12:

Table 4-12. The Members of the TabletHardwareCapabilities Enumeration

Hardware Capability	Description
CursorMustTouch	The pen must be touching the surface for its position to be sampled.
CursorsHavePhysicalIds	The tablet is able to distinguish between pens used with the device.
HardProximity	The pen s position can be reported while it s in the air but in close proximity to the device.
Integrated	The tablet is integrated with the display.

The Tablet class s IsPacketPropertySupported method is a useful function that tells you whether the tablet supports or provides a given packet property type. We saw use of this function earlier in the PacketPropertyWatcher sample so that the ListBox could be filled up only with packet properties that the default tablet supported.

The GetPropertyMetrics method returns an instance of TabletPropertyMetrics given a packet property GUID. TabletPropertyMetrics is used to provide the units, resolution, and minimum and maximum values of a packet property type. This is useful information if you ever want to parse packet data beyond just X and Y values for example, if you wanted pen pressure or rotation to perform some special behavior, the TabletPropertyMetrics of the packet property should be used so that you know how to interpret those packet data values.

Sample Application: DeviceWalker

This final sample application displays all installed tablet devices, their capabilities, and supported packet properties, as shown in Figure 4-11.

Figure 4-11. The DeviceWalker sample application shows the capabilities of all the tablet devices installed in the system.

DeviceWalker.cs

//////////////////////////////////////////////////////////////////// // // DeviceWalker.cs // // (c) 2002 Microsoft Press // by Rob Jarrett // // This program demonstrates introspection of installed Tablet // devices. // //////////////////////////////////////////////////////////////////// using System; using System.Drawing; using System.Reflection; using System.Windows.Forms; using Microsoft.Ink; public class frmMain : Form { private Label lblTablets; private Label lblLine1; private ComboBox cbTablets; private Label lblExtraInfo; private Label lblHardwareCaps; private Label lblLine2; private ListView lvHardwareCaps; private Label lblPacketProps; private Label lblLine3; private ListView lvPacketProps; private Button btnClose; // Entry point of the program [STAThread] static void Main() { Application.Run(new frmMain()); } // Main form setup public frmMain() { SuspendLayout(); // Create and place all of our controls lblTablets = new Label(); lblTablets.Location = new Point(8, 8); lblTablets.Size = new Size(128, 16); lblTablets.Text = "Installed tablet devices:"; lblLine1 = new Label(); lblLine1.BorderStyle = BorderStyle.Fixed3D; lblLine1.Location = new Point(136, 16); lblLine1.Size = new Size(144, 2); cbTablets = new ComboBox(); cbTablets.DropDownStyle = ComboBoxStyle.DropDownList; cbTablets.Location = new Point(16, 32); cbTablets.Size = new Size(264, 21); cbTablets.SelectedIndexChanged += new System.EventHandler(cbTablets_SelIndexChg); lblExtraInfo = new Label(); lblExtraInfo.Location = new Point(16, 56); lblExtraInfo.Size = new Size(264, 16); lblHardwareCaps = new Label(); lblHardwareCaps.Location = new Point(8, 80); lblHardwareCaps.Size = new Size(120, 16); lblHardwareCaps.Text = "Hardware capabilities:"; lblLine2 = new Label(); lblLine2.BorderStyle = BorderStyle.Fixed3D; lblLine2.Location = new Point(128, 88); lblLine2.Size = new Size(152, 3); lvHardwareCaps = new ListView(); lvHardwareCaps.FullRowSelect = true; lvHardwareCaps.Location = new Point(16, 104); lvHardwareCaps.MultiSelect = false; lvHardwareCaps.Size = new Size(264, 80); lvHardwareCaps.View = View.Details; lblPacketProps = new Label(); lblPacketProps.Location = new Point(8, 200); lblPacketProps.Size = new Size(96, 16); lblPacketProps.Text = "Packet properties:"; lblLine3 = new Label(); lblLine3.BorderStyle = BorderStyle.Fixed3D; lblLine3.Location = new Point(104, 208); lblLine3.Size = new Size(176, 3); lvPacketProps = new ListView(); lvPacketProps.FullRowSelect = true; lvPacketProps.Location = new Point(16, 224); lvPacketProps.MultiSelect = false; lvPacketProps.Size = new Size(264, 97); lvPacketProps.View = View.Details; btnClose = new Button(); btnClose.DialogResult = DialogResult.OK; btnClose.Location = new Point(208, 328); btnClose.Text = "Close"; btnClose.Click += new System.EventHandler(btnClose_Click); // Configure the form itself AcceptButton = btnClose; CancelButton = btnClose; ClientSize = new Size(292, 360); Controls.AddRange(new Control[] { lblTablets, lblLine1, cbTablets, lblExtraInfo, lblHardwareCaps, lblLine2, lvHardwareCaps, lblPacketProps, lblLine3, lvPacketProps, btnClose }); FormBorderStyle = FormBorderStyle.FixedDialog; MaximizeBox = false; Text = "DeviceWalker"; ResumeLayout(false); // Fill the combobox with the currently installed tablet // devices Tablets tablets = new Tablets(); foreach (Tablet t in tablets) { cbTablets.Items.Add(t); } // Trigger a UI update to fill in the rest of the properties cbTablets.SelectedIndex = 0; } // Tablet device combobox selection changed handler private void cbTablets_SelIndexChg(object sender, System.EventArgs e) { // Turn off listview invalidatation for performance lvHardwareCaps.BeginUpdate(); lvPacketProps.BeginUpdate(); // Remove all items from the listviews lvHardwareCaps.Clear(); lvPacketProps.Clear(); // Set up their columns lvHardwareCaps.Columns.Add("Capability", 150, HorizontalAlignment.Left); lvHardwareCaps.Columns.Add("Possessed", 100, HorizontalAlignment.Left); lvPacketProps.Columns.Add("Property", 100, HorizontalAlignment.Left); lvPacketProps.Columns.Add("Supported", 150, HorizontalAlignment.Left); // Get the tablet device to introspect Tablet t = cbTablets.SelectedItem as Tablet; if (t != null) { // Fill in "extra" info about the tablet lblExtraInfo.Text = String.Format(  "PnP ID: {0} InputRect: ({1},{2},{3},{4})", t.PlugAndPlayId, t.MaximumInputRectangle.Left, t.MaximumInputRectangle.Top, t.MaximumInputRectangle.Bottom, t.MaximumInputRectangle.Right); // Fill in hardware capabilities by walking through each // value in the TabletHardwareCapabilities enum and seeing // if the device supports it foreach (TabletHardwareCapabilities c in TabletHardwareCapabilities.GetValues( typeof(TabletHardwareCapabilities))) { ListViewItem item = new ListViewItem(); item.Text = c.ToString(); if ((t.HardwareCapabilities & c) == c) { item.SubItems.Add("Yes"); } else { item.SubItems.Add("No"); } lvHardwareCaps.Items.Add(item); } // Fill in packet properties by walking through each value // in the PacketProperty class and seeing if the device // supports it foreach (FieldInfo f in typeof(PacketProperty).GetFields()) { // We're only interested in static public members of // the class if (f.IsStatic && f.IsPublic) { ListViewItem item = new ListViewItem(); item.Text = f.Name; Guid g = (Guid)f.GetValue(f); if (t.IsPacketPropertySupported(g)) { TabletPropertyMetrics tm = t.GetPropertyMetrics(g); item.SubItems.Add( String.Format(  "Yes: ({0}-{1} {2})", tm.Minimum.ToString(), tm.Maximum.ToString(), tm.Units.ToString())); } else { item.SubItems.Add("No"); } lvPacketProps.Items.Add(item); } } } // Turn on listview invalidation now that we're done lvHardwareCaps.EndUpdate(); lvPacketProps.EndUpdate(); } // Close Button clicked handler private void btnClose_Click(object sender, System.EventArgs e) { Application.Exit(); } }

The cbTablets_SelIndexChg method does the lion s share of the work in this application it fills in the UI with the hardware capabilities and supported packet properties of the currently selected tablet device. Again we take advantage of C# s reflection abilities to enumerate various members of enumerations and classes.

Common Properties on InkCollector and InkOverlay

In an effort to bring together all that we ve learned thus far, we ve put together a mini-review of the InkCollector and InkOverlay classes by listing the commonly used properties, methods, and events in them. Tables 4-13 and 4-14 aren t meant to be an exhaustive reference, merely an effort to summarize the information that has been covered in the chapter.

Table 4-13. InkCollector and InkOverlay Mini-Reference

Property	Type	Description	Input Can Be Enabled
AutoRedraw	Bool (read-write)	Whether to redraw currently captured ink when the host window gets invalidated	Read: Yes Write: Yes
CollectingInk	Bool (read-only)	Reports if the InkCollector is currently collecting an ink stroke	Read: Yes
CollectionMode	CollectionMode (read-write)	Whether the InkCollector should recognize ink gestures	Read: Yes Write: No
DefaultDrawingAttributes	DrawingAttributes (read-write)	Specifies the drawing attributes to be used when creating new ink strokes	Read: Yes Write: Yes
DesiredPacketDescription	Guid[] (read-write)	Specifies which tablet input properties to collect	Read: Yes Write: No
DynamicRendering	Bool (read-write)	Whether in-progress ink strokes should be drawn	Read: Yes Write: Yes
Enabled	Bool (read-write)	Turns tablet input data capture on and off	Read: Yes Write: N/A
Handle	IntPtr32 (read-write)	The InkCollector s host window s handle	Read: Yes Write: No
Ink	Ink (read-write)	The object used to store collected ink strokes	Read: Yes Write: No

Table 4-14. InkOverlay Mini-Reference

Property	Type	Description	Input Can Be Enabled
EditingMode	InkOverlayEditingMode (read-write)	The current editing mode used for interaction	Read: Yes Write: Yes
EraserMode	InkOverlayEraserMode (read-write)	The type of erasing used when in DeleteMode	Read: Yes Write: Yes
EraserWidth	int (read-write)	The eraser width and height for point-level erase	Read: Yes Write: Yes