\chapter{The GNUstep Markup Language}
\section{The GNUstep Markup Language}

The GNUstep Renaissance Markup Language (gsmarkup for short) is used to
describe graphical user interfaces (windows, menus, etc).  A gsmarkup
file contains a description of how the graphical user interface should
be created, which objects are to be placed in the user interface, and
how these objects are interconnected between them and to other objects
in the main application.

\section{General overview of the main components}

\subsection{XML Header}
A well formed gsmarkup file begins with the standard XML declaration,
\begin{verbatim}
<?xml version="1.0"?>
<!DOCTYPE gsmarkup>
\end{verbatim}
While this declaration is not strictly necessary, it's pretty to have
-- it declares that the file is an XML version 1 file, and that the
document type is \texttt{gsmarkup}.

\subsection{The \texttt{<gsmarkup>} tag}
The document begins with a \texttt{<gsmarkup>} tag, and ends with a 
\texttt{</gsmarkup>}.  So, here is a skeleton gsmarkup file:
\begin{verbatim}
<?xml version="1.0"?>
<!DOCTYPE gsmarkup>
<gsmarkup>
  <!-- the document goes here -->
</gsmarkup>
\end{verbatim}
(this \texttt{<gsmarkup>} tag is the equivalent of the \texttt{<html>}
tag in HTML).

\subsection{Comments}
Comments can be inserted anywhere in the file inside a \texttt{<!--
-->} tag.  For example,
\begin{verbatim}
<!-- This is a comment -->
\end{verbatim}
Such comments are ignored by the parser.

