The okKeyPanel component allows keyboard input to be captured and mapped to selected Wire In and Trigger In endpoints.  Multiple okKeyPanels may be instantiated on the same okPanel allowing the same keyboard events to map to different behaviors depending on which okKeyPanel is active.

The okKeyPanel appears on a panel as a simple box with a text label within.  When the mouse is over the component, it changes color to indicate that it is active.  When active, keyboard events are captured and mapped to HDL endpoints according to the XML description.  Three behaviors are available: KeyButton, KeyToggle, and KeyTrigger.

The KeyButton works like a pushbutton.  The Wire In is asserted when the key is pressed and deasserted when the key is released.

The KeyButton is like a toggle button.  On the key downstroke, the Wire In is toggled.  Nothing happens on the upstroke.

The KeyTrigger activates a Trigger In when the keyboard event occurs.  By default, the keyboard event is defined as the key downstroke.  However, with the optional <up/> tag within the XML, the KeyTrigger can map to the upstroke.  By defining both the upstroke and downstroke to the same key, triggers can be sent on each end of a keypress.

The following table describes the nodes of the <key> XML element within the component description.  This mapping is used to associate a keyboard event with an HDL endpoint.

<object class="okKeyPanel">
	<label>Key Panel A</label>
	<color>#b0f0b0</color>
	<position>5,260</position>
	<size>100,55</size>
	<keys>
		<KeyButton keycode="KEY_UP">
			<endpoint>0x00</endpoint><bit>0</bit>
		</KeyButton>
		<KeyToggle keycode="KEY_DOWN">
			<endpoint>0x00</endpoint><bit>1</bit>
		</KeyToggle>
		<KeyTrigger keycode="KEY_A">
			<endpoint>0x40</endpoint><bit>1</bit>
		</KeyTrigger>
		<KeyTrigger keycode="KEY_A">
			<up/>
			<endpoint>0x40</endpoint><bit>1</bit>
		</KeyTrigger>
	</keys>
</object>Code language: HTML, XML (xml)

This component supports executing a script function when a key is pressed or released over an active key panel. The event argument of the script callback provides the methods IsKeyDown(), return true if the event corresponds to a key press, and GetKeyCode(), which returns one of KEY_XXX symbolic constants listed in the section “Available Keycodes” above.

As with all the other “input” components, a key panel may combine KeyButton, KeyToggle or KeyTrigger elements with functionname and, if both are used, the script function will be called first and then, if it doesn’t call event:PreventDefault(), the default action will take place.

Here is a simple example of a key panel using only the script function:

Lua:

function OnKey(keyPanel, event)
	if event:GetKeyCode() == OpalKellyUI.KEY_UP then
		local status = okUI:FindPanel("panel1"):FindControl("status")
		if event:IsKeyDown() then
			status:SetLabel("UP pressed")
		else
			status:SetLabel("UP released")
		end
	end

	if event:GetKeyCode() == OpalKellyUI.KEY_DOWN and not event:IsKeyDown() then
		okUI:MessageBox("DOWN released")
	end

	event:PreventDefault()
endCode language: JavaScript (javascript)

All XML components that support Lua scripting also inherit from the Control class. Please refer to the FrontPanel Scripting documentation for more information on this class.