<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>Window Management - ClanLib SDK</title>
<link rel="stylesheet" media="screen" type="text/css" href="clanlib.css"/>
<link rel="icon" href="gfx/favicon.png" type="image/png"/>
</head>
<body>
<div id="content">
<h1><a href="."><img src="gfx/clanlib.png" alt="ClanLib SDK" /></a></h1>
<!--
<div style="float: right;">
<a href="download.html">Download</a> :
<a href="docs.html">Documentation</a> :
<a href="development.html">Development</a> :
<a href="donations.html">Donations</a> :
<a href="http://www.rtsoft.com/clanlib">Forum</a> :
<a href="contributions.html">Contributions</a>
</div>
-->
<h2>
<img src="gfx/overview.png"/>Window Management
</h2>
<p>In all of the major modern operating systems for the destop, the graphics
and input device sharing is handled by a windowing system. Each application
creates one or more windows, where each represents a rectangular area in
which the application intends to interact with the user. The windows are
usually layered in a z-order, with one of the windows being the foreground
(focused) window, the window that currently receives user input, while all
the other windows are background (inactive) windows. Depending on the
windowing system and the current foreground window, the background windows
may be visible or partly visible or completely covered by a fullscreen
window.</p>
<p>In other words, the window is the basic interface to the OS windowing
system, and one must be created before any graphics can be drawn or any
input received. In ClanLib the window is represented by the
<span class="code">CL_DisplayWindow</span> class. The easiest way to create a window will be to
simply call one of its constructors:</p>
<p>The following code will create a 640x480 window located at 10,10 with the
window caption Hello ClanLib!</p>
<pre>
CL_DisplayWindow window(10, 10, 640, 480, "Hello ClanLib!");
</pre>
<p>Although everything drawn on the screen comes from one window or another,
the windowing systems usually offer several different types of APIs to draw
graphics or handle user input.</p>
<p>For example, in Microsoft Windows you can
use either GDI, DirectDraw, DirectShow, Direct3D or OpenGL to render the
graphics, and you can use either basic window input messages or DirectInput
to read user input.</p>
<p>The windowing system normally needs to know very early
on which of these technologies you intend to use (this simplifies
housekeeping for the OS), and so ClanLib also needs to know exactly what you
want to do.</p>
<p>The <span class="code">CL_DisplayWindow</span> example shown above
assumes a lot of defaults for the window created, but if you need something
else than those defaults, you need to first create a display window
description. In this example we describe the window characteristics first,
then create the window.</p>
<pre>
CL_DisplayWindowDescription description;
description.set_width(640);
description.set_height(640);
description.set_title("Hello ClanLib!");
description.set_allow_resize(false);
CL_DisplayWindow window(description);
</pre>
<p>The ClanLib display system is built as an abstract graphics and input
API, with other ClanLib libraries acting as display targets. Currently only
an OpenGL display target library exists (clanGL), but other targets may be
added in the future. When creating a window it is also important to be able
to specify the target specific window characteristics, i.e. the bit depth of
the z-buffer in OpenGL. Each target offers an alternative description
class, eg. <span class="code">CL_OpenGLWindowDescription</span> for
clanGL:</p>
<pre>
CL_OpenGLWindowDescription description;
description.set_width(640);
description.set_height(480);
description.set_title("Hello OpenGL");
description.set_depth_size(24);
CL_DisplayWindow window(description);
</pre>
<h3>Window Messages</h3>
<p>The OS windowing system communicates with the application and its window
by sending it messages via a message queue. In order to process these
messages, a ClanLib application needs to call <span
class="code">CL_KeepAlive::process()</span>. This function then
reads and handles the messages, updating the input contexts and emiting
signals when the window is resized and so on.</p>
<p>A simple main loop of a ClanLib application may look like this:</p>
<pre>
CL_SetupCore setup_core;
CL_SetupDisplay setup_display;
CL_SetupGL setup_gl;
CL_DisplayWindow window(10, 10, 640, 480, "Hello World");
CL_GraphicContext gc = window.get_gc();
CL_InputContext ic = window.get_ic();
while (ic.get_keyboard().get_keycode(CL_KEY_ESCAPE) == false)
{
draw_gfx(gc);
handle_input(ic);
window.flip();
CL_KeepAlive::process();
CL_System::sleep(10);
}
</pre>
</div>
</body>
</html>
