Difference between revisions of "Keyboard (Chili Framework)"

From Chilipedia
Jump to: navigation, search
(ReadKey vs. ReadChar)
 
(10 intermediate revisions by 2 users not shown)
Line 1: Line 1:
With <code>Keyboard</code>, you can get the current state of depressed keys, and you can pop key press and release events out of an <code>Event</code> queue contained in <code>Keyboard</code>. You can also turn autorepeat on/off. Whopee. (''Note: the ''<code>kbd</code>'' object lives in ''<code>MainWindow</code>'''s belly.'')
+
With <code>Keyboard</code>, you can get the current state of depressed keys (have a Valium mate), and you can pop key press and release events out of an <code>Event</code> queue contained in <code>Keyboard</code>. You can also turn autorepeat on/off. Whopee. (''Note: the ''<code>kbd</code>'' object lives in ''<code>MainWindow</code>'''s belly.'')
 +
 
 +
== Example of Use ==
 +
<syntaxhighlight lang="cpp" line>
 +
// how to respond to key release event
 +
 
 +
// keep processing events as long as queue contains them
 +
while( !wnd.kbd.KeyIsEmpty() )
 +
{
 +
// get an event from the queue
 +
const Keyboard::Event e = wnd.kbd.ReadKey();
 +
// check if it is a release event
 +
if( e.IsRelease() )
 +
{
 +
// check if the event was for the space key
 +
if( e.GetCode() == VK_SPACE )
 +
{
 +
// respond to space key release event
 +
}
 +
}
 +
}
 +
</syntaxhighlight>
  
 
== Members ==
 
== Members ==
Line 21: Line 42:
 
<code>bool Keyboard::CharIsEmpty() const</code><br />
 
<code>bool Keyboard::CharIsEmpty() const</code><br />
 
Returns <code>true</code> if the character queue is empty.
 
Returns <code>true</code> if the character queue is empty.
 +
 +
=== Buffer Flushing Bullshit ===
 +
<code>void Keyboard::FlushKey()</code><br />
 +
<code>void Keyboard::FlushChar()</code><br />
 +
<code>void Keyboard::Flush()</code><br />
 +
These functions empty the respective queues. Flush() empties both in one fell swoop. It's like taking a pee and a poo at the same time.
 +
 +
=== Autorepeat Bullshit ===
 +
<code>void Keyboard::EnableAutorepeat()</code><br />
 +
<code>void Keyboard::DisableAutorepeat()</code><br />
 +
<code>bool Keyboard::AutorepeatIsEnabled() const</code><br />
 +
If you hhhhhhhhhhhhhhhhhold a key down for a while, it will start machine gunning events and characters into your queues like a motherfucker. You can disable that if it pisses you off.
  
 
== Event ==
 
== Event ==
Line 26: Line 59:
  
 
Key press and release events are held in a queue in <code>Keyboard</code> in the order they occurred. These events are modeled with their own class because they're precious fucking little snowflakes. They store the type of event (press or release) and the [[#Virtual Key Codes|virtual key code]] of the associated key. You pull them out of the buffer with <code>Keyboard::ReadKey()</code>.
 
Key press and release events are held in a queue in <code>Keyboard</code> in the order they occurred. These events are modeled with their own class because they're precious fucking little snowflakes. They store the type of event (press or release) and the [[#Virtual Key Codes|virtual key code]] of the associated key. You pull them out of the buffer with <code>Keyboard::ReadKey()</code>.
 
=== Type ===
 
<code>enum Keyboard::Event::Type</code><br />
 
 
This represents the different types of events that can be recorded. The options are <code>Press</code>, <code>Release</code>, and <code>Invalid</code>.
 
  
 
=== IsPress ===
 
=== IsPress ===
Line 57: Line 85:
 
* <code>VK_SPACE</code>
 
* <code>VK_SPACE</code>
 
* <code>VK_SHIFT</code>
 
* <code>VK_SHIFT</code>
* <code>VK_ENTER</code>
+
* <code>VK_RETURN</code>
 
* <code>VK_ESCAPE</code>
 
* <code>VK_ESCAPE</code>
 +
