/*
 WM.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 wm.hpp
\brief window management routines
*/

/*!
\enum wm_error
\brief error codes

\var wm_error::ERROR_NONE
	no error occurred

\var wm_error::ERROR_INIT_SCREEN
	unable to initialize the display

\var wm_error::ERROR_INIT_MOUSE
	unable to initialize the mouse

\var wm_error::ERROR_EMPTY_QUEUE
	the queue is empty (there are no windows to recieve events)

\var wm_error::ERROR_USER_ESC
	the user hit the escape key
*/

/*!
\fn enum wm_error wm_init()
\brief initialize the FDOSTUI subsystem
\returns error code
*/

/*!
\fn void wm_deinit()
\brief return the system to it's initial state
\returns none
*/

/*!
\fn void wm_register_window(
    window*const                        i_window)
\brief add a window to the window manager
\param[in] i_window valid window 
\returns none
*/

/*!  
\fn enum wm_error wm_run()
\brief enter the main loop
\returns error code

A typical scenario is to create a window, register it, and then call
the run loop. Following, wait for an exit code and then terminate.

\code

	enum wm_error error= wm_init();

	if (error)
	{
		printf("Unable to initialize subsystem\n");
		return error;
	}

	window* window= new window(0,0,_video_cols,_video_rows);
	add widgets to window...
	wm_register_window(window);

	error= wm_run();

	wm_deinit();

	return error;

\endcode

*/

/*!
\fn enum event_response wm_run_modal(
    widget&                             i_widget)
\brief runs a widget as modal
\param[in] i_widget widget to run as modal
\returns response

The widget will run in an infinite loop. It will exit if the user hits
the escape key (::RESPONSE_CLOSE) or an event produces a response other 
than ::RESPONSE_NONE or ::RESPONSE_HANDLED.

The code in menu::submenu illustrates the use of how to use \a wm_run_modal.

*/

/*!
\fn void wm_quit(
    enum wm_error const                 i_reason)
\brief signal the event manager to close down
\param[in] i_reason error code
\returns none

This routine signals the window manager to close down.
It sets an internal flag, which signifies that the run
loop should exit. 

This has no affect in the wm_run_modal routine. 

*/

/*!
\fn void wm_draw(
    window *const                       i_window)
\brief redraw window
\param[in] i_window window to redraw
\returns none

Redraws all windows, with \a i_window being the last to be drawn.
If \a i_window is NULL, the currently focused window will be drawn last.
*/

/*!
\fn void wm_draw_widget(
    widget *const                       i_widget)
\brief draw a widget
\param[in] i_widget widget to draw
\returns none
*/

/*!
\fn window*const wm_grab(
    window*const                        i_window)
\brief grab the focus
\param[in] i_window window to grab focus. NULL to unset the focus.
\returns window that had the previous focus
*/

/*!
\fn void wm_unregister_window(
    window*const                        i_window)
\brief remove a window from the window manager
\param[in] i_window window to remove
\returns none

Once the window has been removed, it is no longer managed by the window
manager. If it was dynamically allocated, it is the callers responsibility
to dispose of it.
*/