\subsection{Special Characters}
A few characters are special XML characters.  To insert these
characters inside strings or free text in the file, you need to use
the appropriate XML entities.  The table \ref{XML-entities} lists
these important entities for easy reference.
\begin{table}
\caption{\label{XML-entities}Special XML entities}
\begin{tabular}{l|c}
Entity  & Value\\
\hline
\&amp;  & \texttt{\&} \\
\&apos; & \texttt{'} \\
\&gt;   & \texttt{>} \\
\&lt;   & \texttt{<} \\
\&quot; & \texttt{"} \\
\end{tabular}
\end{table}
For example, to insert \texttt{<} in the title of a button, you need
to write it as \texttt{\&lt;}.

\subsection{\texttt{<objects>} and \texttt{<connectors>} sections}

Inside the \texttt{<gsmarkup>} document tag, you can place objects and
connectors section.  An objects section is started by opening a
\texttt{<objects>} tag, and ended by closing it.  A connectors section
is started by opening a \texttt{<connectors>} tag, and ended by
closing it.  You can use as many objects and connectors sections as
you want, even if normally just one objects and one connectors
sections are present.  You can not nest objects and connectors
sections.  An objects section declares a list of objects which are to
be created when the file is loaded into a running application.
Typically, the list of objects might include windows (and all the
widgets contained in the windows), menus, and other arbitrary objects,
including objects of custom classes you have defined in your
application.  The connectors section declares a list of connectors;
each connector represents a connection to establish between two
objects - typically between an object residing in your application and
one of the objects created when the file is loaded.  As we will
explain later on, connections between objects created when the file is
loaded (and connections from an object within the file and an external
object in your application) can be declared using a special syntax
inside the objects section itself, so normally the connectors section
is very short, and it is mostly provided for the special cases which
can't be managed by the other syntax.  Programs generating gsmarkup files
are expected to put all connections in the objects section, except
connections which can't be embedded there.

The difference between the two section types is important because the
parser behaves differently inside an objects section and inside a
connectors section.

To let you get a more practical feeling of the thing, here is a very
simple gsmarkup file creating a button:
\begin{verbatim}
<?xml version="1.0"?>
<!DOCTYPE gsmarkup>
<gsmarkup>

<objects>

  <window title="Button Test" closable="NO" frameAutosaveName="main" >
    <button title="Click this button to quit" action="terminate:" />
  </window>

</objects>

</gsmarkup>
\end{verbatim}
We will explain the \texttt{window} and the \texttt{button} tags later
on.  Just notice that in this example, there is only an objects
section in the file (which creates a window containing a button), and
there is no connectors section.

If you want to run this file, save it as a \texttt{button.gsmarkup} file,
then type at the command prompt
\begin{verbatim}
openapp GSMarkupBrower.app button.gsmarkup
\end{verbatim}
(of course you need to have installed Renaissance for this to work).  You
can normally load any file to see how it looks by using
\texttt{GSMarkupBrowser.app} in this way.

\section{The objects section}

\subsection{Relationship between tags and objects}

The objects section describes objects which are to be created when the
file is loaded into a running application.  The section describes the
intention of the programmer about the objects to be created -- the
logic of the GUI objects in other words -- rather than the precise
details of how the objects are to be created on each platform.  For
example, a button with title 'Quit' and which, when clicked,
terminates the application, is described in the file as:
\begin{verbatim}
<button title="Quit" action="terminate:" />
\end{verbatim}
The actual appearance of the button (border, imaged used for borders,
font used for the title, changing in the button appearance when it's
clicked etc) is not specified -- on each platform it will different --
on platforms supporting themes or just preferences like allowing the
user to change the default font size, it might even change each time
depending on the configuration.  The actual size of the button is
computed automatically by the system at runtime when the button object
is created; the title is also translated automatically at runtime (and
the button sized depending on the translated title).  All this
information (appearance of buttons, fonts, images, translation of
titles etc) really is not known till the program is run, so the button
object will result different on each platform and each configuration.

For this reason, the list of objects really is more an abstract
description of the logic of the GUI interface rather than an exact
specification.  Most tags correspond to objects; a few tags (such as
the separators tag, used to add separators in menus and hboxes/vboxes)
don't necessarily correspond to objects.

In some cases, different tags produce objects of the same class; for
example the \texttt{<label>} tag creates a \texttt{NSTextField} object
used to display a non-editable string (such as a title or a message),
while the \texttt{<textField>} tag creates a \texttt{NSTextField}
object used to display an area on screen where the user can insert
some text.  While they are implemented using the same class, they are
conceptually completely different GUI objects, because they have a
completely different function.

In other cases, the same tag could produce objects of different
classes depending on the attributes it contains.  As an extreme
example, all tags representing view and window objects support an
\texttt{instanceOf} attribute -- if this attribute is set to a value, 
the value is used as the name of the class of the object to create
(provided that this class is a subclass of the class which would be
used by default).  For example,
\begin{verbatim}
<button title="Example" />
\end{verbatim}
would create a button object (an instance of \texttt{NSButton}).  Now
if \texttt{MyButton} is a subclass of \texttt{NSButton}, then
\begin{verbatim}
<button title="Example" instanceOf="MyButton" />
\end{verbatim}
would do exactly the same, but allocating the object using the custom
subclass \texttt{MyButton} instead of the default class
\texttt{NSButton}.  This is a very powerful and simple way of embedding 
customized objects in windows.

Normally, each tag creates an object, except in special cases, which
are clearly documented.

\subsection{Object tags - basic example}
Consider for example the \texttt{<window>} tag, used to create a
window object.  In the simplest case, the tag is just opened and
closed:
\begin{verbatim}
<?xml version="1.0"?>
<!DOCTYPE gsmarkup>

<gsmarkup>

  <objects>
    <window>
    </window>
  </objects>

</gsmarkup>
\end{verbatim}
or more simply (using the abbreviation \texttt{<window />}, 
which in XML means \texttt{<window>} \texttt{</window>}):
\begin{verbatim}
<?xml version="1.0"?> 
<!DOCTYPE gsmarkup>

<gsmarkup>

  <objects>
    <window />
  </objects>

</gsmarkup>
\end{verbatim}
(in this example, we showed all the document; in the next examples of
object tags, we will omit all but the tags we are discussing).  If you
load this example into an application, it will create a window, with
no particular attributes and nothing inside it.

\subsection{Object tags - attributes}
If you want to modify the properties of an object, you add attributes
to the tag.  For example, if you create a window using the
\texttt{<window>} tag, it is created by default miniaturizable, resizable and 
closable.  If you don't want it to be closable, you need to add an attribute
to the tag -
\begin{verbatim}
<window closable="no" />
\end{verbatim}
This causes the window to be created without the close button.
Attributes are generally used to change the properties of that
specific object.  Each object is normally created with default
properties set up for the most common case, so you only need to
specify attributes when you need some special behaviour.  In the
example of the window, all windows are created by default with a close
button, unless you specify \texttt{closable="no"}.

A tag can have more than one attribute -- it can have as many
attributes as you need.  The attributes are written one after the
other one, separated by spaces.  For example, if you want both to specify
that a window should not be closable and not resizable, you can write
\begin{verbatim}
<window closable="no" resizable="no" />
\end{verbatim}

We now examine and classify all the different types of attributes you
can use for a tag.  Some attributes have a string value, other a
boolean value, other even describe a color or a font; other still give
a name to the object so that it can be referenced from elsewhere;
other are references to other objects.

\subsubsection{String attributes}
String attributes are very common -- a string attribute sets a
property of the object which is described by a string.  For example,
if you want to create a window with a title \texttt{Game Board}, you
write
\begin{verbatim}
<window title="Game Board" />
\end{verbatim}
The attribute \texttt{title} is set to a string, \texttt{Game Board}
in the example.  You can use any character in the string, except a few
special XML characters -- to insert them, you need to use the entities
listed in table \ref{XML-entities}.  Each tag has a different set of
available string attributes -- the reference documentation later on in
this document lists all available string attributes for each tag.

\subsubsection{Localizable strings attributes}
Most (but not all) strings need to be localized -- that is, translated
into the user preferred language -- before they are displayed.  Each
tag knows which attributes are strings to localize, and which are
strings not to localize (it's normally quite obvious -- anything which
is meant to be displayed to the user must be localized, while anything
which is only used internally by the program must not be; for example,
window titles or button titles are localized; selectors as used in
actions are not).  To localize a string, the gsmarkup framework calls the
NSBundle method +localizedStringForKey:value:table:, first looking for
the string in the specific table (normally loaded from a file having
the same name as the .gsmarkup file, but with a .strings extension rather
than a .gsmarkup extension), and failing that, in the Localizable.strings
strings table.  If that fails too, the string is used untranslated.
For example, suppose that you have the window
\begin{verbatim}
<window title="Game Board" />
\end{verbatim}
created in your \texttt{main.gsmarkup} file.  To translate the window
into Italian, you need to add a file
\texttt{Italian.lproj/main.strings} to your application, containing
the following line:
\begin{verbatim}
"Game Board"="Tavolo di Gioco";
\end{verbatim}
when the application loads the .gsmarkup file, it automatically translates
it into the appropriate language by using the appropriate
\texttt{main.strings} file for that language.  In this example, when the
user sets Italian as his preferred language, the window will be
created with title \texttt{Tavolo di Gioco} rather than \texttt{Game
Board}.  Please note that by default different .gsmarkup files use
different .strings files -- for each .gsmarkup file there is a
corresponding .strings file.  This makes it easier to keep the
.strings files updated (you only need to update a .strings file when
the corresponding .gsmarkup files has changed), makes clear where each
string comes from, and allows different .gsmarkup files to contain the
same English string, and yet to translate it in different ways.

\subsubsection{Boolean attributes}
Boolean attributes are used to set a boolean property of the object.
The valid values of a boolean attributes are \texttt{yes} and
\texttt{no} -- for example, you can write
\begin{verbatim}
<window resizable="no" />
\end{verbatim}
Resizable is a boolean attribute, which can be \texttt{YES} or
\texttt{NO}.  The example sets it to \texttt{NO}.  For consistency 
with other stuff which is always written lowercase, we prefer to use
\texttt{yes} and \texttt{no} (lowercase), but it is only a matter of taste: 
\texttt{Yes}, \texttt{YES} are valid as well as attribute values, and they
mean the same thing as \texttt{yes}; \texttt{No} and \texttt{NO} are
valid as well to mean \texttt{no}.  For example, it is perfectly
correct to write
\begin{verbatim}
<window resizable="NO" />
\end{verbatim}
and it means the same as before.

Each boolean attribute normally has a default value (documented in the
documentation); if a boolean attribute is not present, or if its value
can't be parsed as a \texttt{yes} or a \texttt{no}, then it's ignored,
which implicitly means that the default for it is used.

\subsubsection{Number attributes}
Number attributes are used to set a property to a number (integer or
float).  For example, to create window with width \texttt{200} and 
heigth \texttt{50}, you do
\begin{verbatim}
<window width="200" height="50" />
\end{verbatim}

\subsubsection{Image attributes}
Image attributes are used to set a property to an image.  The image is
found by invoking the method \texttt{+imageNamed:} of
\texttt{NSImage}.  For example,
\begin{verbatim}
<button image="mail" title="Read Mail" imagePosition="above" />
\end{verbatim}
would set the button image to the result of calling 
\begin{verbatim}
[NSImage imageNamed: @"mail"]
\end{verbatim}
and position it above the title.

\subsubsection{Sound attributes}
Sound attributes are used to set a property to a sound.  The sound is
found by invoking the method \texttt{+soundNamed:} of
\texttt{NSSound}.  For example,
\begin{verbatim}
<button sound="mail" title="Read Mail" />
\end{verbatim}
would set the button sound to the result of calling 
\begin{verbatim}
[NSSound soundNamed: @"mail"]
\end{verbatim}

\subsubsection{Color attributes}
Color attributes are used to set a property to a color.  You should
use this very rarely, because you want your program to use the native
platform colors when running on a certain platform.  But in some cases
-- for example when setting up a colorWell (a gui object which allows
the user to choose a color) -- you need to specify colors.

Color attributes are evaluated in the following way by the system: 
\begin{enumerate}
\item First, the system checks if \texttt{NSColor} responds to the
  method \texttt{+xxxColor}, where \texttt{xxx} is the value of the
  attribute.  If it does, the method is invoked, and the result is
  used as the color.  For example,
\begin{verbatim}
<colorWell width="50" height="50" color="red" />
\end{verbatim}
  will create a colorWell which displays the color returned by
  \texttt{[NSColor redColor]}.  In this way, you can access all
  standard colors by name, such as \texttt{black}, \texttt{white},
  \texttt{red}, \texttt{blue}, \texttt{green}, \texttt{yellow},
  \texttt{windowBackground}, etc.  (advanced tip: if you want to
  access a non-standard one by name, you can always implement a
  \texttt{NSColor} category, and add the method you need).
\item If the method is not found, the system tries to parse the color
  as a calibrated RRGGBB or RRGGBBAA description of the color, where
  RR, GG, BB and AA are hexadecimal two-digits number between 00 and
  FF describing the red, green, blue and alpha components of the color
  (btw this is the same format used in HTML pages, without the
  \texttt{\#} at the beginning).  For example, \texttt{FFFFFF} is
  white, \texttt{000000} is black, \texttt{FF0000} is red, and
  \texttt{FF000065} is a semi-transparent red color.
\end{enumerate}

\subsubsection{Font attributes}
Font attributes are used to set a font property.  This is very
delicate, because you want your program to use the native platform
fonts when running on a certain platform -- hardcoding a certain font
might actually destroy the visual impact of your program rather than
improving it (typically, the font you want might not be available on
that system, and be replaced with an ugly one, or might simply clash
completely with the rest of the look on the system, be too big, too
little, or too bold or too fuzzy compared with the other native fonts
used by the system).  In general, system fonts are normally chosen
between the prettier fonts available on the plaform, and the
appearance of the user interface elements is made to match those
fonts.  Last, the user/theme might have changed the fonts to fit their
wishes/needs, and you certainly don't want to argue with your users.
For this reason, gsmarkup normally doesn't really allow you to specify a
font, but only to scale the default system fonts.

In some cases -- for example when creating panels -- you might want to
display a title on top of your panel, or other information which you
want to display in a more prominent font.  This is typically needed by
labels (objects which display non-editable strings such as those used
by titles or messages).  A font attribute allows you to specify the
size and type of font you want.

The font for labels is normally found by calling the \texttt{[NSFont
labelFontOfSize:0]} method (or the \texttt{[NSFont systemFontOfSize:0]} 
on older systems which don't have \texttt{+labelFontOfSize:}).

You normally only need to make the font bigger or smaller.  To do it,
you can use the following font values:
\begin{itemize}
\item {\bf Tiny}: uses the same font, reduced to 1/3 of the original size.
\item {\bf tiny}: uses the same font, reduced to 1/2 of the original size.
\item {\bf Small}: uses the same font, reduced to 2/3 of the original size.
\item {\bf small}: uses the same font, reduced to 4/5 of the original size.
\item {\bf medium}: uses the same font, with no size change.
\item {\bf big}: uses the same font, enlarged 5/4 times the original size.
\item {\bf Big}: uses the same font, enlarged 3/2 times the original size.
\item {\bf huge}: uses the same font, enlarged 2 times the original size.
\item {\bf Huge}: uses the same font, enlarged  3 times the original size.
\end{itemize}
For example,
\begin{verbatim}
<label font="Big">Contents</label>
\end{verbatim}
displays \texttt{Contents} using the default label font, with the
default label font size multiplied by 1.5.

You can also specify a float, which is read and interpreted as a
scaling factor.  For example, 
\begin{verbatim}
<label font="1.5">Contents</label>
\end{verbatim}
is completely equivalent to setting the font to \texttt{Big}.

Normally, you only want to change the fonts in labels, and you don't
need to bother with the font type.  For very special cases, you might
need to change font type.  The current API used on OpenStep systems
provides NSFont methods to get recommended fonts to be used on that
particular platform to display various types of gui objects -- for
example, \texttt{[NSFont userFontOfSize: 0]} returns the font to be
used for user editable text, in the default size.  To choose that type
of font, you just specify \texttt{user} as the font value, as in
\begin{verbatim}
<label font="user">Testing fonts</label>
\end{verbatim}
this draws the label using the font \texttt{[NSFont userFontOfSize:
0]}.  In general, if the value of the font attribute is xxx, the
NSFont method \texttt{+xxxFontOfSize:} (if it exists) is used to get
the font.  The types of fonts available on gsmarkup at the moment are
\texttt{label}, \texttt{boldSystem}, \texttt{user}, 
\texttt{userFixedPitch}, \texttt{menu}, \texttt{message},
\texttt{palette}, \texttt{system}, \texttt{titleBar},
\texttt{toolTips}.  These fonts should be available on other OpenStep
systems as well, but not all them are available on older OpenStep
systems, and you would extremely rarely need to use them anyway.

Anyway, if for example you want to display a button containing a title
with a bigger font, you may need them.

You can use one of those standard fonts in any size, for example
\begin{verbatim}
<label font="user big">Testing fonts</label>
\end{verbatim}
is valid, and uses the same font returned by \texttt{[NSFont
userFontOfSize: 0]} but enlarged by a factor of 1.20.

\subsubsection{The instanceOf attribute}
This is a special attribute which is recognized by all objects which
inherit from windows or views (views represent rectangular areas in
windows).  It allows you to allocate the object using a subclass
instead of the original class; it is typically used to create objects
of custom subclasses.  For example, if you implement a class called
\texttt{NPWindow}, which is a subclass of \texttt{NSWindow} with some
special behaviour added to it, then you can create a window of you
subclass by doing
\begin{verbatim}
<window instanceOf="NPWindow" />
\end{verbatim}
This will create a window using the standard procedure used for
windows, except it will lookup the class named \texttt{NPWindow} at
run time, and allocate the object using that class instead of
\texttt{NSWindow} class.  Please note that all the standard attributes
of a window object are still recognized:
\begin{verbatim}
<window instanceOf="NPWindow" width="100" height="100" resizable="no" />
\end{verbatim}
the attributes will be read, and applied to the window exactly as if
the window was a standard \texttt{NSWindow} object.  Because
\texttt{NPWindow} is a subclass of \texttt{NSWindow} (and Renaissance
will check it at run time), all the attributes and methods which are
valid for a \texttt{NSWindow} are expect to be available for an
\texttt{NPWindow} object too, so this is expected to work.

In detail, when you specify a \texttt{instanceOf="XXX"} attribute for a
view or window tag, Renaissance at run time looks up \texttt{XXX} as a
class name, searching for a class with that name.  If a class with
that name is found (in the executable), Renaissance checks that the
class is a subclass of the default class (the one which would be used
if no \texttt{instanceOf} attribute had been specified).  If it is, then
Renaissance allocates the new object using class \texttt{XXX} instead
of the default class.  It is important to check that the class
\texttt{XXX} is a subclass of the default class, because that makes sure
that the object created supports all the attributes and methods that a
default object would.  Then, everything else goes on as if the created
object was of the default class.

The reference documentation should mark clearly tags which recognize
the \texttt{instanceOf} attribute, and tags which ignore it.

As a final note, if you need to allocate an object which is not a
subclass of a view or of a window, you can use the \texttt{<instance>}
tag, which allows you to allocate an instance of any class (still
specified with the \texttt{instanceOf} attribute).  This is mostly used to
create controller objects.  Because of the wide generality of the
objects allocated by the \texttt{<instance>} tag (which could be of
any class), there are no defined attributes you can set for the object
created, except for embedded outlets (described in the next sections),
which are always available for all objects.  The \texttt{<instance>}
tag is normally used if you want to create an instance of a controller
class from a gsmarkup file; it's not used to embed custom controls in
windows, or to create custom windows: in those case, you are better
off using a view or window tag with a \texttt{instanceOf} attribute,
because then Renaissance will know what type of object it is and will
treat it accordingly, including recognizing all the appropriate
attributes.

\subsubsection{The id attribute}
This is a special attribute which any object can have; it is used to
tag objects with names, so that you can refer to that object by name.
The attribute is always called \texttt{id}, and its value is a string
which is the internal name to give to the object\footnote{The string
should not contain any dots (that is, it should not contain the
\texttt{'.'} character), because dots are used for advanced key value
coding.}.  For example,
\begin{verbatim}
<window id="board" />
\end{verbatim}
creates a window, and tags it with the id \texttt{board}.  You can
then refer to this window object by name whenever you need it (we'll
explain later on when you might need to refer to the window object).
Of course, you don't need to tag all objects with names -- you would
just be wasting time and making your gsmarkup files more difficult to
read if you do -- you only need to tag the ones which you need to
refer to.  The id name of the window is never shown to the user --
it's only used internally to refer to objects by name, and establish
connections between objects.

\subsubsection{Mask attributes}
Some attributes are used for integer mask, where a number of
possibilities are combined.  In that case, the description of the
attributes lists all the possible values, and a \texttt{|} character
can be used to specify multiple values at the same time (the
\texttt{|} character is used because internally a bitfield OR will be
used to calculate the final value).  For example, a \texttt{<button>}
tag has a \texttt{sendActionOn} attribute (inherited from
\texttt{<control>}) which can be used to control when the button
specific action is triggered.  The \texttt{sendActionOn} attribute can
take a number of values, such as \texttt{leftMouseUp} or
\texttt{leftMouseDown} (indicating that the button's action is
triggered when the left mouse button is released, or pressed).  To
specify that it should the action both when the left mouse button is
pressed and released, you can use the \texttt{|} character as in the
following example:
\begin{verbatim}
<button title="Test" action="dummyAction:" 
               sendActionOn="leftMouseDown | leftMouseUp" />
\end{verbatim}
Note that spaces around the \texttt{|} character are ignored, so you
can use them for readability if you want.

\subsubsection{Attributes referring to other objects}
In the previous section we have explained how you can tag an object
with an id.  In this section we learn how you can refer to an object
by id.  There is a very general syntax which can be used to refer to
an object which has been given an id: you prefix the id name with a
hashmark (\texttt{\#}).  For example, if you create a window and give
it an id of \texttt{board}, as in
\begin{verbatim}
<window id="board" />
\end{verbatim}
then you can refer to that window object by using the syntax
\texttt{\#board}.  \texttt{\#board} simply means {\it the object whose id name 
is} \texttt{board}.

This is normally used to establish connections between objects.  There
are two ways of building connections between objects: one is adding a
connector to a connectors section.  A gsmarkup file can contain one or
more connectors sections, where you can freely build up connections
between objects (and you refer to objects by using their ids and the
syntax just explained).  The other way, the one we learn about here,
is by using attributes which take objects as values.

Some attributes wants other objects as values.  For example, a window
can have a delegate, and this delegate is an object.  You can specify
the delegate object for a window by using the following syntax:
\begin{verbatim}
<window delegate="#myDelegate">
\end{verbatim}
When this file is loaded in a running application, the attribute 
\texttt{delegate} is treated specially.  It is treated specially because
its value begins with a hash (\texttt{\#}), which means it is a
reference to another object (in the file or even outside the file).
When the file is loaded, the method \texttt{setDelegate:} of the
window object will automatically be called, with argument the object
which has id name \texttt{myDelegate}.  This object can be 
\begin{enumerate}
\item another object which is created by the file when the file is
  loaded.  In the example, since you can create objects of custom
  classes in the file, you could allocate an instance of a custom
  class, give it the id name \texttt{myDelegate}, and then make it the
  window controller.

\item the file owner.  The file owner is an existing object in the
  application which loads the file; whenever the application loads a
  gsmarkup file, it needs to specify a file owner object, which is
  automatically made available to the file with the id name
  \texttt{NSOwner}.  For example, to make the file owner the delegate
  of your window, you would do
\begin{verbatim}
<window delegate="#NSOwner">
\end{verbatim}
  Normally, all connections between the objects loaded in the file and
  the existing application objects are done through the file owner.

\item NSApp (the shared application instance), which is automatically
  made available by Renaissance with the id name \texttt{NSApp}.  For
  example, to create a popup button with an item which terminates the
  application, you would do
\begin{verbatim}
<popUpButton>
  <popUpButtonItem title="terminate the app" action="terminate:"
                   target="#NSApp" />
</popUpButton>
\end{verbatim}

\item some other existing object in the application which is made
  available to the file when the file is loaded.  If the application
  needs it, by using the extended NSBundle GSMarkup API, it can make
  available any existing object in the application specifying under
  which name it should be available.  If there is a single object to
  connect, it is simpler to make that object available as file owner;
  if there are more, you can specify them in the external name table
  dictionary (see description of the NSBundle GSMarkup API), and then
  the file can make any connections to those objects by referring to
  them by id, and using the special syntax with the hash.

\end{enumerate}

Here is another example --
\begin{verbatim}
<window>
  <hbox>
    <button title="yes" id="yes" nextKeyView="#no" />
    <button title="no" id="no" nextKeyView="#yes" />
  </hbox>
</window>
\end{verbatim}
in this example, a window with two buttons is created.  The first
button has title \texttt{yes}, the second one has title \texttt{no}.
The first button is given id \texttt{yes}, and the second one is given
id \texttt{no}.  Then, the nextKeyView attribute of the first button
is set to point to the second one, and the nextKeyView attribute of
the second button is set to point to the first one.  This allows users
to navigate between the buttons using the keyboard -- pressing TAB
while the input focus is on an object moves the focus to the
nextKeyView of that object.  In the example, the nextKeyView of the
first button is the second one, and viceversa, so by pressing TAB the
user can move the input focus between the two buttons.

\subsubsection{Technical details of embedded outlets}
You can skip this section at a first reading.  It is explaining the
technical details of attributes referring to objects.

Technically, whenever an attribute has a value which begins with a
single hash (\texttt{\#}), the system automatically creates an outlet
connector when the file is loaded (and adds it to the list of outlet
connections to be established), and removes the attribute from the
list of attributes.  So if you wish to encode attribute text beginning
with a hash, you must escape that leading hash by doubling it.
No check is done on the attribute name, so you
are free to setup any sort of connectors you want.  When the outlet
connections are established, the outlet will establish the connection
from the source (the object bound to the tag where the attribute was
found) to the target (the object which is referred by the attribute)
using as key the attribute name.  Establishing outlet connections uses
key-value coding, so in practice by writing
\begin{verbatim}
<window delegate="#myDelegate">
\end{verbatim}
you are effectively establishing that the value of the key
\texttt{delegate} of the created window object should be set to the
object whose id is \texttt{myDelegate}.

This way of embedding outlets inside object description is both very
natural and very powerful; it is certainly much more natural than
having to write in the separated connectors section.

\subsubsection{Advanced embedded outlets using key value paths}
This section explains a rarely useful, and rarely used, advanced
technique.  Unless you are already familiar with key-value coding, you
can/should definitely skip it at a first reading.

Renaissance allows the advanced syntax
\begin{verbatim}
<window delegate="#NSOwner.windowDelegate" />
\end{verbatim}
to mean extracting the value for the key \texttt{windowDelegate} of
the \texttt{\#NSOwner} object, and setting it as the \texttt{delegate}
of the window.  ``Extracting the value for the key'' will use
key-value coding to get it.  In practice, if the \texttt{\#NSOwner}
responds to one of the methods \texttt{getWindowDelegate},
\texttt{windowDelegate}, \texttt{\_getWindowDelegate}, 
\texttt{\_windowDelegate}, or has an instace variable called 
\texttt{\_windowDelegate} or \texttt{windowDelegate}, to get the value
for the key, the method will be called, or the instance variable
will be read\footnote{In more details, it will first try to get the
object by calling the method \texttt{getWindowDelegate} of the
\texttt{\#NSOwner}; if the \texttt{\#NSOwner} does not respond to that
method, it will try \texttt{windowDelegate}; if the \texttt{\#NSOwner}
does not to respond to it either, it will try
\texttt{\_getWindowDelegate}, and then \texttt{\_windowDelegate}; if the
\texttt{\#NSOwner} still does not respond to those methods, it will
try to access the \texttt{\#NSOwner} instace variable
\texttt{\_windowDelegate}, if any, and failing that, the instance variable
\texttt{windowDelegate}.  If all else fails, it will call the method
\texttt{handleQueryWithUnboundKey:} (which by default 
usually raises an exception).}.

This can be a very handy trick.  Typically, you can have delegates (or
other similar attributes) of objects created from the gsmarkup to be
set to point to instance variables (or the result of calling certain
methods) of the \texttt{\#NSOwner}.  It's an additional layer of
flexibility.

Renaissance also allows multiple key-value coding in sequence, for example
\begin{verbatim}
<window delegate="#NSOwner.controller.preferenceWindowDelegate" />
\end{verbatim}
This will start with \texttt{\#NSOwner}, use key-value coding to
extract the value for key \texttt{controller} of that object, then use
key-value coding to extract the value for key
\texttt{preferenceWindowDelegate} of the resulting object, and finally
set the window's \texttt{delegate} to the result.

To support both simple and multiple key-value coding, Renaissance uses
\texttt{-valueForKeyPath:}.  For example, when Renaissance processes the 
code
\begin{verbatim}
<window delegate="#NSOwner.windowDelegate" />
\end{verbatim}
it assigns to the window's \texttt{delegate} the result of calling
\begin{verbatim}
[#NSOwner valueForKeyPath: @"windowDelegate"]
\end{verbatim}
which, in this case, because there are no dots in the keypath, does
the same as \texttt{[\#NSOwner valueForKey: @"windowDelegate"]}.

As a general rule, if the id of the source or target of an embedded
outlet (or other connector) contains a dot (that is, the character
\texttt{'.'}), then the string up to the dot is the id of an object to
use, and the string following the dot is interpreted as a key path
value to apply to the object in order to get the actual source or
target of the connector.  So, \texttt{\#xxx.yyy} is to be interpreted
as meaning ``the result of \texttt{[\#xxx valueForKeyPath: @"yyy"]},
where \texttt{\#xxx} is the object with id \texttt{xxx}.''

For example, the expression \texttt{\#NSApp.mainMenu} means the result
of calling 
\begin{verbatim}
[NSApp valueForKeyPath: @"mainMenu"]
\end{verbatim}
which will return the application main menu.
\texttt{\#NSApp.delegate.description} means the result of calling
\begin{verbatim}
[NSApp valueForKeyPath: @"delegate.description"]
\end{verbatim}
which will invoke the \texttt{description} method of the delegate of
\texttt{NSApp}.

For more information, please refer to the documentation of key-value
coding, for example the documentation for the
\texttt{-valueForKeyPath:} and \texttt{-valueForKey:} methods.

\subsection{Object tags - content}
Everything which is found between an open tag and the corresponding
close tag is called the content of the tag.  For example, in
\begin{verbatim}
<label>Please reboot your system</label>
\end{verbatim}
the open tag is \texttt{<label>}, the close tag is \texttt{</label>},
and the string inside is the content of the tag.  Often, the content
of a tag can include other tags.  For example,
\begin{verbatim}
<window>
  <button title="Click me to quit" action="terminate:" />
</window>
\end{verbatim}
in this case, the content of the window tag is the button tag.

In general, while attributes are used to change the properties of the
specific objects represented by that tag, the content of a tag are
used to describe things which go {\sl inside} the object.  This
concept is of course human and not completely well defined, anyway the
idea is that, for example, the attributes of a \texttt{<window>} tag
(such as \texttt{closable="no"}, \texttt{width="200"},
\texttt{title="Main Window"}) change the general properties of the
window, while the tags inside the \texttt{window} tag represent
objects which should be displayed inside the window.

Now we examine typical examples of tags and the type of content they
can hold.

\subsubsection{No content}
Some gui objects do not contain anything.  For example, a button or a
colorWell do not contain anything and never have a content.

\subsubsection{String content}
Some gui objects have a simple string content, representing a string
to be displayed inside the gui object.  This typically happens with
labels and textfields; in this case, the string is not in the
attributes because it could potentially be very large.  For example,
\begin{verbatim}
<label>Missing image</label>
\end{verbatim}
displays a label with the string \texttt{Missing image}, while
\begin{verbatim}
<textField>user@host</textField>
\end{verbatim}
displays an editable textField which contains the string
\texttt{user@host} when it is first displayed.  In this case, the string 
to display is in the content of the tag because it can potentially be
very big (and perhaps optionally contain formatting tags (html?) in
the future for attributed strings ?).

In most cases, string content are localizable -- they are
automatically localized by the gsmarkup framework in the same way as it is
done for localizable string attributes.

\subsubsection{Tag content}
Other gui objects have content which is composed of other objects.
Typical examples include:
\begin{itemize}
\item Menus.  A menu contains menu items, or other menus.  Here is an
  example:
\begin{verbatim}
<menu type="main">
  <menuItem title="Info" action="showStandardInfoPanel:" 
                  keyEquivalent="i" />
  <menuItem title="Hide" action="hide:" keyEquivalent="h" />
  <menuItem title="Quit" action="terminate:" keyEquivalent="q" />
</menu>
\end{verbatim}
  When the menu is created, the menuitems are created and added to it.
  A menuitem has no content.  If a menu contains another menu in its
  content, this other menu is created as a submenu.
\item Windows.  A window can contain a single object, which is set to
  be the window's contentview.  The view can contain other objects, so
  building the whole view tree inside the window.
\item Boxes.  Horizontal, vertical boxes contain a list of objects,
  and display all these objects in a row (in the case of horizontal
  boxes), or in a column (in the case of vertical boxes).  For
  example,
\begin{verbatim}
<hbox>
  <button title="Save" />
  <button title="Discard" />
  <button title="Cancel" />
</hbox>
\end{verbatim}
  displays the buttons inside the horizontal box (which is invisible,
  it is only used to align the buttons).  Simple boxes contain a
  single object, which they display surrounded by a border (and
  optionally with a title).  For example,
\begin{verbatim}
<box title="Mail Preferences">
  <vbox>
    <!-- missing - vbox content -->
  </vbox>
</box>
\end{verbatim}
  displays a border box with title \texttt{Mail Preferences}, and
  inside it a vertical (invisible) box containing any sort of objects
  (not shown in the example).
\item Containers (boxes are actually just a special case of
  containers), such as a scrollview.  A scrollview contains an object,
  which is the scrollview document view.
\item Tables.  A table contains various columns.
\end{itemize}

\section{The connectors section}

The connectors section is used to establish connections between
objects.

\subsection{How objects are given ids}
Objects are identified by their \texttt{id}.  There are various ways
in which an object can be given an \texttt{id}:
\begin{itemize}
\item Objects created by the file are given an id if the tags which
  creates them contains the \texttt{id} attribute.  For example,
\begin{verbatim}
<textField id="pop3" width="200" />
\end{verbatim}
  the textField object is given the \texttt{id} \texttt{pop3}.
\item The file owner -- an object which is specified by the code
  loading the GSMarkup file, and normally is the main way of
  connecting objects in the GSMarkup file with the rest of the
  application -- is automatically given the \texttt{id}
  \texttt{NSOwner}.
\item Additional objects which the code loading the GSMarkup file
  wants to make available to the GSMarkup file.  By specifying an
  external name table when loading the GSMarkup file, the code can
  give an \texttt{id} to any existing object in the application (and
  so making it available for establishing connections to/from it).
\item Some predefined objects have a predefined \texttt{id} given to
  them automatically by the system.  For example, the main
  \texttt{NSApplication} instance is automatically available with
  \texttt{id} \texttt{NSApp}.
\end{itemize}
Any object which has been given an id can be the source or the target
of a connection set up in the connectors section.

\subsection{Connector tags}
Inside the connectors section tags are interpreted in a different way
than inside the objects section.  Inside the connectors sections, tags
are interpreted as being connectors tags rather than object tags.
Connector tags might vary, but normally you only need to know about
outlet connectors, so we only describe outlet connectors here.

\subsection{Outlet connectors}
An outlet connector is created with the \texttt{<outlet>} tag.  For
example,
\begin{verbatim}
<connectors>
 <outlet source="#NSOwner" target="#Controller" key="controller" />
</connectors>
\end{verbatim}
An outlet has a source (an object specified by id), a target (another
object again specified by id), and a key (a string).  The outlet
describes a connection which should be established between the source
and target object; the key represents a key in the source object.  By
using key-value coding, when the outlet connection is established, the
value for the key in the source is set to the target (I'll try to
explain this better in a minute).  In the example, when the outlet is
established, it's result will likely to be to invoke
\begin{verbatim}
[#NSOwner setController: #Controller];
\end{verbatim}
(where \texttt{\#NSOwner} is the object which has id \texttt{NSOwner}
and \texttt{\#Controller} is the object which has id
\texttt{Controller}).

As an advanced extension, if the \texttt{source} or \texttt{target} of
an outlet connector contains a dot (that is, the \texttt{'.'} 
character), then the part of the string before the dot is interpreted
as an object specified by id, and the part of the string after the dot
is interpreted as a key value path to use on the object to get the
actual \texttt{source} or \texttt{target}.  For example, when the outlet
\begin{verbatim}
<connectors>
 <outlet source="#NSOwner" target="#Controller.name" key="controllerName" />
</connectors>
\end{verbatim}
is established, it's result will likely to be to invoke
\begin{verbatim}
[#NSOwner setControllerName: [#Controller name]];
\end{verbatim}
assuming that \texttt{\#Controller} responds to a method
\texttt{name} (if it doesn't, key-value coding -- as explained 
in the next section -- is used to retrieve the value for key
\texttt{name} of the object \texttt{\#Controller}).

\subsection{Details of how outlet connections are established}
When an outlet connection is established, the following things happen:
\begin{enumerate}
\item the outlet connector determines the source and target objects
  from their ids (by performing a lookup in the name tables which
  store the mappings from ids to objects).  If the ids do not contains
  dots, a simple lookup in the name table is done.  If the source or
  target strings contain a dot, then the advanced key value coding
  support is used: the string is broken in two parts: before and after
  the first dot in the string.  For example,
  \texttt{\#NSController.delegate.name} would be broken into
  \texttt{\#NSController} and \texttt{delegate.name}.  The first part
  of the string is looked up in the name table, producing an object.
  Then, key value coding is used to retrieve the value for the key
  path given by the second string on this object.  In practice, if the
  first part of the string is \texttt{xxx}, and the second part is
  \texttt{yyy}, the \texttt{source} or \texttt{target} is set to the
  result of the following operations:
\begin{verbatim}
[[nameTable objectForKey: xxx] valueForKeyPath: yyy];
\end{verbatim}
  (please check the documentation for \texttt{valueForKeyPath:} to
learn more about this operation).
\item the outlet connector calls
\begin{verbatim}
[source takeValue: target forKey: key];
\end{verbatim}
  to set target as the value for the key key in the source.  If you
  don't know what this really mean, we describe here briefly what this
  does; for more information please read the documentation of the
  \texttt{takeValue:forKey:} method.
\begin{enumerate}
\item if the key is xxx, the system searches for the \texttt{setXxx:}
  method in the source (please note that the first letter of xxx is
  made uppercase).  If that method exists, the following code is
  executed:
\begin{verbatim}
[source setXxx: target];
\end{verbatim}
  and the outlet connection can be considered established.
\item if the method wasn't found, the \texttt{\_setXxx:} method is
  searched, and if it exists is used.
\item if this fails, the system searches an instance variable with
  name \texttt{\_xxx} in the source, and if it finds it, it
  \texttt{ASSIGN}s to it the target\footnote{Unless the class of the
    source has implemented \texttt{+accessInstanceVariablesDirectly}
    to return \texttt{NO}, in which case the system skips trying to
    assign instance variables in this way.}.  Assigning includes
  releasing the previous value, and retaining the new one.
\item if the \texttt{\_xxx} instance variable is not found, the system
  searches for an instance variable called \texttt{xxx}, and tries to
  set that.
\item if even this fails, the system calls the method
  \texttt{-handleTakeValue:forUnboundKey:} of the source, which --
  unless overridden by the source class -- raises an exception.
\end{enumerate}
\end{enumerate}
As you can see, you can automatically set up instance variables of
objects to point to other objects when you load a gsmarkup file.  This is
very handy to establish connections between objects.

\section{The GSMarkup NSBundle Additions API}

\subsection{What is the NSBundle Additions API}
The main API for loading GSMarkup files into a running application is via
the NSBundle GSMarkup Additions.  These are a set of category methods of
NSBundle which allow you to load a gsmarkup file into a running
application, or to get a list of the localizable strings in a gsmarkup
file (this is useful for applications which allow you to manage gsmarkup
files).  The methods are declared in
\begin{verbatim}
Renaissance/GSMarkupBundleAdditions.h
\end{verbatim}
so you need to \texttt{\#include} (or \texttt{\#import}) that file to
use them.  This file is automatically included by
\begin{verbatim}
Renaissance/Renaissance.h
\end{verbatim}
so if you are including the general \texttt{Renaissance.h} header, the
methods are automatically available.  Please note that the API mirrors
the existing NIB loading API which is traditionally found on OpenStep,
with a few additional facilities.

\subsection{A small tweak to get it to work on Microsoft Windows}
If you are only using the NSBundle Additions API, you can have a
problem on Microsoft Windows where you need to reference something
inside a library to get it linked in.  The recommended workaround is
to add the following line (or a similar one) to your program
(typically in your main.m file):
\begin{verbatim}
int (*linkRenaissanceIn)(int, const char **) = GSMarkupApplicationMain;
\end{verbatim}
This defines a (dummy) function pointer called
\texttt{linkRenaissanceInt}, and generates a reference to
\texttt{GSMarkupApplicationMain} which fixes the problem.

\subsection{Methods reference}
We now list each method, followed by the explanation of what the
method does.

\subsubsection{NSBundle methods}
The methods listed in this section are methods of NSBundle.
\begin{verbatim}
+ (BOOL)   loadGSMarkupFile: (NSString *)fileName
          externalNameTable: (NSDictionary *)context
                   withZone: (NSZone *)zone
    localizableStringsTable: (NSString *)table
                   inBundle: (NSBundle *)localizableStringsTableBundle;
\end{verbatim}
This method is the method which does the actual loading; other loading
methods end up calling this one to do the loading.  This method loads
the file \texttt{fileName} (an absolute path) into the application.
If \texttt{fileName} is missing the \texttt{.gsmarkup} extension, it is
automatically appended.  The file is read, and all the sections are
parsed, resulting in a list of objects and of connectors, and a name
table mapping id names to objects which have been decoded.  The
objects are then asked to replace themselves with the corresponding
platform objects, and the name table is updated accordingly.  While
replacing themselves with the platform objects, the objects also
translate the eventual text which might need to be translated by using
the localizable strings given as argument, which is found in the
bundle given as argument.  Each type of objects knows which attributes
or which content requires translation and which don't.  Then, the
\texttt{context} dictionary (which is supposed to contain a mapping of
strings -- id names -- to objects already existing in the application;
typically it contains at least the \texttt{NSOwner} object) is merged
into the name table loaded from the file (except the special key-value
pair with key \texttt{NSTopLevelObjects}, which is not added to the
name table, and it is used later on for another task).  The
connections are finally established using the final name table.  Last,
all platform objects which were decoded from the file, and the
\texttt{NSOwner} object, if it exists, are sent the 
\texttt{awakeFromGSMarkup} method.  The top-level objects so created are
not autoreleased -- so unless they are released at some point, they
will never be deallocated.  This is correct for example for windows,
which are normally released when the user closes them; it is also
correct for some custom objects (the main controller object in the
application), which are supposed to just exist for the whole lifetime
of the application.  But there are cases in which you might need
access to the top-level objects, for example in order to release them.
When Renaissance has loaded the file, it performs a few task which
have the purpose of making the top-level objects available to the
application.  It posts the notification
\begin{verbatim}
GSMarkupBundleDidLoadGSMarkupNotification
\end{verbatim}
with the file owner as object, and a dictionary containing the key
\texttt{NSTopLevelObjects} with value an array containing all the 
top-level objects as user info.  If the file owner responds to the
method
\begin{verbatim}
- (void) bundleDidLoadGSMarkup: (NSNotification *)notification;
\end{verbatim}
this method is automatically called with the notification as its
argument, so you don't need to register the file owner to receive the
notification.  Finally, if the \texttt{context} dictionary contains a
key \texttt{NSTopLevelObjects}, with value a NSMutableArray, this
array is filled with the top-level objects created from the .gsmarkup
file when it is read (for more information on retrieving the top-level
objects, please refer to section \ref{top-level-objects}).
\texttt{zone} is supposed to be the memory zone from which all objects
created when reading the file are allocated; but it is currently
ignored, so you can pass \texttt{NULL} to it.  The strings table and
bundle arguments are used to translate the messages contained in the
objects; if table is nil, the path extension is removed from the
filename, and that is used as string table (so that localizable
strings for the gsmarkup file \texttt{example.gsmarkup} are by default
searched in the localizable strings file
\texttt{example.strings}).  If bundle is nil, the main bundle is used.
The method returns \texttt{YES} if the file could be loaded, and
\texttt{NO} otherwise.

\begin{verbatim}
+ (BOOL) loadGSMarkupFile: (NSString *)fileName
        externalNameTable: (NSDictionary *)context
                 withZone: (NSZone *)zone;
\end{verbatim}
This method is a short form of the previous one; it simply calls it
with nil table and nil bundle, which means that the localizable
strings are translated using the strings table with the same name as
the .gsmarkup file (extension removed) in the main bundle.

\begin{verbatim}
- (BOOL)    loadGSMarkupFile: (NSString *)fileName
           externalNameTable: (NSDictionary *)context
                    withZone: (NSZone *)zone
     localizableStringsTable: (NSString *)table;
\end{verbatim}
This method loads the gsmarkup file with name \texttt{fileName} (NB: if
the \texttt{fileName} string does not have the extension .gsmarkup, it is
automatically added) from the receiver bundle.  The method first
locates the file to load in the bundle, by searching as in the
following example:
\begin{verbatim}
bundle_path/Resources/Italian.lproj/fileName.gsmarkup
bundle_path/Resources/English.lproj/fileName.gsmarkup
bundle_path/Resources/fileName.gsmarkup
bundle_path/Italian.lproj/fileName.gsmarkup
bundle_path/English.lproj/fileName.gsmarkup
bundle_path/fileName.gsmarkup
\end{verbatim}
assuming that \texttt{Italian.lproj} is the user's preferred language.
This algorithm differs from the standard bundle searching algorithm in
that localized resources are preferred to non-localized ones (we're
still all wondering why NSBundle does not have a standard method doing
this by default).  Once the file has been located and its absolute
path on disk is known, the method finally calls the NSBundle method
\begin{verbatim}
     + loadGSMarkupFile:
      externalNameTable:
               withZone:
localizableStringsTable:
               inBundle:
\end{verbatim}
with the given table as table argument, and the receiver bundle as
bundle argument, to perform the actual loading.

\begin{verbatim}
- (BOOL)    loadGSMarkupFile: (NSString *)fileName
           externalNameTable: (NSDictionary *)context
                    withZone: (NSZone *)zone;
\end{verbatim}
This is a short form of the previous method, which uses a nil
localizableStringsTable, which causes the localizable strings file
with the same name as the gsmarkup file (extension removed) to be used as
localizable strings table.

\begin{verbatim}
+ (BOOL) loadGSMarkupNamed: (NSString *)fileName
                     owner: (id)owner;
\end{verbatim}
This method is the more straightforward API to load a gsmarkup file.
\texttt{fileName} should be a file name (including the .gsmarkup
extension or not) (not an absolute path, just a file name);
\texttt{owner} should be an object provided by the application.  Both
must not be nil, otherwise the method immediately returns \texttt{NO}.
The method first builds a context dictionary containing a single
key-value pair, which maps the string \texttt{NSOwner} to the object
\texttt{owner}; then, it gets the owner bundle (if the owner object
belongs to a bundle), or the main bundle (if the owner object does not
belong to a bundle); finally, it invokes the method
\texttt{-loadGSMarkupFile:externalNameTable:withZone:} of that bundle to load
the gsmarkup file.  It uses as zone the owner's zone (but this detail is
currently ignored).  It returns the result of invoking that method.
Localizable strings are by default translated using a table with the
same name as the gsmarkup file (extension removed, so that the localizable
strings file for \texttt{test.gsmarkup} would be \texttt{test.strings}),
from the bundle in which the file is loaded.

\begin{verbatim}
+ (NSArray *) localizableStringsInGSMarkupFile: (NSString *)fileName;
\end{verbatim}
This method parses the \texttt{fileName} file (which should be an
absolute path to a file on disk; if the \texttt{fileName} string does
not end with \texttt{.gsmarkup}, this extension is automatically added),
and it extracts the list of localizable strings in the file.  Each tag
knows exactly which strings found in its attributes and contents are
localizable; the list of localizable strings is built using this
knowledge.

\subsubsection{awakeFromGSMarkup informal protocol}
This section contains a single method, which any object can implement
to perform additional setup after it has been created from a GSMarkup
file.
\begin{verbatim}
- (void) awakeFromGSMarkup
\end{verbatim}
This method is called on the objects created from a GSMarkup file, and
on the file owner (\texttt{NSOwner}), if any, after all connections
(outlets etc) have been established.  You can implement this method to
complete the setup of your objects.

\subsubsection{GSMarkupTopLevelObjects informal protocol}
This section contains a single method, which the file owner can implement
to receive a notification when the gsmarkup is loaded.  The notification
will include an array containing all top-level objects which were loaded
from the gsmarkup file.
\begin{verbatim}
- (void) bundleDidLoadGSMarkup: (NSNotification *)aNotification;
\end{verbatim}

\subsection{Accessing the top-level objects}\label{top-level-objects}
There are basically three ways of accessing the top-level objects created
from a gsmarkup file:
\begin{enumerate}
\item Using one of the NSBundle methods which allow you to set
  manually the \texttt{context} dictionary, and adding a
  \texttt{NSTopLevelObjects} to the \texttt{context} dictionary, with
  value a mutable array.  After loading the gsmarkup, Renaissance will
  store in that dictionary all the top-level objects which have been
  created from the file.  For example:
\begin{verbatim}
NSDictionary *table;
NSMutableArray *topLevelObjects = [NSMutableArray array];

table = [NSDictionary dictionaryWithObjectsAndKeys: 
                                 self, @"NSOwner",
                      topLevelObjects, @"NSTopLevelObjects",
                                  nil];

[NSBundle loadGSMarkupFile: @"MyFile"
         externalNameTable: table
                  withZone: [self zone]];

/* Now topLevelObjects contains the top-level objects which
 * were created from the gsmarkup file.  */
\end{verbatim}
  This method of accessing the top-level objects is similar as the
  method which can be used with NSBundleAdditions, where an
  undocumented Apple extension can be used to get the top-level
  objects by adding a key \texttt{NSTopLevelObjects} with value a
  mutable array to the \texttt{context} dictionary.

\item Implementing a \texttt{-bundleDidLoadGSMarkup:} method in the
  file owner, and retrieving the top-level objects from the
  notification object.  Example:
\begin{verbatim}
- (void) bundleDidLoadGSMarkup: (NSNotification *)aNotification
{
  NSArray *topLevelObjects;
  topLevelObjects = [[aNotification userInfo] objectForKey: 
                                                  @"NSTopLevelObjects"];
  /* Now topLevelObjects contains the top-level objects which
   * were created from the gsmarkup file.  */
}
\end{verbatim}
  There is no equivalent of this method in the traditional NIB loading
  API.

\item Registering some object to receive the notification
\begin{verbatim}
GSMarkupBundleDidLoadGSMarkup
\end{verbatim}
  This is more advanced and more rarely useful; there is no equivalent
  of this method in the traditional NIB loading API.
\end{enumerate}

\subsubsection{Example: loading a single view from a gsmarkup file}
In most cases, a gsmarkup file contains one or more \texttt{<window>}
or \texttt{<panel>} objects.  They are automatically displayed when
the file is loaded and there is nothing you need to do.

In some other cases you may want your gsmarkup file to only contain a
single view tag (such as a \texttt{<vbox>}) that you then want to
programmatically add to an already existing window.  In this case, you
need to access the top-level objects using one of the techniques
explained above.  For example, your gsmarkup file could be:
\begin{verbatim}
<?xml version="1.0"?>
<!DOCTYPE gsmarkup>

<gsmarkup>
  <objects>
    <vbox>
      <button title="Miniaturize" action="performMiniaturize:" />
      <button title="Quit" action="terminate:" />
    </vbox>
  </objects>
</gsmarkup>
\end{verbatim}

If you want to add the \texttt{<vbox>} from that file to an existing
window, you would load it using code such as
\begin{verbatim}
NSDictionary *table;
NSMutableArray *topLevelObjects = [NSMutableArray array];
NSView *vbox;

table = [NSDictionary dictionaryWithObjectsAndKeys: 
                                 self, @"NSOwner",
                      topLevelObjects, @"NSTopLevelObjects",
                                  nil];

[NSBundle loadGSMarkupFile: @"MyFile"
         externalNameTable: table
                  withZone: [self zone]];

vbox = [topLevelObjects objectAtIndex: 0];

/* Now you can do something with vbox, eg, adding it to a window.  */
\end{verbatim}

\section{Integrating Renaissance in your application}
In this part of manual we examine practical issues involved in
integrating Renaissance in your application -- in practice, how to
write an application which uses gsmarkup files for creating menus and
windows.  Our main concern here is teaching you the traps and tricks
involved in switching from nib/gorm files to gsmarkup files.  There is
nothing essentially different: the structure and the organization of
the application is the same; everything is the same except that you
need to load Renaissance files instead of nib ones.  A few details
might confuse you the first time you try to do it -- in this part of
the manual we examine all the details step to step to make sure you
won't get confused or upset by a small silly detail.

\subsection{The application main nib}
Traditionally, an application has a main nib file, and support for
automatically loading this nib file at the application startup is
built into the system libraries.  Because we can't modify the system
libraries, if you are using a gsmarkup file instead of the main nib
file, you will have to load this gsmarkup file manually.  Normally,
you would have a main gsmarkup file creating the main menu, and, if
needed, another one creating the main application window (if there is
one).  We now examine those separately in the next sections.

\subsection{When to load the main menu gsmarkup}\label{integrating-renaissance-menu}
If you are creating the main menu from a gsmarkup file, you need to
load the gsmarkup file as soon as possible, typically in your
\texttt{main} function.  Here is the classical example:
\begin{verbatim}
#include <Foundation/Foundation.h>
#include <AppKit/AppKit.h>
#include <Renaissance/Renaissance.h>

/* Dummy function pointer to get it working on Windows.  */
int (*linkRenaissanceIn)(int, const char **) = GSMarkupApplicationMain;

int main (int argc, const char **argv, char** env)
{
  CREATE_AUTORELEASE_POOL (pool);
  [NSApplication sharedApplication];
  [NSApp setDelegate: [MyApplicationDelegate new]];

  /* Load the menu before calling NSApplicationMain(), because on
   * Apple Mac OS X NSApplicationMain() creates automatically a menu
   * if none is there, and when we try to replace it later, it doesn't
   * really get replaced ... (?)
   *
   * After extensive experiments, loading the menu at this stage is the best
   * way of having it work on both platforms.
   */
#ifdef GNUSTEP
  [NSBundle loadGSMarkupNamed: @"MainMenu-GNUstep"  owner: [NSApp delegate]];
#else
  [NSBundle loadGSMarkupNamed: @"MainMenu-OSX"  owner: [NSApp delegate]];
#endif

  RELEASE (pool);

  return NSApplicationMain (argc, argv);
}
\end{verbatim}
Please note that in the example we have two separate gsmarkup files
for the menu on the different platforms.  While it can be clumsy to do
so, it's certainly the way which works best at the moment -- unless
you know what you are doing, it's recommended that you do it this way
(and that you check/use default template examples of main menu
gsmarkup files).  Finally, we set an instance of an hypothetic
\texttt{MyApplicationDelegate} as the application delegate.  
That is only an example, but implementing an application delegate
custom class can be useful for loading the main window gsmarkup if you
need so, as explained in the next section.

\subsection{When to load the main window gsmarkup}
If you are creating the main window of your application from a
gsmarkup file, I'd suggest to load this file after the application has
been launched.  That makes sure the window can immediately be
displayed on screen.

In practice, you can implement your own application delegate class,
and have it implement the 
\begin{verbatim}
- (void)applicationDidFinishLaunching: (NSNotification *)aNotification;
\end{verbatim}
method.  This method will be called when the application has finished
launching; you can load the main window gsmarkup from there.  For
example:
\begin{verbatim}
@interface MyApplicationDelegate : NSObject
{
  /* ... */
}
- (void)applicationDidFinishLaunching: (NSNotification *)aNotification;
@end

@implementation MyApplicationDelegate
- (void)applicationDidFinishLaunching: (NSNotification *)aNotification
{
  [NSBundle loadGSMarkupNamed: @"MainWindow"  owner: self];  
}
@end
\end{verbatim}
Of course, in your \texttt{main} function, you need to set an instance
of \texttt{MyApplicationDelegate} as the application delegate (as
demonstrated in the previous section).  Please note that this is just
a very simple example: depending on how you are organizing the code in
your application, you might be loading the \texttt{MainWindow} from a
different object, or with a different owner -- as a classical variant,
in \texttt{-applicationDidFinishLaunching:} you could be creating a
controller object, and that object might be loading the gsmarkup file
during initialization.

Renaissance includes full examples of applications demonstrating how
to do all this - the first example you should look at is probably the
CurrencyConverter example -
\begin{verbatim}
/Examples/Applications/CurrencyConverter
\end{verbatim}

\subsection{When to load other gsmarkup files}
You can literally load other gsmarkup files whenever you want.
Typically, you simply do -
\begin{verbatim}
  /* ... code here ... */
  [NSBundle loadGSMarkupNamed: @"HighScores"  owner: self];  
  /* ... more code here ... */
\end{verbatim}
that would load the \texttt{HighScores.gsmarkup} file from the main
bundle, create the window(s) from the file, using self as the owner
(assuming this method call is done inside a method implementation).
The owner used when loading is quite important, because instance
variables of the owner can be set to point to objects in the window
(by using outlets in the gsmarkup file), and vice versa objects in the
window can have some of their instance variables (/attributes) set to
point to the file owner, so it is particularly natural to use as owner
the object which will be interacting more closely and directly with
the window while the program is running.

\subsection{Renaissance and NSDocument-based applications}
The AppKit contains a set of classes (NSDocumentController,
NSDocument, NSWindowController) which are meant to simplify building
document-based application.  The default implementation uses nib/gorm
files to create windows.  Renaissance provides subclasses which behave
exactly in the same way, but they use gsmarkup files to create windows
instead of nib/gorm files.  In the next sections we will examine these
subclasses.

\subsubsection{GSMarkupWindowController}
Renaissance provides \texttt{GSMarkupWindowController} -- a subclass
of NSWindowController which behaves exactly in the same way as
NSWindowController does, but that creates the window from a gsmarkup
file rather than from a nib/gorm file.

So, if you want to use NSWindowController with Renaissance, instead of
using NSWindowController, you just need to use
GSMarkupWindowController; the API is precisely the same.  You can
subclass a GSMarkupWindowController in the same way as you subclass a
NSWindowController.

It's worth making an example of a gsmarkup file which can be loaded by 
a GSMarkupWindowController:
\begin{verbatim}
<?xml version="1.0"?>
<!DOCTYPE gsmarkup>

<gsmarkup>
  <objects>
    <window id="window">
      <!-- ... your code here ... -->
    </window>
  </objects>

  <connectors>
    <outlet source="#NSOwner" target="#window" key="window" />
  </connectors>
</gsmarkup>
\end{verbatim}
Please note the outlet which sets the window outlet of the NSOwner to
the window objects in your file (in practice, it calls
\texttt{[\#NSOwner setWindow: \#window]}) -- it's essential that you have
this outlet in your file, or it won't work.  It's the same outlet that
is required in a nib/gorm file which is meant to be loaded by a 
NSWindowController.

Please refer to the NSWindowController documentation for more information
on using window controllers.

\subsubsection{GSMarkupDocument}
Because the default implementation of NSDocument uses
NSWindowController (which is only able to load nib/gorm files, and not
gsmarkup files), Renaissance provides \texttt{GSMarkupDocument} -- a
subclass of NSDocument which uses GSMarkupWindowController instead of
NSWindowController, and so which uses gsmarkup files instead of
nib/gorm files.  \texttt{GSMarkupDocument} behaves exactly in the same
way as NSDocument, but uses GSMarkupWindowController to load windows
from files.

So, if you want to use Renaissance with NSDocument, instead of using
NSDocument, you just need to use GSMarkupDocument; the API is
precisely the same.  You can subclass a GSMarkupDocument in the same
way as you subclass a NSDocument.

In a typical document-based application, you add entries to the
application \texttt{Info.plist} describing the type of files/documents
that your application can manage (TODO: make examples); you then load
your main menu at startup (as explained in section
\ref{integrating-renaissance-menu}).  Actions in the \texttt{File}
menu will typically be about creating, opening, saving, printing
document.  You should probably start with a standard document menu
copied from a template.

Finally, you implement a subclass of GSMarkupDocument able to
read/write those data; you override \texttt{windowNibName} to return
the name of the gsmarkup file (without the \texttt{.gsmarkup}
extension) to use to create the window which the user can use to edit
the data.  Make sure the gsmarkup file sets the window outlet of the
NSOwner to point to the window (as described/exemplified in the
example code in the previous section).

Please refer to the documentation on NSDocument for more information;
the Renaissance distribution provides complete examples of
document-based application built using Renaissace which can be a
useful starting point -- for example
\begin{verbatim}
Examples/Applications/Ink
Examples/Applications/SimpleEditor
\end{verbatim}


%%
%% Object tag reference
%%

\section{Object tag reference}

In this reference, we document all available tags in an objects
section.  Because new tags can be dynamically added by applications
and bundles, we only document the standard system tags.  The
description of each tag consists of
\begin{itemize}
\item The description of the tag, telling you what the tag is.
\item The list of valid attributes for the tag.  All attributes are
  optional (except in very rare cases which are carefully documented).
  The section tells you what values you can give to each attribute,
  and what the attribute does.  The \texttt{id} attribute is always
  available for all objects so it's not listed here.
\item The list of possible meaningful object attributes for the tag.
  These are converted into outlet connectors at run-time.  The list
  lists standard attributes which take a value which is another object
  (identified by id).  Because of the way object attributes work (by
  setting attributes at run-time using key-value coding), there might
  be more attributes than the ones listed here.
\item A description of what content the tag accepts.
\item One or more example gsmarkup code using the tag.
\item In a few specific cases, a discussion of portability issues.
\end{itemize}

%
% Template for documenting new tags
%

%\subsection{The xxx tag}
%
%\subsubsection{Description}
%A \texttt{<xxx>} tag represents xxx, and normally generates an instance
%of \texttt{XXX}.
%
%\subsubsection{Attributes}
%\begin{itemize}
%\item {\bf ttt}:
%\end{itemize}
%
% The \texttt{<xxx>} tag supports the \texttt{instanceOf} attribute.
%
%\subsubsection{Possible object attributes}
%\begin{itemize}
%\item {\bf ttt}:
%\end{itemize}
%
%\subsubsection{Content}
%
%\subsubsection{Examples}
%
%%OPTIONAL%%
%\subsubsection{Portability}

\subsection{The button tag}

\subsubsection{Description}
A \texttt{<button>} tag represents a button, and normally generates an
instance of \texttt{NSButton}.  The most common attributes to set in a
button are the \texttt{title} (the text displayed in the button), the
\texttt{target} and \texttt{action} (controlling what happens when the
button is clicked).  It's also possible to set the \texttt{image}
attribute to set the image displayed in the button, and to create
different types of buttons by using the \texttt{type} attribute.  Some
of the button types will be highlighted by the system; some others
will display the \texttt{alternateText} and/or \texttt{alternateImage}
when highlighted.

\subsubsection{Attributes}
The \texttt{<button>} tag inherits all attributes from the generic
\texttt{<control>} and \texttt{<view>} tags; in addition, it has 
the following ones:
\begin{itemize}
\item {\bf alternateImage}: The alternate image of the button, if any.
  This is an image attribute.
\item {\bf alternateTitle}: The alternate text of the button, if any.
  This is an optional localized string attribute.
\item {\bf image}: The image of the button (an image).
\item {\bf imagePosition}: The position of the button image (if
  needed).  This attribute is a string, and is optional.  It can be
  set to \texttt{above}, \texttt{below}, \texttt{left},
  \texttt{right}, \texttt{overlaps} and \texttt{imageOnly}.
\item {\bf keyEquivalent}: The keyEquivalent of the button (normally a
  single character).
\item {\bf keyEquivalentModifierMask}: This attribute is a string, and
  is optional; it specifies modifier keys that need to be pressed by
  the user to trigger the key equivalent.  It can be set to
  \texttt{noKey} (the default), \texttt{commandKey},
  \texttt{controlKey} or \texttt{alternateKey}.  In addition to that,
  you can specify combinations of these values by using the \texttt{|}
  character; for example
  \texttt{commandKey\discretionary{|}{}{|}controlKey} will require the
  user to press both Command and Control with the key equivalent to
  trigger the button (see the section on 'Integer Mask Attributes' for
  more info on this syntax).
\item {\bf sound}: The name of the sound to use when the button is
  clicked.  This attribute is a string, and it is optional.  If this
  attribute is set, the sound to play is found using \texttt{[NSSound
  +soundNamed:]}, where the value of this attribute is used as the
  argument.
\item {\bf title}: The text of the button, if any.  This is an
  optional localized string attribute.
\item {\bf type}: The type of button.  This is a string, and can be
  set to \texttt{momentaryPushIn} (a standard button that is
  highlighted when you click, and unhighlighted when the mouse goes
  up), \texttt{momentaryChange} (the same as \texttt{momentaryPushIn},
  but the highlighting is done by displayed the alternate text and
  image), \texttt{pushOnPushOff} (a button that gets pushed on when
  you click, and gets pushed back off when you click again),
  \texttt{toggle} (the same as \texttt{pushOnPushOff}, but the 'pushed
  on' state is shown by displaying the alternate text and image) and
  \texttt{switch} (a stock button that looks like a checkbox; the
  image and alternate image are provided by the system).  If this
  attribute is not set, the default is \texttt{momentaryPushIn}.
\end{itemize}

The \texttt{<button>} tag supports the \texttt{instanceOf} attribute.

\subsubsection{Possible object attributes}
The \texttt{<button>} tag inherits all object attributes from the
generic \texttt{<control>} and \texttt{<view>} tags, but adds no
specific of its own.

\subsubsection{Content}
A \texttt{<button>} tag has no content.

\subsubsection{Examples}
The most common type of \texttt{<button>} tag triggers an action on a
target:
\begin{verbatim}
<button title="Click this button to quit" action="terminate:" target="NSApp" />
\end{verbatim}
In preference panels, it's also common to use switch buttons:
\begin{verbatim}
<window>
 <box title="Advanced Settings">
  <vbox>
   <button title="Enable Caching" type="switch" halign="wexpand" 
           action="preferenceCaching:" target="#NSOwner" />
   <button title="Enable Secure Connections" type="switch" halign="wexpand" 
           action="preferenceConnections:" target="#NSOwner" />
   <button title="Enable Database Connection Pooling" type="switch" 
                                                    halign="wexpand" 
           action="preferencePooling:" target="#NSOwner" />
  </vbox>
 </box>
</window>
\end{verbatim}

\subsection{The colorWell tag}

\subsubsection{Description}

A \texttt{<colorWell>} tag represents a colorWell (a small rectangular
control used to display or choose a color), and normally generates an
instance of \texttt{NSColorWell}.  The most common attribute to set in
a colorWell is the \texttt{color} (the color displayed/edited in the
color well).

\subsubsection{Attributes}
The \texttt{<colorWell>} tag inherits all attributes from the generic
\texttt{<control>} and \texttt{<view>} tags; in addition, it has 
the following ones:
\begin{itemize}
\item {\bf bordered}: A boolean attribute; if set to yes, the color
  well is bordered (the default), else, it's not.
\item {\bf color}: A color attribute -- the color displayed in the
  color well.
\end{itemize}

The \texttt{<colorWell>} tag supports the \texttt{instanceOf} attribute.

\subsubsection{Possible object attributes}
The \texttt{<colorWell>} tag inherits all object attributes from the
generic \texttt{<control>} and \texttt{<view>} tags, but adds no
specific of its own.

\subsubsection{Content}
A \texttt{<colorWell>} tag has no content.

\subsubsection{Examples}
The most common type of \texttt{<colorWell>} tag triggers an action on
a target, and is mostly used in preference panels:
\begin{verbatim}
<window title="Color Preferences">
 <box title="Color Preferences">
  <vbox>
   <hbox halign="right">
    <label>First color:</label>
    <colorWell id="colorWell1" color="red" action="changedColor:" 
                                           target="#NSOwner" />
   </hbox>
   <hbox halign="right">
    <label>Second color:</label>
    <colorWell id="colorWell2" color="blue" action="changedColor:" 
                                            target="#NSOwner" />
   </hbox>
  </vbox>
 </box>
</window>
\end{verbatim}

\subsection{The control tag}

\subsubsection{Description}

A \texttt{<control>} tag represents a control, and normally generates
an instance of \texttt{NSControl}.  Instances of \texttt{NSControl}
are not particularly useful as they are (\texttt{NSControl} instances
represent rectangular regions in a window which display some data and
react to user events), which is why \texttt{<control>} tags are
normally only used with an \texttt{instanceOf} attribute to create
custom control objects.

The attributes of \texttt{<control>} tags are inherited by all tags
whose instances inherit from \texttt{NSControl} -- this includes all
sort of things that you can put inside a window and which display some
data and/or react to user's actions.

\subsubsection{Attributes}
The \texttt{<control>} tag inherits all attributes from the more
generic \texttt{<view>} tag; in addition, it has the following
attributes:
\begin{itemize}
\item {\bf action}: The action of the control.  This attribute is a
  string (non localizable), and it's optional.  The string is
  converted into a selector at run time; the selector is then set as
  the control's action.  The control's action is the method (of a
  suitable target object) which is typically invoked when the control
  is activated.  If missing (or if the specified selector can't be
  found), a \texttt{NULL} action is used.  Please note that the string
  should include the \texttt{`:'} at the end; for example,
  \texttt{action="terminate:"}.
\item {\bf continuous}: This attribute is a boolean; it is optional;
  if set to \texttt{yes}, the control will send its action
  continuously; if set to \texttt{no}, it does not.
\item {\bf enabled}: This attribute is a boolean; it is optional; if
  set to \texttt{yes} it enables the control, if set to \texttt{no} it
  disables it.
\item {\bf font}: This attribute is a font string; it is optional; if
  set, it determines what font is used to display the text (if any)
  displayed by the control.  See the discussion on font attributes for
  possible values.
\item {\bf sendActionOn}: This attribute is a string, and is optional.
  It can be set to \texttt{leftMouseUp}, \texttt{leftMouseDown},
  \texttt{leftMouseDragged} or \texttt{periodic}.  In addition to
  that, you can specify combinations of these values by using the
  \texttt{|} character; for example \texttt{leftMouseDown\discretionary{|}{}{|}leftMouseUp}
  will send the action when the left mouse button is pressed or
  released (see the section on 'Integer Mask Attributes' for more info
  on this syntax).
\item {\bf tag}: This is the tag of the control.  It is an integer,
  and it is optional.  A tag is used to mark the control usually so
  that it can be distinguished from other controls at run time.
\item {\bf textAlignment}: The alignment of the text (if needed).
  This attribute is a string, and is optional.  It can be set to
  \texttt{left}, \texttt{center}, or \texttt{right}.  If you specify a
  size for the \texttt{<control>} tag which is bigger than the size of
  the text (if any) to be displayed in the control view, this
  specifies how the text is aligned.
\end{itemize}

The \texttt{<control>} tag supports the \texttt{instanceOf} attribute.

\subsubsection{Possible object attributes}
The \texttt{<control>} tag inherits all object attributes from the
generic \texttt{<view>}, and adds the following ones:
\begin{itemize}
\item {\bf target}: The target of the control.
\end{itemize}

\subsubsection{Content}
None.

\subsubsection{Examples}
In practice, \texttt{<control>} tags are rarely used.  The only good
reason to use a \texttt{<control>} tag in practice is to create an
instance of a custom subclass of \texttt{NSControl}:
\begin{verbatim}
<control instanceOf="MapView" action="clickOnMap:" target="#NSOwner" 
         width="400" height="400" />
\end{verbatim}

While \texttt{<control>} tags are rarely used, many common tags
inherit attributes from \texttt{<control>}; for example, buttons
inherit the \texttt{<control>} attributes, in particular the
\texttt{action}, \texttt{target} and \texttt{enabled} attributes used
to control how the control reacts to user actions (very common for
buttons), but also the \texttt{font} and \texttt{textAlignment}
attributes that control how the text is displayed (very common for
labels and textfields).

\subsection{The hbox tag}

\subsubsection{Description}
A \texttt{<hbox>} tag represents an invisible horizontal autolayout
container that can hold other views, and normally generates an
instance of \texttt{GSAutoLayoutHBox}.

There are two types of boxes:
\begin{itemize}
\item {\bf standard}: This type of box does the layout by just placing
  horizontally the views in their minimum size, one after the other
  one, in a row.  Any view marked with an halign of expand or wexpand
  is then expanded to make sure the \texttt{<hbox>} takes up all the
  space allocated to it.  If no views are marked as expand or wexpand,
  then the \texttt{<hbox>} itself won't be expanding.
\item {\bf proportional}: This type of box does the layout by placing
  horizontally the views in the minimum size, one after the other one,
  in a row; then all segments are made of the same size by computing
  an appropriate layout unit that makes all segments bigger than their
  minimum size, and that fills up the entire row.  Views that are
  marked as expanding in the horizontal direction will expand to take
  up their entire segments; other views will be aligned inside their
  segment according to their halign flag.  A view can also have a
  \texttt{proportion} attribute set, which will cause it to cover a
  different number of layout units.  By default, all views have
  proportion=1.
\end{itemize}

Normally you should use standard boxes unless you are trying to
recreate some eye-pleasing special alignment, such as a row of buttons
which are all of the same size, in which case you probably need a
proportional box.

\subsubsection{Attributes}
The \texttt{<hbox>} tag inherits all attributes from the generic
\texttt{<view>} tag; in addition, it has the following ones:
\begin{itemize}
\item {\bf type}: The type of box; this attribute is a string, and is
  optional.  It can be 'standard' (the default) or 'proportional'.  A
  standard box resize views to fit; there is no particular
  relationship between the widths of the various views.  A
  proportional box instead holds views which have a width that is
  proportional to a layout unit (normally each view takes up 1 layout
  unit; this can be changed by specifying a 'proportion' attribute for
  some of them).  If nothing is specified, the box is by default
  created as a standard box.
\end{itemize}
The \texttt{<hbox>} tag supports the \texttt{instanceOf} attribute.

\subsubsection{Possible object attributes}
The \texttt{<hbox>} tag inherits all object attributes from the
generic \texttt{<view>} tag but has none of its own.

\subsubsection{Content}
A \texttt{<hbox>} tag has its subviews as its content.  They are
created in the order they are listed, and displayed from left to
right.

\subsubsection{Examples}
\texttt{<hbox>} are one of the basic autolayout containers and are
extremely common.  In most cases, they have no attributes and only
have content (consisting of the subviews they manage).  Here is an
example with two buttons in a row:
\begin{verbatim}
<hbox>
  <button title="Miniaturize" action="performMiniaturize:" />
  <button title="Close" action="performClose:" />
</hbox>
\end{verbatim}
Note how the buttons are created from left to right as listed in the
XML file, so the 'Miniaturize' button will be on the left of the
'Close' button.

Here is the same example where the buttons are automatically sized
to have exactly the same size:
\begin{verbatim}
<hbox type="proportional">
  <button title="Miniaturize" action="performMiniaturize:" />
  <button title="Close" action="performClose:" />
</hbox>
\end{verbatim}

It is quite possible and common to nest \texttt{<hbox>} and
\texttt{<vbox>} tags to create more complex layouts, as in the
following example where a textfield is on top of a row
of buttons:
\begin{verbatim}
<vbox>
  <hbox>
    <label>Name:</label>
    <textField id="name" width="150" />
  </hbox>
  <hbox type="proportional" halign="right">
    <button title="Cancel" action="cancel:" halign="wexpand" />
    <button title="OK" action="submit:" halign="wexpand" />
  </hbox>
</vbox>
\end{verbatim}

\subsection{The hspace tag}

\subsubsection{Description}

A \texttt{<hspace>} tag represents invisible horizontal
weakly-expanding space that can be put into autolayout containers such
as \texttt{<hbox>} objects for alignment purporses.  It normally
generates an instance of \texttt{GSAutoLayoutHSpace}.

An \texttt{<hspace>} has zero size by default, but expands
horizontally if there is horizontal space available.  You can use it
to fill any void space created by the layout and keep non-expanding
views aligned.

Please note in vertical boxes (\texttt{<vbox>}) you should use
vertical spaces (\texttt{<vspace>}); it does not really make sense to
put a \texttt{<hspace>} inside a \texttt{<vbox>} since the
\texttt{<hspace>} only expand horizontally, not vertically.

\subsubsection{Attributes}
The \texttt{<hspace>} tag inherits all attributes from the generic
\texttt{<view>} tag but adds no new attributes of its own.

The \texttt{<hspace>} tag supports the \texttt{instanceOf} attribute.

\subsubsection{Possible object attributes}
The \texttt{<hspace>} tag inherits all object attributes from the
generic \texttt{<view>} tag but has none of its own.

\subsubsection{Content}
A \texttt{<hspace>} tag has no content.

\subsubsection{Examples}
\texttt{<hspace>} can be a nice simple tool to get autolayout done
quickly and effectively.  Technically, they can almost always be
replaced with more sophisticated choice of the halign attributes, but
their simplicity and clarity often makes them the better alternative.

For example, the following example shows a horizontal box containing
a button.  In its minimum size, the button takes up all the space.
If the box is expanded, the space that is created is taken by the
\texttt{<hspace>}, so the button always remains at the right end
of the \texttt{<hbox>}:
\begin{verbatim}
<hbox>
  <hspace />
  <button title="Close" action="performClose:" />
</hbox>
\end{verbatim}

\texttt{<hspace>} tags rarely have any attributes and have never
any content.


\subsection{The image tag}

\subsubsection{Description}
An \texttt{<image>} tag represents an image, and normally generates an
instance of \texttt{NSImageView}.  An \texttt{NSImageView} is a
control which is used to display an image.  Normally, you specify the
image by putting an \texttt{name="xxx"} attribute into the tag, and
the \texttt{NSImageView} is automatically sized to fit the image.  The
value of the \texttt{name} attribute is a string, which is used as
argument to the \texttt{NSImage} method \texttt{+imageNamed:}.
Typically you put the image (as a .png, or .gif, or .jpeg , or .tiff
file) in the main application bundle.

If all you want to do is display an image from a file, this is all you
need to know; but there are more complex situations which might
require more control: for example, you can change the image
programmatically later (by calling \texttt{-setImage:} of the
\texttt{NSImageView}), after the file has been loaded; or you can
force a size of the image view (by using the \texttt{width} and
\texttt{height} attributes which the \texttt{<image>} tag inherits 
from the generic \texttt{<view>} tag), which might be different from
the size of the image contained in the file; or you can set the image
view to be editable (by setting \texttt{editable="yes"}), and then the
user can change the image by dragging\&dropping images from elsewhere.

In all those advanced cases, you can easily end up with an image view
of a size which is different from the size of the image to be
displayed in the view.  Usually the image is then automatically
scaled, but you can decide how the scaling is to be done by using the
\texttt{scaling} attribute, and how to align the image in the area (if
not all of it is covered after the specified scaling) by using the
\texttt{alignment} attribute.  Please check the \texttt{NSImageView} 
documentation for more information on scaling and alignment.

\subsubsection{Attributes}
The \texttt{<image>} tag inherits all attributes from the generic
\texttt{<control>} and \texttt{<view>} tags; in addition, it has 
the following ones:
\begin{itemize}
\item {\bf imageAlignment}: The alignment (if needed).  This attribute
  is a string, and is optional.  It can be set to \texttt{bottom},
  \texttt{bottomLeft}, \texttt{bottomRight}, \texttt{center},
  \texttt{left}, \texttt{right}, \texttt{top}, \texttt{topLeft} or
  \texttt{topRight}.  If you specify a size for the \texttt{<image>}
  tag which is bigger than the size of the image to be displayed in
  the image view, this specifies how the image is aligned after having
  been scaled.
\item {\bf frameStyle}: The type of frame (if used).  This attribute
  is a string, and it is optional.  It can be set to \texttt{button},
  \texttt{grayBezel}, \texttt{groove}, \texttt{none} or
  \texttt{photo}.  Those frame styles will likely look different on
  different platforms, and they might no longer be available in future
  releases of some of the platforms.  For this reason if possible you
  should avoid to set a frame style manually; if you want a frame, it
  is recommended that you just set \texttt{hasFrame="yes"} and let the
  system choose the natural native frame style, whatever that is.
\item {\bf hasFrame}: A boolean: if set to \texttt{yes}, a frame will
  be drawn around the image; the frame usually consists of a border or
  bezel line around the image.  This attribute is optional; if
  omitted, no frame is drawn.
\item {\bf name}: The name name of the image to display.  This
  attribute is a string, and it is optional, but generally you should
  have it unless you are setting an image programmatically later.  If
  this attribute is set, the image to display is found using
  \texttt{[NSImage +imageNamed:]}, where the value of this attribute
  is used as the argument; if this attribute is not set, no image is
  actually displayed.
\item {\bf scaling}: The type of scaling (if needed).  This attribute
  is a string, and it is optional.  It can be set to \texttt{none},
  \texttt{proportionally} or \texttt{toFit}.  It determines how the
  image is scaled if the frame size for the image view is different
  from the size of the image to display in the image view.
\end{itemize}

The \texttt{<image>} tag supports the \texttt{instanceOf} attribute.

\subsubsection{Possible object attributes}
The \texttt{<image>} tag inherits all object attributes from the
generic \texttt{<control>} and \texttt{<view>} tags, but adds no
specific of its own.

\subsubsection{Content}
An \texttt{<image>} tag has no content.

\subsubsection{Examples}
In the typical usage, you have an image in your main application
bundle called for example \texttt{GreenArrow.png}.  To display the
image in a window, you can use the \texttt{<image>} tag:
\begin{verbatim}
<image name="GreenArrow" />
\end{verbatim}

\subsection{The instance tag}

\subsubsection{Description}
An \texttt{<instance>} tag represents an instance of a custom class.  You
specify the custom class and an object of that class is created.

\subsubsection{Attributes}
\begin{itemize}
\item {\bf instanceOf}: The name of the class.  This attribute is a
  string, and is required.
\end{itemize}

\subsubsection{Possible object attributes}
This depends on the class -- each class has different object attributes.

\subsubsection{Content}
No content.

\subsubsection{Examples}
Normally, you set the id of your object, because you are referring to
it somewhere else.  You also might set additional object attributes to
connect the object to other objects.
\begin{verbatim}
<instance instanceOf="MyController" id="Controller" 
          textField="#TextField" />
\end{verbatim}
in this example, the class \texttt{MyController} should have the method
\texttt{setTextField:}.

\subsection{The label tag}

\subsubsection{Description}
A \texttt{<label>} tag represents a non-editable string displayed
inside the window; it normally generates an instance of
\texttt{NSTextField} configured to be non-editable and with no border.

The content of the tag represent the (localized) string to be
displayed; you can change the font, text and background color by using
the corresponding attributes.

A \texttt{<label>} tag draws its background if and only if the
\texttt{backgroundColor} attribute is set.

\subsubsection{Attributes}
A \texttt{<label>} inherits all the attributes of the \texttt{<view>}
and \texttt{<control>} tags; moreover, it supports the following ones:
\begin{itemize}
\item {\bf backgroundColor}: a color attribute that determines the
  color of the background.  If not set, no special background is
  drawn; if set, a background of the specified color is drawn.
\item {\bf textColor}: a color attribute that determines the color
  used to draw the text.
\item {\bf selectable}: a boolean attribute that determines if the
  label is selectable or not; that is, if the user can select the text
  in the label (for example, for copy and paste).  Labels are
  selectable by default so that users can copy and paste messages from
  GUI interfaces (for example, so that they can copy and paste error
  messages from a panel).
\end{itemize}

The \texttt{<label>} tag supports the \texttt{instanceOf} attribute.

\subsubsection{Possible object attributes}
The \texttt{<label>} tag inherits all object attributes from the
generic \texttt{<control>} and \texttt{<view>} tags, but adds no
specific of its own.

\subsubsection{Content}
The content of a \texttt{label} tag is the localized string that is
displayed by the label.

\subsubsection{Examples}
In most cases, a \texttt{label} tag works very well with no attributes:
\begin{verbatim}
<label>Path to the executable</label>
\end{verbatim}

The most common attribute for labels is the \texttt{font} attribute,
as in the following example showing labels with different fonts:
\begin{verbatim}
<window>
  <vbox>
    <label font="big">Big font</label>
    <label>Normal font</label>
    <label font="small">Small font</label>
  </vbox>
</window>
\end{verbatim}

You may also want to set the color and/or background:
\begin{verbatim}
<label textColor="blue" backgroundColor="white">Blue on white</label>
\end{verbatim}

\subsection{The menu tag}

\subsubsection{Description}
A \texttt{<menu>} tag represents a menu, and normally generates an
instance of \texttt{NSMenu}.

\subsubsection{Attributes}
\begin{itemize}
\item {\bf autoenablesItems}: A boolean: if set to \texttt{no},
  disables autoenabling of its menu items (which is otherwise enabled
  by default).
\item {\bf title}: The title of the menu (a localizable string).
\item {\bf type}: If set to \texttt{main}, then the menu is made the
  application main menu (by invoking \texttt{setMainMenu:} of the
  shared \texttt{NSApplication}).  If set to \texttt{windows}, then
  the menu is made the application windows menu (by invoking
  \texttt{setWindowsMenu:} of the shared \texttt{NSApplication}).  If
  set to \texttt{services}, then the menu is made the application
  services menu (by invoking \texttt{setServicesMenu:} of the shared
  \texttt{NSApplication}).  If set to \texttt{font}, then the menu is
  created as the font menu (by using the menu \texttt{fontMenu:} of
  the shared \texttt{NSFontManager}); in this case, the standard menu
  items for the font menu are automatically added when then menu is
  first created; if you specify any menu or menu item as content for
  the tag, they are added in addition to the default ones.  If set to
  \texttt{apple}, then the menu is made the application apple menu (by
  invoking \texttt{setAppleMenu:} of the shared
  \texttt{NSApplication}); if running on Apple Mac OS X; it is ignored
  otherwise.
\end{itemize}

The \texttt{<menu>} tag does not support the \texttt{instanceOf} attribute.

\subsubsection{Possible object attributes}
None.

\subsubsection{Content}
A menu can contain \texttt{menuItem}, \texttt{menuSeparator} and
\texttt{menu} tags.  Each \texttt{menuItem} tag represents a menu item
which is added to the menu.  Each \texttt{menuSeparator} tag
represents a menu separator which is added to the menu.  Each
\texttt{menu} represents a submenu.

\subsubsection{Examples}
Normally, the only attribute of menus you're likely to use is the 
\texttt{type} attribute, which is used to make a menu the main, windows, 
services or font menu.
\begin{verbatim}
<menu type="main">
  <menuItem title="Info Panel..." action="orderFrontStandardInfoPanel:" />
  <menuItem title="Hide" action="hide:" keyEquivalent="h" />
  <menuItem title="Quit" action="terminate:" keyEquivalent="q" />
</menu>
\end{verbatim}

Here is an example of a menu holding a submenu:
\begin{verbatim}
<menu type="main">
  <menu title="Info">
    <menuItem title="Info Panel..." action="orderFrontStandardInfoPanel:" />
    <menuItem title="Preferences..." action="runPreferencesPanel:" />
    <menuItem title="Help..." action="orderFrontHelpPanel:" />
  </menu>
  <menuItem title="Hide" action="hide:" keyEquivalent="h" />
  <menuItem title="Quit" action="terminate:" keyEquivalent="q" />
</menu>
\end{verbatim}
Technically, to add the submenu, Renaissance automatically creates a
menu item, adds it to the parent menu, then set the submenu as the
menu item's submenu.  You can ignore this process.

\subsubsection{Portability}
Menu portability is quite tricky.  Because there are many differences
between how the application main menus are organized on different
platforms, and what the standard names/locations used in menus are, it
is common to keep the application main menu in a separate gsmarkup
file, and to have a different gsmarkup file for each different
platform; then loading the appropriate file depending on the platform
you are running on.

In order to have your code work well across different platforms, it is
also recommended that you load the main application menu gsmarkup file
inside your \texttt{main()} function, before calling
\texttt{NSApplicationMain()} (if you call it).  On Apple Mac OS X it is
also quite important to set the type (main, apple ...)  of the menus.
The essential thing is that there should be a single \texttt{main}
menu, containing the \texttt{apple} submenu as its first item.  There
should be one, and only one, \texttt{apple} submenu.  The simplest
(and probably best) way to get it right without too much effort is by
doing what working examples are doing (such as the CurrencyConverter
example, located inside
\texttt{Examples/Applications/CurrencyConverter} in the Renaissance
distribution).

\subsection{The menuItem tag}

\subsubsection{Description}
A \texttt{<menuItem>} tag represents a menu item to be added to a menu,
and normally generates an instance of \texttt{NSMenuItem}.

\subsubsection{Attributes}
\begin{itemize}
\item {\bf action}: The action of the menuItem (a string, non
  localized, which is converted into a selector).
\item {\bf enabled}: A boolean; if \texttt{no}, the menuItem is
  disabled (it is enabled by default).  If your menu autoenables its
  items, this is not particularly useful.
\item {\bf image}: The image of the menuItem (an image).
\item {\bf keyEquivalent}: The keyEquivalent of the menuItem (normally
  a single character).
\item {\bf keyEquivalentModifierMask}: This attribute is a string, and
  is optional; it specifies modifier keys that need to be pressed by
  the user to trigger the key equivalent (the default if you specify
  nothing is \texttt{commandKey}).  It can be set to \texttt{noKey},
  \texttt{shiftKey}, \texttt{commandKey}, \texttt{controlKey} or
  \texttt{alternateKey}.  In addition to that, you can specify
  combinations of these values by using the \texttt{|} character; for
  example \texttt{commandKey\discretionary{|}{}{|}controlKey} will
  require the user to press both Command and Control with the key
  equivalent to trigger the button (see the section on 'Integer Mask
  Attributes' for more info on this syntax).
\item {\bf state}: The state of the menuItem (either \texttt{on}, or
  \texttt{off} or \texttt{mixed}).  Setting a state for the menuItem
  automatically causes the menuItem to display its state (on/off)
  ... at least on GNUstep it is so, and it is done using a tickmark.
\item {\bf tag}: The tag of the menuItem (an integer).
\item {\bf title}: The title of the menuItem (a localizable string).
\end{itemize}

The \texttt{<menuItem>} tag does not support the \texttt{instanceOf} attribute.

\subsubsection{Possible object attributes}
\begin{itemize}
\item {\bf target}: The target of the menuItem.
\item {\bf representedObject}: The representedObject of the menuItem.
\end{itemize}

\subsubsection{Content}
A menuItem has no content.

\subsubsection{Examples}
In most cases, you just set title, action and keyEquivalent of menu items (in
some cases not even those).  The classical menu item is the Quit menu
item of the main menu:
\begin{verbatim}
<menuItem title="Quit" action="terminate:" />
\end{verbatim}
Here is an example of a menuItem displaying an on/off tickmark and
changing state:
\begin{verbatim}
<menu title="Options">
  <menuItem title="Full Headers" state="on" action="fullHeadersChanged:" />
  <menuItem title="Hide spam" state="on" action="hideSpamChanged:" />
</menu>
\end{verbatim}
You need to implement the actions, and have them change the state of the
menuItem each time, to see the state change.

\subsection{The menuSeparator tag}

\subsubsection{Description}
A \texttt{<menuSeparator>} tag represents a separator in a menu, and
normally inserts into the menu a \texttt{[NSMenuItem separatorItem]}.
It is a very simple tag, with no attributes nor content; it is opened,
and immediately closed, as in
\begin{verbatim}
<menuSeparator />
\end{verbatim}
It can only be used inside the contents of a menu.  It is usually
represented by a \texttt{[NSMenuItem separatorItem]} object, but that
is not compulsory -- it can be mapped to whatever standard way of
inserting separators in NSMenus is used on that platform.

\subsubsection{Attributes}
A \texttt{menuSeparator} tag has no attributes.  The
\texttt{<menuSeparator>} tag does not support the \texttt{instanceOf}
attribute.

\subsubsection{Possible object attributes}
A \texttt{menuSeparator} tag has no possible object attributes.

\subsubsection{Content}
A \texttt{menuSeparator} tag has no content.

\subsubsection{Examples}
A menuSeparator is often used on Apple Mac OS X to visually separate and
group menu items in menus, as in the following example:
\begin{verbatim}
<menu type="main">

  <menu title="CurrencyConverter" type="apple">
    <menuItem title="About CurrencyConverter" 
             action="orderFrontStandardAboutPanel:" />
    <menuSeparator />
    <menu title="Services" type="services" />
    <menuSeparator />
    <menuItem title="Hide CurrencyConverter" 
             action="hide:" keyEquivalent="h" />
    <menuItem title="Hide Others" 
             action="hideOtherApplications:" />
    <menuItem title="Show All" 
             action="unhideAllApplications:" />
    <menuSeparator />
    <menuItem title="Quit CurrencyConverter" 
             action="terminate:" keyEquivalent="q" />
  </menu>
</menu>
\end{verbatim}

\subsection{The panel tag}

\subsubsection{Description}
A \texttt{<panel>} tag represents a panel, and normally generates an
instance of \texttt{NSPanel}.  The panel tag inherits from the window
tag, so it inherits all attributes available for a window.  The only
different with a window tag is that it creates a \texttt{NSPanel}
instead of a \texttt{NSWindow} object, and that it has a few more
attributes, specific to panels.

\subsubsection{Attributes}
All the attributes recognized by the \texttt{<window>} tag, plus:
\begin{itemize}
\item {\bf becomesKeyOnlyIfNeeded}: A boolean.  If set to yes, sets
  the panel to become key only if needed.
\item {\bf floating}: A boolean.  If set to yes, sets the panel to be
  a floating panel.
\item {\bf worksWhenModal}: A boolean.  If set to yes, sets the panel
  to work when modal.
\end{itemize}

The \texttt{<panel>} tag supports the \texttt{instanceOf} attribute.

\subsubsection{Possible object attributes}
The same possible object attributes as for the \texttt{<window>} tag.

\subsubsection{Content}
The same content as the \texttt{<window>} tag.

\subsubsection{Examples}
\begin{verbatim}
  <panel title="Inspector" autosaveName="Inspector" floating="yes">
    <vbox>
      <!-- all sort of goodies go in here -->
    </vbox>
  </panel>
\end{verbatim}

\subsection{The secureTextField tag}

\subsubsection{Description}
A \texttt{<secureTextField>} tag represents a secure, editable text
field displayed inside the window, apt to be used to type passwords
and other sensitive information; it normally generates an instance of
\texttt{NSSecureTextField} configured to be editable, selectable and
with the distinctive appearance of a secure, editable text field.

The only difference between a \texttt{<secureTextField>} tag and a
\texttt{<textField>} one is that a \texttt{<secureTextField>} creates
an instance of \texttt{NSSecureTextField}, which is a special text
field that doesn't display what is being typed into it; it usually
displays bullets or other similar symbols to show that something is
being typed, without actually revealing it.

\subsubsection{Attributes}
A \texttt{<secureTextField>} has exactly the same attributes as a
\texttt{<textField>} tag.

\subsubsection{Possible object attributes}
A \texttt{<secureTextField>} has exactly the same possible object
attributes as a \texttt{<textField>} tag.

\subsubsection{Content}
A \texttt{<secureTextField>} has exactly the same content as a
\texttt{<textField>} tag.

\subsubsection{Examples}
In most cases, a \texttt{secureTextField} tag works very well with no
attributes, or with a minimal width set:
\begin{verbatim}
<hbox><label>Password:</label> <secureTextField width="200" /></hbox>
\end{verbatim}
For more examples, see the description of \texttt{<textField>}.

\subsection{The textField tag}

\subsubsection{Description}
A \texttt{<textField>} tag represents an editable text field displayed
inside the window; it normally generates an instance of
\texttt{NSTextField} configured to be editable, selectable and with
the distinctive appearance of an editable text field.

You can also make the control non-editable or non-selectable by using
the corresponding attributes.

The content of the tag represent the (localized) string to be
displayed; you can change the font, text and background color by using
the corresponding attributes.

\subsubsection{Attributes}
A \texttt{<textField>} inherits all the attributes of the
\texttt{<view>} and \texttt{<control>} tags; moreover, it supports the
following ones:
\begin{itemize}
\item {\bf allowsEditingTextAttributes}: a boolean attribute.  When
  set to yes, the user can edit the font and text attributes of the
  text displayed in the text field.
\item {\bf backgroundColor}: a color attribute that determines the
  color of the background.
\item {\bf drawsBackground}: a boolean attribute that controls whether
  the text field draws its background or not.  Useful in conjunction
  with 'backgroundColor' if you want to control the text field colors.
\item {\bf editable}: a boolean attribute that determines if the text
  field is editable or not (that is, if the user can edit the text
  within the text field).  Text fields are editable by default.
\item {\bf importsGraphics}: a boolean attribute.  When set to yes,
  the user can drag image files into the text field.
\item {\bf selectable}: a boolean attribute that determines if the
  text field is selectable or not (that is, if the user can select the
  text within the text field, for example for copy and paste).  Text
  fields are selectable by default.
\item {\bf textColor}: a color attribute that determines the color
  used to draw the text.
\end{itemize}

The \texttt{<textField>} tag supports the \texttt{instanceOf} attribute.

\subsubsection{Possible object attributes}
The \texttt{<textField>} tag inherits all object attributes from the
generic \texttt{<control>} and \texttt{<view>} tags, and adds:
\begin{itemize}
\item {\bf delegate}: The delegate of the text field (see the
  documentation of the NSTextField class for more information on using
  delegates).
\end{itemize}

\subsubsection{Content}
The content of a \texttt{textField} tag is the localized string that
is displayed in the text field.

\subsubsection{Examples}
In most cases, a \texttt{textField} tag works very well with no attributes:
\begin{verbatim}
<hbox><label>Name:</label> <textField /></hbox>
\end{verbatim}

Sometimes you may want to set the \texttt{delegate} attribute if you
want your software to be informed in real-time of changes to the text
field contents:
\begin{verbatim}
<hbox><label>Name:</label> <textField delegate="#NSOwner" /></hbox>
\end{verbatim}
You then need to implement the appropriate text field delegate methods
in your file owner object.

\subsection{The vbox tag}

\subsubsection{Description}
A \texttt{<vbox>} tag represents an invisible vertical autolayout
container that can hold other views, and normally generates an
instance of \texttt{GSAutoLayoutHBox}.

A \texttt{<vbox>} object is identical to a \texttt{<hbox>} object, but
it holds views in a column instead of a row.  Please refer to the
description of the \texttt{<hbox>} tag for details of the tag.

\subsubsection{Attributes}
The \texttt{<vbox>} tag inherits all attributes from the generic
\texttt{<view>} tag; in addition, it has the following ones:
\begin{itemize}
\item {\bf type}: The type of box; this attribute is a string, and is
  optional.  It can be 'standard' (the default) or 'proportional'.  A
  standard box resize views to fit; there is no particular
  relationship between the heights of the various views.  A
  proportional box instead holds views which have a height that is
  proportional to a layout unit (normally each view takes up 1 layout
  unit; this can be changed by specifying a 'proportion' attribute for
  some of them).  If nothing is specified, the box is by default
  created as a standard box.
\end{itemize}
The \texttt{<vbox>} tag supports the \texttt{instanceOf} attribute.

\subsubsection{Possible object attributes}
The \texttt{<vbox>} tag inherits all object attributes from the
generic \texttt{<view>} tag but has none of its own.

\subsubsection{Content}
A \texttt{<vbox>} tag has its subviews as its content.  They are
created in the order they are listed, and displayed from top to
bottom.

\subsubsection{Examples}
See the examples for the \texttt{<hbox>} tag.

\subsection{The view tag}

\subsubsection{Description}
A \texttt{<view>} tag represents a view, and normally generates an
instance of \texttt{NSView}.  Instances of \texttt{NSView} are not
particularly useful as they are (\texttt{NSView} instances represent
rectangular regions in a window, and don't do much), which is why
\texttt{<view>} tags are normally only used with an \texttt{instanceOf}
 attribute to create custom view objects.

The attributes of \texttt{<view>} tags are inherited by all tags whose
instances inherit from \texttt{NSView} -- this includes anything you
can put inside a window.  Of particular interest is the autolayout
behaviour, which is again inherited by all tags.

When the view instance created by a \texttt{<view>} tag is
initialized, the method \texttt{sizeToFitContent} of the instance is
first called.  This method resizes the instance to fit its content.
Then, the \texttt{x}, \texttt{y} \texttt{height} and \texttt{width}
attributes of the tag are checked; if one of them is set, the
corresponding part of the frame of the view is overridden with the
attribute value.  This means that any setting of \texttt{x},
\texttt{y}, \texttt{height} or \texttt{width} overrides the
automatically computed size and position.

If the view is inserted into an autolayout container, the view can
have additional attributes which are used by the autolayout container
to manage the view properly.  These attributes are \texttt{halign},
\texttt{valign}, \texttt{hborder}, \texttt{vborder} and \texttt{span}.  
There is also an additional attribute \texttt{border}, which is a
currently a short-cut for setting both the \texttt{hborder} and
\texttt{vborder} attributes (and might be removed in the future).

Reasonable values for those attributes are automatically guessed by
the autolayout system, so you only need to set them when the default
values are not satisfactory for you.  \texttt{halign} and
\texttt{valign} control the way the view is aligned and expanded 
horizontally and vertically inside the layout container and in
relationship with other views in the container; \texttt{hborder} and
\texttt{vborder} control the horizontal and vertical border around the
view when in the container; \texttt{span} is used with proportional
boxes, for special effects when a view spans more than a single slot
in the box.

The system will also set default values for the
\texttt{autoresizingMask} basing on the autolayout properties, so that
if you put your view inside an old-fashioned container such as a
\texttt{<box>}, you can control its autoresizing behaviour using the
usual autolayout flags.

\subsubsection{Attributes}
\begin{itemize}
\item {\bf autoresizesSubviews}: A boolean.  This flag is only used by
  the default (legacy) autoresizing system in OpenStep platforms; if
  you are using Renaissance's autolayout and autosizing (which is much
  more advanced), you should never touch the view's autoresizing mask
  as you could cause all sort of confusion and mess by mixing the two
  autoresizing systems.  Setting the flag to yes or no causes the
  -setAutoresizesSubviews: method to be called on the view.
\item {\bf autoresizingMask}: A string.  The autoresizing mask is used
  by the default (legacy) autoresizing system in OpenStep platforms;
  if you are using Renaissance's autolayout and autosizing (which is
  much more advanced), you should never touch the view's autoresizing
  mask as you could cause all sort of confusion and mess by mixing the
  two autoresizing systems.  Also, setting the standard autolayout
  flags \texttt{halign} and \texttt{valign} automatically sets the
  autoresizing mask to an appropriate corresponding value, so even if
  you need to use an autoresizing mask, you may want to use
  \texttt{halign} and \texttt{valign}.  If this attribute is
  set, it is used to manually override the default autoresizing mask
  with the one provided; the string is a list of bits to set in the
  autoresizing mask: every character represents a bit; a '\texttt{h}'
  means to set the \texttt{NSViewHeightSizable} flag; a '\texttt{w}'
  means to set the \texttt{NSViewWidthSizable} flag; a '\texttt{x}'
  means to set the \texttt{NSViewMinXMargin} flag; a '\texttt{X}'
  means to set the \texttt{NSViewMaxXMargin} flag; a '\texttt{y}'
  means to set the \texttt{NSViewMinYMargin} flag; a '\texttt{Y}'
  means to set the \texttt{NSViewMaxYMargin} flag.  For example, an
  attribute value of ``hw'' means \texttt{NSViewHeightSizable |
    NSViewWidthSizable}.  An attribute value of ``'' means an empty
  autoresizing mask.  If this attribute is not set, the autoresizing
  mask of the view is set from the \texttt{halign} and \texttt{valign}
  property; if any of the two is not set, the object's
  \texttt{-autolayoutDefaultHorizontalAlignment} or
  \texttt{-autolayoutDefaultVerticalAlignment} method is called to get
  a default value that can be used.
\item {\bf border}: A float.  If set, this is equivalent to setting
  both \texttt{hborder} and \texttt{vborder} to that same value.  This
  attribute might be removed in future releases.
\item {\bf halign}: A string, which can take one of the values
  \texttt{expand}, \texttt{wexpand}, \texttt{left}, \texttt{center},
  \texttt{right}.  \texttt{min} is also accepted as an alias for
  \texttt{left}, and \texttt{max} as an alias for \texttt{right}.
  This attribute is only used by an eventual enclosing autolayout
  container (such as a hbox or a vbox).  \texttt{expand} causes the
  view to be made expandable in a certain direction; the view will
  expand horizontally when space is available, and will cause
  horizontal expansion whenever possible.  \texttt{wexpand} causes the
  view to be made weakly expandable in a certain direction: the view
  will expand horizontally when space is available, but will not
  directly cause horizontal expansion to be possible unless another
  view causes it.  \texttt{left}, \texttt{center} and \texttt{right}
  will cause the view not to expand when more space is available, but
  just to keep its width, and align itself in the available space as
  specified.  For more information on the meaning of those flags,
  please refer to section \ref{autolayout-flags}.
\item {\bf hborder}: An integer.  If set, the horizontal border of the
  view is set to that value.  This is only used by an eventual
  enclosing autolayout container (such as a hbox or vbox).
\item {\bf height}: A float.  If set, the height of the view frame is
  set to this value; this is done after the autosizing, so in practice
  it overrides any height computed by the autosizing.
\item {\bf hidden}: A boolean.  If set to yes, it changes the view to
  be hidden.
\item {\bf proportion}: A float.  If set, the proportion of the view
  is set to that value.  This is only used by an eventual enclosing
  autolayout container supporting view proportions (such as a
  proportional hbox or vbox).  For example, a view with a
  \texttt{proportion="2"} attribute takes up twice the space as normal
  view in a proportional hbox.
\item {\bf toolTip}: A localizable string.  If set, the view tool tip
  is set to it.
\item {\bf valign}: A string, which can take one of the values
  \texttt{expand}, \texttt{wexpand}, \texttt{top}, \texttt{center},
  \texttt{bottom}.  \texttt{min} is also accepted as an alias for
  \texttt{bottom}, and \texttt{max} as an alias for \texttt{top}.
  This attribute is only used by an eventual enclosing autolayout
  container (such as a hbox or a vbox).  For the meaning of the
  attribute values please refer to the documentation for the
  \texttt{halign} attribute; the attribute values have the same
  meaning in the vertical direction.
\item {\bf vborder}: An integer.  If set, the vertical border of the
  view is set to that value.  This is only used by an eventual
  enclosing autolayout container (such as a hbox or vbox).
\item {\bf width}: A float.  If set, the width of the view frame is
  set to this value; this is done after the autosizing, so in practice
  it overrides any width computed by the autosizing.
\item {\bf x}: A float.  If set, the x coordinate of the origin of the
  view frame is set to this value.
\item {\bf y}: A float.  If set, the y coordinate of the origin of the
  view frame is set to this value.
\end{itemize}

The \texttt{<view>} tag supports the \texttt{instanceOf} attribute.

\subsubsection{Possible object attributes}
\begin{itemize}
\item {\bf nextKeyView}: The view next key view.  (TODO: If
  hboxes/vboxes are used, a reasonably meaningful key view chain can
  be automatically established by linking together views as they are
  listed in the hboxes/vboxes!).
\end{itemize}

\subsubsection{Content}
Usually \texttt{<view>} tags should have no content; they are mostly
used subclasses to provide a special control to display in an area of
a window.  Most other view tags do have content though; autoresizing
container tags such as \texttt{<hbox>} or \texttt{<vbox>} have content
which are subviews that are managed by them; text fields and labels
have strings to display as content; tables and matrixes have columns
and rows as content.  Please refer to the description of each tag for
an explanation of the content they hold.

To support corner cases and static placement of subviews, if you add
some view tags as content to a \texttt{<view>} tag, they are added as
subviews.  This is only useful in special cases and provides no
autoresizing (unless you use the legacy OpenStep one).  We recommend
adding subviews in this way only in special situations; you should
normally use the Renaissance autolayout container tags to manage
subviews.  Also note that subclasses do not inherit this behaviour
unless they contain explicit code to enable it - so \texttt{<view>} is
the only tag where you can add subviews in a direct OpenStep way;
other view tags do not treat their content as subviews in this way
(unless specifically written to do so).

\subsubsection{Examples}
Usually \texttt{<view>} tags are used to create custom views, in which
case the \texttt{instanceOf} is used.  Custom views representing
editable areas often have have hardcoded \texttt{width} and
\texttt{height} attributes -- but other types of custom views might
be able/need to autosize.
\begin{verbatim}
<view instanceOf="BandView" id="BandView" width="200" height="100" />
\end{verbatim}

Here is an example of using a \texttt{<view>} tag to create a view and
put some subviews at fixed locations into it:
\begin{verbatim}
<view width="250" height="150">
  <colorWell x="50" y="50" width="50" height="50" color="black" />
  <colorWell x="150" y="50" width="50" height="50" color="black" />
</view>
\end{verbatim}

\subsection{The vspace tag}

\subsubsection{Description}

A \texttt{<vspace>} tag represents invisible vertical weakly-expanding
space that can be put into autolayout containers such as
\texttt{<vbox>} objects for alignment purporses.  It normally
generates an instance of \texttt{GSAutoLayoutVSpace}.

A \texttt{<vspace>} is identical to a \texttt{<hspace>}, but expands
vertically instead of horizontally.  You should always use
\texttt{<vspace>} tags inside \texttt{<vbox>} tags, and
\texttt{<hspace>} tags inside \texttt{<hbox>} tags.

\subsubsection{Attributes}
The \texttt{<vspace>} tag inherits all attributes from the generic
\texttt{<view>} tag but adds no new attributes of its own.

The \texttt{<vspace>} tag supports the \texttt{instanceOf} attribute.

\subsubsection{Possible object attributes}
The \texttt{<vspace>} tag inherits all object attributes from the
generic \texttt{<view>} tag but has none of its own.

\subsubsection{Content}
A \texttt{<vspace>} tag has no content.

\subsubsection{Examples}
See the examples for the \texttt{<vspace>} tag.

\subsection{The window tag}
\subsubsection{Description}
A \texttt{<window>} tag represents a window, and normally generates an
instance of \texttt{NSWindow}.  When the tag is processed, the
borderless, closable, miniaturizable and titled attributes are read
first.  If no attribute is specified, the window is created with all
decorations, so that it is made closable, miniaturizable and titled
(we'll discuss the resizable attribute later).  Any of these
decorations can be removed by setting the corresponding attribute to
no.  Setting the attribute borderless to yes causes no decoration to
be used.

The content of the tag is then processed; it is expected to contain a
single tag (or nothing); if that tag produces a NSView object, the
object is set to be the window content view.  The resizable attribute
is checked next; if it set to yes (or no), then the window is made
resizable (or not resizable).

If the resizable attribute is not set, then Renaissance needs to
automatically determine if the window is to be made resizable or not.
The autolayout flags of the content view are checked; if the content
view has a flag of \texttt{expand} set in a direction, Renaissance
records that the window should be made resizable in that direction; if
it set to anything else (including \texttt{wexpand}), Renaissance
records that the window should not be made resizable in that direction
(preventing resizability in the horizontal/vertical direction will be
obtained by setting the maximum width/height to be the same as the
minimum width/height).

At this point, the window itself is resized so that its content size
is exactly that view's size (this basically autosizes the window to
fit the contents).  After the window has been so sized, the hardcoded
frame attributes are processed -- these attributes are x, y, width,
heigth, contentWidth and contentHeight.  If any of these attributes is
set, it is used to resize/relocate the window, so that hardcoded frame
attribute override the autosizing size.  Then, the window sets
additional attributes such as title, minWidth, minHeight, maxWidth,
maxHeigth, backgroundColor.  If minWidth or minHeight are not set, the
current width and height of the window are used instead, in the
assumption that the content view is always sized to its minimum
comfortable size the first time the window is loaded.  If the code for
automatical decision of resizability has been used, and Renaissance
has determined that the window should not be resizable in a direction,
then it also sets the maxWidth (or maxHeight) to be the same as the
current width (or height); this will in fact make the window not
resizable in that direction.

Then, if the attribute center is set to yes, the window is centered on
screen.  At this point, if an autosaveName is specified for the
window, the window sets up autosaving of the frame under that name
and, if a frame already exists in the user defaults with that name,
the window changes its frame accordingly.  In other words, if the
window autosaves its frame, the next time the window is created from a
GSMarkup file, the autosaved frame will override any other frame.

Last, the window is ordered front (by using \texttt{orderFront:}),
unless the attribute visible has been set to no; it is also made the
key window (by using \texttt{makeKeyWindow}) unless the keyWindow
attribute has been set to no; and if the mainWindow attribute is set
to yes, it is also made the main window (by using
\texttt{makeMainWindow}).

\subsubsection{Attributes}
\begin{itemize}
\item {\bf autosaveName}: A string (not localized).  If set, the
  window frameAutosaveName is set to it, and -- after the window has
  been created and set to its default size and location --, the frame
  saved under this name is automatically retrieved (if found) in the
  user defaults, and the window frame is changed to it.  This means
  that the first time the window is displayed, it will use the
  frame/size which is determined by its content view, or which is
  hardcoded in the gsmarkup file (the latter overriding the previous);
  but the next time, it will resize and relocate itself to the same
  frame the user gave it last time it was used.
\item {\bf backgroundColor}: A color.  If set, the window natural
  background color is overridden by this color.
\item {\bf borderless}: A boolean.  If set to yes, the window is
  created without any decorations.
\item {\bf center}: A boolean.  If set to yes, the window is
  automatically centered when it is created.
\item {\bf closable}: A boolean.  If set to no, the window is created
  non closable (if not set, it is created closable, unless borderless
  is set to yes).
\item {\bf contentHeight}: A positive float.  If set, the heigth of
  the window content size is set to this.  This is done after the
  window has been sized to fit its content view (if any), but before
  the window is sized to the autosaved frame (if any).
\item {\bf contentWidth}: A positive float.  If set, the width of the
  window content size is set to this.  This is done after the window
  has been sized to fit its content view (if any), but before the
  window is sized to the autosaved frame (if any).
\item {\bf heigth}: A positive float.  If set, the heigth of the
  window frame is set to this value.  See comments for {\bf x} about
  interaction with autosaved frame.
\item {\bf keyWindow}: A boolean.  If set to no, the window is not
  automatically made the key window when it is created.  By default
  all windows are made the key window when they are loaded from a
  .gsmarkup file.
\item {\bf mainWindow}: A boolean.  If set to yes, the window is
  automatically made the main window when it is created.  By default
  windows are not made the main when they are loaded from a .gsmarkup
  file.
\item {\bf maxHeigth}: A positive float.  If set, the heigth of the
  window maximum size is set to this value.
\item {\bf maxWidth}: A positive float.  If set, the width of the
  window maximum size is set to this value.
\item {\bf minHeigth}: A positive float.  If set, the heigth of the
  window minimum size is set to this value.
\item {\bf minWidth}: A positive float.  If set, the width of the
  window minimum size is set to this value.
\item {\bf miniaturizable}: A boolean.  If set to no, the window is
  created non miniaturizable (it is miniaturizable otherwise, unless
  borderless is set to yes).
\item {\bf releasedWhenClosed}: A boolean.  If set to yes, the window
  is set to be released when closed, if set to no, the window is set
  to not be released when closed.  Please note that the default
  behaviour differs between windows and panels: windows by default are
  released when closed, while panels are not.
\item {\bf resizable}: A boolean.  If set to no, the window is created
  non resizable.  If this attribute is not set, Renaissance will use
  the content view autolayout flags to decide if the window has to be
  resizable or not (including possibly using maxWidth and maxHeight to
  force the window be not resizable in a single direction).
\item {\bf title}: A localizable string.  If set, the window title is
  set to it.
\item {\bf titled}: A boolean.  If set to no, the window is created
  without a titlebar (it has a titlebar otherwise, unless borderless
  is set to yes).
\item {\bf visible}: A boolean.  If set to no, the window is not made
  visible after it has been created.  Normally, all windows are
  automatically ordered front (by calling \texttt{orderFront:}) after
  they are created.  By setting visible to no, you can prevent this to
  happen.
\item {\bf width}: A positive float.  If set, the width of the window
  frame is set to this value.  See comments for {\bf x} about
  interaction with autosaved frame.
\item {\bf x}: A float.  If set, the x coordinate of the origin of the
  window frame is set to this value.  If the window autosaves its
  frame, the autosave frame is set last, overriding any specification
  found in the gsmarkup file ... which means setting this attribute
  affects the window only the very first time it is displayed; later
  on, the autosaved origin is used instead.
\item {\bf y}: A float.  If set, the y coordinate of the origin of the
  window frame is set to this value.  See comments for {\bf x} about
  interaction with autosaved frame.
\end{itemize}

The \texttt{<window>} tag supports the \texttt{instanceOf} attribute.

\subsubsection{Possible object attributes}
\begin{itemize}
\item {\bf delegate}: The window delegate.
\item {\bf initialFirstResponder}: The window initialFirstResponder.
\end{itemize}

\subsubsection{Content}
A \texttt{<window>} tag can contain a single tag, representing a view.
The platform object created by this tag is set to be the window
content view, and the window itself is sized (at first) so that the
content view exactly fits.  The window is later on resized if a fixed
content size or frame is specified in the attributes; finally, if the
window is autosaving its frame, the saved frame is restored last, so
that it overrides all other specifications.

\subsubsection{Examples}
Really depends on the type of window you are creating.  Typically you
want to set a title, change the window decorations (closable,
miniaturizable), set an autosaveName; from time to time, you might
also need to hardcode the contentSize of the window, or the window
frame.  If you are creating a panel, please use the \texttt{<panel>}
tag, which accepts all the attributes of a \texttt{<window>} tag, but
creates a \texttt{NSPanel} rather than a \texttt{NSWindow} (and has a
few panelish attributes more).  An example window with nothing inside:
\begin{verbatim}
  <window title="My First Window" />
\end{verbatim}
A window containing a button:
\begin{verbatim}
  <window title="Test" center="yes" autosaveName="terminate">
    <button title="Click to quit the application" action="terminate:">
  </window>
\end{verbatim}
please note that autosaving the frame will save the window location,
so it is a good idea to do it even if the window is not resizable.  A
window with a fixed frame:
\begin{verbatim}
<window title="frame of 500x100" autosaveName="fixedFrameExample"
        width="500" heigth="100" />
\end{verbatim}

%%
%% Connector tag reference
%%

\section{Connector tag reference}

\subsection{The control tag}

\subsubsection{Description}
A \texttt{<control>} tag represents a control connector (a connector
used to connect controls) and is converted into an instance of
\texttt{GSMarkupControlConnector}.  When the connection is
established, the following code is executed
\begin{verbatim}
  [source setAction: action];
  [source setTarget: target];
\end{verbatim}
where \texttt{source} is the source object, \texttt{target} is the
target object, and \texttt{action} is obtained by converting the
action attribute into a selector.

Because objects which allow you to set an action normally have an
action attribute, this connector is normally never used, since you
would rather set the action of the source by using the action
attribute of the source object, and then set the target of the source
to the target object by using a standard outlet connector with key
"target", or setting the object attribute target of the source to the
target object.  Please have a look at the examples which should make
this clear.

\subsubsection{Attributes}
\begin{itemize}
\item {\bf action}: The action of the connector.  This attribute is a
  string (non localizable), which is converted into a selector when
  the connection is established.  If missing (or if the specified
  selector can't be found), a \texttt{NULL} action is used.
\item {\bf label}: If there is no \texttt{action} but a \texttt{label}
  attribute is present, it is used instead of \texttt{action}.
\item {\bf source}: A reference to another object -- a string
  beginning with a hash (\texttt{\#}).  This object is the source of
  the control connector.  If the string contains a dot, the object is
  looked up in the name table, and then key-value coding is applied
  (see the description of advanced outlets).  It is required.
\item {\bf target}: A reference to another object -- a string
  beginning with a hash (\texttt{\#}).  This object is the target of
  the control connector.  If the string contains a dot, the object is
  looked up in the name table, and then key-value coding is applied
  (see the description of advanced outlets).  If omitted, \texttt{nil}
  will be used as target when establishing the connection.
\end{itemize}

\subsubsection{Examples}
Control connectors are used very rarely.  Here is how a control
connector would look:
\begin{verbatim}
<connectors>
  <control source="#myButton" target="#myController" action="buttonPressed:" />
</connectors>
\end{verbatim}
this is rarely used, because usually you can more simply do
\begin{verbatim}
<objects>
  ...
    <button action="buttonPressed:" target="#myController" ... />
  ...
</objects>
\end{verbatim}
this is equivalent, but it is preferred because it is much more
natural: you set the action and the target of the button in the same
place where you create the button, rather than in the separate
connectors section.  The system automatically writes all action
connectors in this way when it writes gsmarkup files -- if it can: if the
source is not created in the gsmarkup file, this can't be done, and you
would need to use a control connector explicitly.

\subsection{The outlet tag}

\subsubsection{Description}
An \texttt{<outlet>} tag represents an outlet connector (a generic
connector), and is converted into an instance of
\texttt{GSMarkupOutletConnector}.  When the connection is established,
the following code is executed
\begin{verbatim}
  [source takeValue: target  forKey: key];
\end{verbatim}
where \texttt{source} is the source object, \texttt{target} is the
target object, and \texttt{label} is the key.  Often an outlet can be
embedded directly into the objects section, which results in simpler,
better code.

\subsubsection{Attributes}
\begin{itemize}
\item {\bf key}: The key of the connector.  This attribute is a string
  (non localized), and is required (unless a label is provided).  It
  is the key whose value is set to target, using key-value coding on
  source.
\item {\bf label}: If there is no \texttt{key} but a \texttt{label}
  attribute is present, it is used instead of \texttt{key}.
\item {\bf source}: A reference to another object -- a string
  beginning with a hash (\texttt{\#}).  This object is the source of
  the outlet connector.  If the string contains a dot, the object is
  looked up in the name table, and then key-value coding is applied
  (see the description of advanced outlets).  It is required.
\item {\bf target}: A reference to another object -- a string
  beginning with a hash (\texttt{\#}).  This object is the target of
  the outlet connector.  If the string contains a dot, the object is
  looked up in the name table, and then key-value coding is applied
  (see the description of advanced outlets).  If omitted, \texttt{nil}
  will be used as target when establishing the connection.
\end{itemize}

\subsubsection{Examples}
Outlet connectors are not used often, but they are needed sometimes.
Here is how an outlet connector would look:
\begin{verbatim}
<connectors>
  <outlet source="#myController" target="#myButton" key="button" />
</connectors>
\end{verbatim}
this (in which the source is an object already existing in the
application) is the only form of outlet connector which is normally
used, because if the object is created in the gsmarkup file itself, the outlet
can be embedded in the object creation by using the syntax
\begin{verbatim}
<objects>
  ...
    <textView delegate="#myController" ... />
  ...
</objects>
\end{verbatim}
which is perfectly equivalent to:
\begin{verbatim}
<objects>
  ...
    <textView id="myTextView" ... />
  ...
</objects>

<connectors>
  <outlet source="#myTextView" target="#myController" key="delegate" />
</connectors>
\end{verbatim}
this second explicit form is much more long, artificial and
cumbersome.  The system automatically writes all outlet connectors
inside the objects section when it writes gsmarkup files -- if it can.  In
some cases (when the source is created outside the gsmarkup file) this
can't be done; these are the cases in which the connector is created
manually inside the connectors section.

\section{Example}

FIXME: this example should be replaced with a better one.

FIXME: add examples of advanced outlets.

\begin{verbatim}

<?xml version="1.0"?>
<!DOCTYPE gsmarkup>
<gsmarkup>

<objects>
 <!-- the main window -->
 <window title="Calculator" resizable="no" closable="no">

   <vbox>

     <textfield editable="no" id="TextField" />

     <hbox>
      <button title="1" target="#Controller" action="digit:" />
      <button title="2" target="#Controller" action="digit:" />
      <button title="3" target="#Controller" action="digit:" />
     </hbox>

     <hbox>
      <button title="4" target="#Controller" action="digit:" />
      <button title="5" target="#Controller" action="digit:" />
      <button title="6" target="#Controller" action="digit:" />
     </hbox>

     <hbox>
      <button title="7" target="#Controller" action="digit:" />
      <button title="8" target="#Controller" action="digit:" />
      <button title="9" target="#Controller" action="digit:" />
     </hbox>

     <hbox>
      <button title="+" target="#Controller" action="add:" />
      <button title="0" target="#Controller" action="digit:" />
      <button title="=" target="#Controller" action="total:" />
     </hbox>

   </vbox>

 </window>

 <!-- an object of a custom class, which is instantiated when the nib
      is loaded.  Key-value coding is used to set textField to #TextField.
      In other words, the textField attribute is equivalent to having a
      NSNibOutletConnector with source #Controller, target #TextField, 
      and key textField -->
 <instance instanceOf="CalculatorController" id="Controller" 
           textField="#TextField" />

</objects>


<!-- in this example, connectors are not actually needed (or better
     all connectors are embedded in the objects section) - but we add
     the connectors section as an example.  -->
<connectors>

 <!-- an example of a standalone connector, needed to connect the Controller
      to the controller ivar (or setController: method) of the NSOwner (the
      object which loaded the nib).  This connector must be standalone
      because #NSOwner is not inside the nib.  (you can reference objects
      totally outside the nib in a connector, which are provided by the
      nameTable dictionary when the nib is loaded) -->
 <outlet source="#NSOwner" target="#Controller" key="controller" />

</connectors>

</gsmarkup>
\end{verbatim}
