Playing around with barf
[rodin/chimara.git] / docs / reference / glk-display-style.sgml
1 <?xml version="1.0"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
4 ]>
5 <refentry id="chimara-A-Note-on-Display-Style">
6 <refmeta>
7 <refentrytitle>A Note on Display Style</refentrytitle>
8 <manvolnum>3</manvolnum>
9 <refmiscinfo>CHIMARA Library</refmiscinfo>
10 </refmeta>
11 <refnamediv>
12 <refname>A Note on Display Style</refname>
13 <refpurpose>How windows may be displayed on different platforms</refpurpose>
14 </refnamediv>
15 <refsect1>
16 <title>Description</title>
17 <para>
18 The way windows are displayed is, of course, entirely up to the Glk library; it depends on what is natural for the player's machine. The borders between windows may be black lines, 3-D bars, rows of <quote><computeroutput>&num;</computeroutput></quote> characters; there may even be no borders at all. 
19 </para>
20 <note><para>
21 This is an important possibility to keep in mind.
22 </para></note>
23 <para>
24 There may be other decorations as well. A text buffer window will often have a scroll bar. The library (or player) may prefer wide margins around each text window. And so on.
25 </para>
26 <para>
27 The library is reponsible for handling these decorations, margins, spaces, and borders. You should never worry about them. You are guaranteed that if you request a fixed size of two rows, your text grid window will have room for two rows of characters &mdash; if there is enough total space. Any margins or borders will be allowed for already. If there <emphasis>isn't</emphasis> enough total space (as in stages 4 and 5 of <link linkend="chimara-Figure-Squeezing-Window">this figure</link>), you lose, of course.
28 </para>
29 <para>
30 How do you know when you're losing? You can call glk_window_get_size() to determine the window size you really got. Obviously, you should draw into your windows based on their real size, not the size you requested. If there's enough space, the requested size and the real size will be identical; but you should not rely on this. Call glk_window_get_size() and check.
31 </para>
32 </refsect1>
33 </refentry>