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 The library may not support the Border/NoBorder hint, in which case <emphasis>every</emphasis> pair of windows will have a visible border &mdash; or no border &mdash; between them.
  20 </para>
  21 <note><para>
  22 The Border/NoBorder was introduced in Glk 0.7.1.
  23 Prior to that, all games used the Border hint, and this remains the default.
  24 However, as noted, not all implementations display window borders.
  25 Therefore, for existing implementations, <quote>Border</quote> may be understood as <quote>your normal style of window display</quote>; <quote>NoBorder</quote> may be understood as <quote>suppress any interwindow borders you may have</quote>.
  26 </para></note>
  27 <para>
  28 There may be decorations within the windows 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.
  29 </para>
  30 <para>
  31 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.
  32 </para>
  33 <para>
  34 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.
  35 </para>
  36 </refsect1>
  37 </refentry>