See the Microsoft [https://msdn.microsoft.com/en-us/library/windows/desktop/dd375731(v=vs.85).aspx documentation] for the full list of virtual key codes defined in the Windows headers.
  
 
=== ReadKey vs. ReadChar ===
 
=== ReadKey vs. ReadChar ===
Line 64: Line 93:
 
# Each key press and release sequence puts two events (press event and release event) into the <code>ReadKey()</code> queue, but the same sequence only puts one <code>char</code> value into the <code>ReadChar()</code> queue.
 
# Each key press and release sequence puts two events (press event and release event) into the <code>ReadKey()</code> queue, but the same sequence only puts one <code>char</code> value into the <code>ReadChar()</code> queue.
 
# The <code>char</code> values read with <code>ReadChar()</code> have the shift modifier applied to them, whereas those read by <code>ReadKey()</code> are just the raw virtual key codes. For example, pressing the 'A' key puts <code>'a'</code> into the <code>ReadChar()</code> queue when the shift key is not pressed and <code>'A'</code> when it is pressed, but the virtual key code in either case is <code>'A'</code> for <code>ReadKey()</code>.
 
# The <code>char</code> values read with <code>ReadChar()</code> have the shift modifier applied to them, whereas those read by <code>ReadKey()</code> are just the raw virtual key codes. For example, pressing the 'A' key puts <code>'a'</code> into the <code>ReadChar()</code> queue when the shift key is not pressed and <code>'A'</code> when it is pressed, but the virtual key code in either case is <code>'A'</code> for <code>ReadKey()</code>.
In general, you should use ReadKey() for controls and ReadChar() for text input.
+
In general, you should use <code>ReadKey()</code> for controlling shit and <code>ReadChar()</code> for text input.
  
 
== See also ==
 
== See also ==
 
* The [[Chili Framework]]
 
* The [[Chili Framework]]

Latest revision as of 12:56, 13 October 2017

With Keyboard, you can get the current state of depressed keys (have a Valium mate), and you can pop key press and release events out of an Event queue contained in Keyboard. You can also turn autorepeat on/off. Whopee. (Note: the kbd object lives in MainWindow's belly.)

Example of Use

// how to respond to key release event

// keep processing events as long as queue contains them
while( !wnd.kbd.KeyIsEmpty() )
{
	// get an event from the queue
	const Keyboard::Event e = wnd.kbd.ReadKey();
	// check if it is a release event
	if( e.IsRelease() )
	{
		// check if the event was for the space key
		if( e.GetCode() == VK_SPACE )
		{
			// respond to space key release event
		}
	}
}

Members

KeyIsPressed

bool Keyboard::KeyIsPressed( unsigned char keycode ) const
Checks to see if a specific key is currently in the pressed state. The function parameter is the virtual key code of the key that you want to check.

ReadKey

Event Keyboard::ReadKey()
Pull a fresh Event object out of the key press/release event queue. Erases an event from the queue and returns a copy if there is a key press event in the queue. Returns an invalid Event object if the queue is empty.

KeyIsEmpty

bool Keyboard::KeyIsEmpty() const
Returns true if the key event queue is empty.

ReadChar

char Keyboard::ReadChar()
Pull a fresh character off of the character queue. Returns a '\0' (null) character if the queue is empty. See also: ReadKey vs. ReadChar.

CharIsEmpty

bool Keyboard::CharIsEmpty() const
Returns true if the character queue is empty.

Buffer Flushing Bullshit

void Keyboard::FlushKey()
void Keyboard::FlushChar()
void Keyboard::Flush()
These functions empty the respective queues. Flush() empties both in one fell swoop. It's like taking a pee and a poo at the same time.

Autorepeat Bullshit

void Keyboard::EnableAutorepeat()
void Keyboard::DisableAutorepeat()
bool Keyboard::AutorepeatIsEnabled() const
If you hhhhhhhhhhhhhhhhhold a key down for a while, it will start machine gunning events and characters into your queues like a motherfucker. You can disable that if it pisses you off.

Event

class Keyboard::Event

Key press and release events are held in a queue in Keyboard in the order they occurred. These events are modeled with their own class because they're precious fucking little snowflakes. They store the type of event (press or release) and the virtual key code of the associated key. You pull them out of the buffer with Keyboard::ReadKey().

IsPress

bool Keyboard::Event::IsPress() const

Returns true if the event is a press event.

IsRelease

bool Keyboard::Event::IsRelease() const

Returns true if the event is a release event.

IsValid

bool Keyboard::Event::IsValid() const

Returns true if the event is a valid event (reading from an empty buffer will return an invalid event object).

GetCode

char Keyboard::Event::GetCode() const

Gets the virtual key code of the key associated with the Event object.

Miscellaneous

Virtual Key Codes

The virtual key code for a standard alphanumeric key is just the char literal (capital if alphabetic), e.g. 'A' or '9'. Virtual key codes for other keys are defined with #define macros included with Windows.h. Some common ones are:

  • VK_SPACE
  • VK_SHIFT
  • VK_RETURN
  • VK_ESCAPE

See the Microsoft documentation for the full list of virtual key codes defined in the Windows headers.

ReadKey vs. ReadChar

There are two main differences between the events read with ReadKey() and the char values read with ReadChar():

  1. Each key press and release sequence puts two events (press event and release event) into the ReadKey() queue, but the same sequence only puts one char value into the ReadChar() queue.
  2. The char values read with ReadChar() have the shift modifier applied to them, whereas those read by ReadKey() are just the raw virtual key codes. For example, pressing the 'A' key puts 'a' into the ReadChar() queue when the shift key is not pressed and 'A' when it is pressed, but the virtual key code in either case is 'A' for ReadKey().

In general, you should use ReadKey() for controlling shit and ReadChar() for text input.

See also