/*
 POLL.DOX

 License CC0 PUBLIC DOMAIN

 To the extent possible under law, Mark J. Olesen has waived all copyright
 and related or neighboring rights to FDOSTUI Library. This work is published
 from: United States.
*/

/*! \file poll.h
\brief keyboard and mouse polling routines
*/

/*!
\enum poll_event_type
\brief indicator of the type of event that occurred

\var poll_event_type::EVENT_KEY
	key event

\var poll_event_type::EVENT_MOUSE
	mouse event

\var poll_event_type::EVENT_SCREEN_RESIZE
	screen resize event

*/

/*!
\union poll_event_record
\brief continaer to hold an event record

\var poll_event_record::m_key
	key event

\var poll_event_record::m_mouse
	mouse event

\var poll_event_record::m_resize
	resize event

*/


/*!
\struct poll_event
\brief structure to hold event

\var poll_event::m_type
	event type of this record (key, mouse or resize)

\var poll_event::m_record
	event record

*/

/*!
\fn void poll_keyboard_unget(
    struct event_key const*const        i_event)
\brief put back a key event into queue
\param[in] i_event event to place in queue
\returns none

The quueue can only hold one event record.
*/

/*!  
\fn int poll_block(
    struct poll_event *const            o_event)
\brief polls event queue
\param[out] o_event event object
\returns 0 internal error - no event has occurred
\returns !0 event has occurred 

Waits (blocks) in an infinite cycle for a key event to occur.
Once an event has occurred the event is returned.

*/
