Server : Apache/2.4.41 (Ubuntu) System : Linux absol.cf 5.4.0-198-generic #218-Ubuntu SMP Fri Sep 27 20:18:53 UTC 2024 x86_64 User : www-data ( 33) PHP Version : 7.4.33 Disable Function : pcntl_alarm,pcntl_fork,pcntl_waitpid,pcntl_wait,pcntl_wifexited,pcntl_wifstopped,pcntl_wifsignaled,pcntl_wifcontinued,pcntl_wexitstatus,pcntl_wtermsig,pcntl_wstopsig,pcntl_signal,pcntl_signal_get_handler,pcntl_signal_dispatch,pcntl_get_last_error,pcntl_strerror,pcntl_sigprocmask,pcntl_sigwaitinfo,pcntl_sigtimedwait,pcntl_exec,pcntl_getpriority,pcntl_setpriority,pcntl_async_signals,pcntl_unshare, Directory : /proc/self/root/usr/share/doc/renaissance-doc/html/manual/
Upload File :
Current File : //proc/self/root/usr/share/doc/renaissance-doc/html/manual/node21.html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<!--Converted with LaTeX2HTML 2002-2-1 (1.71)
original version by: Nikos Drakos, CBLU, University of Leeds
* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>2.7 Object tag reference</TITLE>
<META NAME="description" CONTENT="2.7 Object tag reference">
<META NAME="keywords" CONTENT="manual">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META NAME="Generator" CONTENT="LaTeX2HTML v2002-2-1">
<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
<LINK REL="STYLESHEET" HREF="manual.css">
<LINK REL="next" HREF="node22.html">
<LINK REL="previous" HREF="node20.html">
<LINK REL="up" HREF="node14.html">
<LINK REL="next" HREF="node22.html">
</HEAD>
<BODY BGCOLOR="#FFFFFF" text="#000000" link="#0000FF" vlink="#4444FF" alink="#3388FF">
<B> Next: <A NAME="tex2html753"
HREF="node22.html">2.8 Connector tag reference</A> </B>
<B>Up: <A NAME="tex2html749"
HREF="node14.html">2. The GNUstep Markup</A> </B>
<B> Previous: <A NAME="tex2html743"
HREF="node20.html">2.6 Integrating Renaissance in</A> </B>
<BR> <P>
<!--End of Navigation Panel-->
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
<UL>
<LI><A NAME="tex2html754"
HREF="node21.html#SECTION00371000000000000000">2.7.1 The button tag</A>
<UL>
<LI><A NAME="tex2html755"
HREF="node21.html#SECTION00371100000000000000">2.7.1.1 Description</A>
<LI><A NAME="tex2html756"
HREF="node21.html#SECTION00371200000000000000">2.7.1.2 Attributes</A>
<LI><A NAME="tex2html757"
HREF="node21.html#SECTION00371300000000000000">2.7.1.3 Possible object attributes</A>
<LI><A NAME="tex2html758"
HREF="node21.html#SECTION00371400000000000000">2.7.1.4 Content</A>
<LI><A NAME="tex2html759"
HREF="node21.html#SECTION00371500000000000000">2.7.1.5 Examples</A>
</UL>
<BR>
<LI><A NAME="tex2html760"
HREF="node21.html#SECTION00372000000000000000">2.7.2 The colorWell tag</A>
<UL>
<LI><A NAME="tex2html761"
HREF="node21.html#SECTION00372100000000000000">2.7.2.1 Description</A>
<LI><A NAME="tex2html762"
HREF="node21.html#SECTION00372200000000000000">2.7.2.2 Attributes</A>
<LI><A NAME="tex2html763"
HREF="node21.html#SECTION00372300000000000000">2.7.2.3 Possible object attributes</A>
<LI><A NAME="tex2html764"
HREF="node21.html#SECTION00372400000000000000">2.7.2.4 Content</A>
<LI><A NAME="tex2html765"
HREF="node21.html#SECTION00372500000000000000">2.7.2.5 Examples</A>
</UL>
<BR>
<LI><A NAME="tex2html766"
HREF="node21.html#SECTION00373000000000000000">2.7.3 The control tag</A>
<UL>
<LI><A NAME="tex2html767"
HREF="node21.html#SECTION00373100000000000000">2.7.3.1 Description</A>
<LI><A NAME="tex2html768"
HREF="node21.html#SECTION00373200000000000000">2.7.3.2 Attributes</A>
<LI><A NAME="tex2html769"
HREF="node21.html#SECTION00373300000000000000">2.7.3.3 Possible object attributes</A>
<LI><A NAME="tex2html770"
HREF="node21.html#SECTION00373400000000000000">2.7.3.4 Content</A>
<LI><A NAME="tex2html771"
HREF="node21.html#SECTION00373500000000000000">2.7.3.5 Examples</A>
</UL>
<BR>
<LI><A NAME="tex2html772"
HREF="node21.html#SECTION00374000000000000000">2.7.4 The hbox tag</A>
<UL>
<LI><A NAME="tex2html773"
HREF="node21.html#SECTION00374100000000000000">2.7.4.1 Description</A>
<LI><A NAME="tex2html774"
HREF="node21.html#SECTION00374200000000000000">2.7.4.2 Attributes</A>
<LI><A NAME="tex2html775"
HREF="node21.html#SECTION00374300000000000000">2.7.4.3 Possible object attributes</A>
<LI><A NAME="tex2html776"
HREF="node21.html#SECTION00374400000000000000">2.7.4.4 Content</A>
<LI><A NAME="tex2html777"
HREF="node21.html#SECTION00374500000000000000">2.7.4.5 Examples</A>
</UL>
<BR>
<LI><A NAME="tex2html778"
HREF="node21.html#SECTION00375000000000000000">2.7.5 The hspace tag</A>
<UL>
<LI><A NAME="tex2html779"
HREF="node21.html#SECTION00375100000000000000">2.7.5.1 Description</A>
<LI><A NAME="tex2html780"
HREF="node21.html#SECTION00375200000000000000">2.7.5.2 Attributes</A>
<LI><A NAME="tex2html781"
HREF="node21.html#SECTION00375300000000000000">2.7.5.3 Possible object attributes</A>
<LI><A NAME="tex2html782"
HREF="node21.html#SECTION00375400000000000000">2.7.5.4 Content</A>
<LI><A NAME="tex2html783"
HREF="node21.html#SECTION00375500000000000000">2.7.5.5 Examples</A>
</UL>
<BR>
<LI><A NAME="tex2html784"
HREF="node21.html#SECTION00376000000000000000">2.7.6 The image tag</A>
<UL>
<LI><A NAME="tex2html785"
HREF="node21.html#SECTION00376100000000000000">2.7.6.1 Description</A>
<LI><A NAME="tex2html786"
HREF="node21.html#SECTION00376200000000000000">2.7.6.2 Attributes</A>
<LI><A NAME="tex2html787"
HREF="node21.html#SECTION00376300000000000000">2.7.6.3 Possible object attributes</A>
<LI><A NAME="tex2html788"
HREF="node21.html#SECTION00376400000000000000">2.7.6.4 Content</A>
<LI><A NAME="tex2html789"
HREF="node21.html#SECTION00376500000000000000">2.7.6.5 Examples</A>
</UL>
<BR>
<LI><A NAME="tex2html790"
HREF="node21.html#SECTION00377000000000000000">2.7.7 The instance tag</A>
<UL>
<LI><A NAME="tex2html791"
HREF="node21.html#SECTION00377100000000000000">2.7.7.1 Description</A>
<LI><A NAME="tex2html792"
HREF="node21.html#SECTION00377200000000000000">2.7.7.2 Attributes</A>
<LI><A NAME="tex2html793"
HREF="node21.html#SECTION00377300000000000000">2.7.7.3 Possible object attributes</A>
<LI><A NAME="tex2html794"
HREF="node21.html#SECTION00377400000000000000">2.7.7.4 Content</A>
<LI><A NAME="tex2html795"
HREF="node21.html#SECTION00377500000000000000">2.7.7.5 Examples</A>
</UL>
<BR>
<LI><A NAME="tex2html796"
HREF="node21.html#SECTION00378000000000000000">2.7.8 The label tag</A>
<UL>
<LI><A NAME="tex2html797"
HREF="node21.html#SECTION00378100000000000000">2.7.8.1 Description</A>
<LI><A NAME="tex2html798"
HREF="node21.html#SECTION00378200000000000000">2.7.8.2 Attributes</A>
<LI><A NAME="tex2html799"
HREF="node21.html#SECTION00378300000000000000">2.7.8.3 Possible object attributes</A>
<LI><A NAME="tex2html800"
HREF="node21.html#SECTION00378400000000000000">2.7.8.4 Content</A>
<LI><A NAME="tex2html801"
HREF="node21.html#SECTION00378500000000000000">2.7.8.5 Examples</A>
</UL>
<BR>
<LI><A NAME="tex2html802"
HREF="node21.html#SECTION00379000000000000000">2.7.9 The menu tag</A>
<UL>
<LI><A NAME="tex2html803"
HREF="node21.html#SECTION00379100000000000000">2.7.9.1 Description</A>
<LI><A NAME="tex2html804"
HREF="node21.html#SECTION00379200000000000000">2.7.9.2 Attributes</A>
<LI><A NAME="tex2html805"
HREF="node21.html#SECTION00379300000000000000">2.7.9.3 Possible object attributes</A>
<LI><A NAME="tex2html806"
HREF="node21.html#SECTION00379400000000000000">2.7.9.4 Content</A>
<LI><A NAME="tex2html807"
HREF="node21.html#SECTION00379500000000000000">2.7.9.5 Examples</A>
<LI><A NAME="tex2html808"
HREF="node21.html#SECTION00379600000000000000">2.7.9.6 Portability</A>
</UL>
<BR>
<LI><A NAME="tex2html809"
HREF="node21.html#SECTION003710000000000000000">2.7.10 The menuItem tag</A>
<UL>
<LI><A NAME="tex2html810"
HREF="node21.html#SECTION003710100000000000000">2.7.10.1 Description</A>
<LI><A NAME="tex2html811"
HREF="node21.html#SECTION003710200000000000000">2.7.10.2 Attributes</A>
<LI><A NAME="tex2html812"
HREF="node21.html#SECTION003710300000000000000">2.7.10.3 Possible object attributes</A>
<LI><A NAME="tex2html813"
HREF="node21.html#SECTION003710400000000000000">2.7.10.4 Content</A>
<LI><A NAME="tex2html814"
HREF="node21.html#SECTION003710500000000000000">2.7.10.5 Examples</A>
</UL>
<BR>
<LI><A NAME="tex2html815"
HREF="node21.html#SECTION003711000000000000000">2.7.11 The menuSeparator tag</A>
<UL>
<LI><A NAME="tex2html816"
HREF="node21.html#SECTION003711100000000000000">2.7.11.1 Description</A>
<LI><A NAME="tex2html817"
HREF="node21.html#SECTION003711200000000000000">2.7.11.2 Attributes</A>
<LI><A NAME="tex2html818"
HREF="node21.html#SECTION003711300000000000000">2.7.11.3 Possible object attributes</A>
<LI><A NAME="tex2html819"
HREF="node21.html#SECTION003711400000000000000">2.7.11.4 Content</A>
<LI><A NAME="tex2html820"
HREF="node21.html#SECTION003711500000000000000">2.7.11.5 Examples</A>
</UL>
<BR>
<LI><A NAME="tex2html821"
HREF="node21.html#SECTION003712000000000000000">2.7.12 The panel tag</A>
<UL>
<LI><A NAME="tex2html822"
HREF="node21.html#SECTION003712100000000000000">2.7.12.1 Description</A>
<LI><A NAME="tex2html823"
HREF="node21.html#SECTION003712200000000000000">2.7.12.2 Attributes</A>
<LI><A NAME="tex2html824"
HREF="node21.html#SECTION003712300000000000000">2.7.12.3 Possible object attributes</A>
<LI><A NAME="tex2html825"
HREF="node21.html#SECTION003712400000000000000">2.7.12.4 Content</A>
<LI><A NAME="tex2html826"
HREF="node21.html#SECTION003712500000000000000">2.7.12.5 Examples</A>
</UL>
<BR>
<LI><A NAME="tex2html827"
HREF="node21.html#SECTION003713000000000000000">2.7.13 The secureTextField tag</A>
<UL>
<LI><A NAME="tex2html828"
HREF="node21.html#SECTION003713100000000000000">2.7.13.1 Description</A>
<LI><A NAME="tex2html829"
HREF="node21.html#SECTION003713200000000000000">2.7.13.2 Attributes</A>
<LI><A NAME="tex2html830"
HREF="node21.html#SECTION003713300000000000000">2.7.13.3 Possible object attributes</A>
<LI><A NAME="tex2html831"
HREF="node21.html#SECTION003713400000000000000">2.7.13.4 Content</A>
<LI><A NAME="tex2html832"
HREF="node21.html#SECTION003713500000000000000">2.7.13.5 Examples</A>
</UL>
<BR>
<LI><A NAME="tex2html833"
HREF="node21.html#SECTION003714000000000000000">2.7.14 The textField tag</A>
<UL>
<LI><A NAME="tex2html834"
HREF="node21.html#SECTION003714100000000000000">2.7.14.1 Description</A>
<LI><A NAME="tex2html835"
HREF="node21.html#SECTION003714200000000000000">2.7.14.2 Attributes</A>
<LI><A NAME="tex2html836"
HREF="node21.html#SECTION003714300000000000000">2.7.14.3 Possible object attributes</A>
<LI><A NAME="tex2html837"
HREF="node21.html#SECTION003714400000000000000">2.7.14.4 Content</A>
<LI><A NAME="tex2html838"
HREF="node21.html#SECTION003714500000000000000">2.7.14.5 Examples</A>
</UL>
<BR>
<LI><A NAME="tex2html839"
HREF="node21.html#SECTION003715000000000000000">2.7.15 The vbox tag</A>
<UL>
<LI><A NAME="tex2html840"
HREF="node21.html#SECTION003715100000000000000">2.7.15.1 Description</A>
<LI><A NAME="tex2html841"
HREF="node21.html#SECTION003715200000000000000">2.7.15.2 Attributes</A>
<LI><A NAME="tex2html842"
HREF="node21.html#SECTION003715300000000000000">2.7.15.3 Possible object attributes</A>
<LI><A NAME="tex2html843"
HREF="node21.html#SECTION003715400000000000000">2.7.15.4 Content</A>
<LI><A NAME="tex2html844"
HREF="node21.html#SECTION003715500000000000000">2.7.15.5 Examples</A>
</UL>
<BR>
<LI><A NAME="tex2html845"
HREF="node21.html#SECTION003716000000000000000">2.7.16 The view tag</A>
<UL>
<LI><A NAME="tex2html846"
HREF="node21.html#SECTION003716100000000000000">2.7.16.1 Description</A>
<LI><A NAME="tex2html847"
HREF="node21.html#SECTION003716200000000000000">2.7.16.2 Attributes</A>
<LI><A NAME="tex2html848"
HREF="node21.html#SECTION003716300000000000000">2.7.16.3 Possible object attributes</A>
<LI><A NAME="tex2html849"
HREF="node21.html#SECTION003716400000000000000">2.7.16.4 Content</A>
<LI><A NAME="tex2html850"
HREF="node21.html#SECTION003716500000000000000">2.7.16.5 Examples</A>
</UL>
<BR>
<LI><A NAME="tex2html851"
HREF="node21.html#SECTION003717000000000000000">2.7.17 The vspace tag</A>
<UL>
<LI><A NAME="tex2html852"
HREF="node21.html#SECTION003717100000000000000">2.7.17.1 Description</A>
<LI><A NAME="tex2html853"
HREF="node21.html#SECTION003717200000000000000">2.7.17.2 Attributes</A>
<LI><A NAME="tex2html854"
HREF="node21.html#SECTION003717300000000000000">2.7.17.3 Possible object attributes</A>
<LI><A NAME="tex2html855"
HREF="node21.html#SECTION003717400000000000000">2.7.17.4 Content</A>
<LI><A NAME="tex2html856"
HREF="node21.html#SECTION003717500000000000000">2.7.17.5 Examples</A>
</UL>
<BR>
<LI><A NAME="tex2html857"
HREF="node21.html#SECTION003718000000000000000">2.7.18 The window tag</A>
<UL>
<LI><A NAME="tex2html858"
HREF="node21.html#SECTION003718100000000000000">2.7.18.1 Description</A>
<LI><A NAME="tex2html859"
HREF="node21.html#SECTION003718200000000000000">2.7.18.2 Attributes</A>
<LI><A NAME="tex2html860"
HREF="node21.html#SECTION003718300000000000000">2.7.18.3 Possible object attributes</A>
<LI><A NAME="tex2html861"
HREF="node21.html#SECTION003718400000000000000">2.7.18.4 Content</A>
<LI><A NAME="tex2html862"
HREF="node21.html#SECTION003718500000000000000">2.7.18.5 Examples</A>
</UL></UL>
<!--End of Table of Child-Links-->
<HR>
<H1><A NAME="SECTION00370000000000000000">
2.7 Object tag reference</A>
</H1>
<P>
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
<UL>
<LI>The description of the tag, telling you what the tag is.
</LI>
<LI>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 <TT>id</TT> attribute is always
available for all objects so it's not listed here.
</LI>
<LI>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.
</LI>
<LI>A description of what content the tag accepts.
</LI>
<LI>One or more example gsmarkup code using the tag.
</LI>
<LI>In a few specific cases, a discussion of portability issues.
</LI>
</UL>
<P>
<H2><A NAME="SECTION00371000000000000000">
2.7.1 The button tag</A>
</H2>
<P>
<H3><A NAME="SECTION00371100000000000000">
2.7.1.1 Description</A>
</H3>
A <TT><button></TT> tag represents a button, and normally generates an
instance of <TT>NSButton</TT>. The most common attributes to set in a
button are the <TT>title</TT> (the text displayed in the button), the
<TT>target</TT> and <TT>action</TT> (controlling what happens when the
button is clicked). It's also possible to set the <TT>image</TT>
attribute to set the image displayed in the button, and to create
different types of buttons by using the <TT>type</TT> attribute. Some
of the button types will be highlighted by the system; some others
will display the <TT>alternateText</TT> and/or <TT>alternateImage</TT>
when highlighted.
<P>
<H3><A NAME="SECTION00371200000000000000">
2.7.1.2 Attributes</A>
</H3>
The <TT><button></TT> tag inherits all attributes from the generic
<TT><control></TT> and <TT><view></TT> tags; in addition, it has
the following ones:
<UL>
<LI><B>alternateImage</B>: The alternate image of the button, if any.
This is an image attribute.
</LI>
<LI><B>alternateTitle</B>: The alternate text of the button, if any.
This is an optional localized string attribute.
</LI>
<LI><B>image</B>: The image of the button (an image).
</LI>
<LI><B>imagePosition</B>: The position of the button image (if
needed). This attribute is a string, and is optional. It can be
set to <TT>above</TT>, <TT>below</TT>, <TT>left</TT>,
<TT>right</TT>, <TT>overlaps</TT> and <TT>imageOnly</TT>.
</LI>
<LI><B>keyEquivalent</B>: The keyEquivalent of the button (normally a
single character).
</LI>
<LI><B>keyEquivalentModifierMask</B>: 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
<TT>noKey</TT> (the default), <TT>commandKey</TT>,
<TT>controlKey</TT> or <TT>alternateKey</TT>. In addition to that,
you can specify combinations of these values by using the <TT>|</TT>
character; for example
<TT>commandKey||controlKey</TT> 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).
</LI>
<LI><B>sound</B>: 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 <TT>[NSSound
+soundNamed:]</TT>, where the value of this attribute is used as the
argument.
</LI>
<LI><B>title</B>: The text of the button, if any. This is an
optional localized string attribute.
</LI>
<LI><B>type</B>: The type of button. This is a string, and can be
set to <TT>momentaryPushIn</TT> (a standard button that is
highlighted when you click, and unhighlighted when the mouse goes
up), <TT>momentaryChange</TT> (the same as <TT>momentaryPushIn</TT>,
but the highlighting is done by displayed the alternate text and
image), <TT>pushOnPushOff</TT> (a button that gets pushed on when
you click, and gets pushed back off when you click again),
<TT>toggle</TT> (the same as <TT>pushOnPushOff</TT>, but the 'pushed
on' state is shown by displaying the alternate text and image) and
<TT>switch</TT> (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 <TT>momentaryPushIn</TT>.
</LI>
</UL>
<P>
The <TT><button></TT> tag supports the <TT>instanceOf</TT> attribute.
<P>
<H3><A NAME="SECTION00371300000000000000">
2.7.1.3 Possible object attributes</A>
</H3>
The <TT><button></TT> tag inherits all object attributes from the
generic <TT><control></TT> and <TT><view></TT> tags, but adds no
specific of its own.
<P>
<H3><A NAME="SECTION00371400000000000000">
2.7.1.4 Content</A>
</H3>
A <TT><button></TT> tag has no content.
<P>
<H3><A NAME="SECTION00371500000000000000">
2.7.1.5 Examples</A>
</H3>
The most common type of <TT><button></TT> tag triggers an action on a
target:
<PRE>
<button title="Click this button to quit" action="terminate:" target="NSApp" />
</PRE>
In preference panels, it's also common to use switch buttons:
<PRE>
<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>
</PRE>
<P>
<H2><A NAME="SECTION00372000000000000000">
2.7.2 The colorWell tag</A>
</H2>
<P>
<H3><A NAME="SECTION00372100000000000000">
2.7.2.1 Description</A>
</H3>
<P>
A <TT><colorWell></TT> tag represents a colorWell (a small rectangular
control used to display or choose a color), and normally generates an
instance of <TT>NSColorWell</TT>. The most common attribute to set in
a colorWell is the <TT>color</TT> (the color displayed/edited in the
color well).
<P>
<H3><A NAME="SECTION00372200000000000000">
2.7.2.2 Attributes</A>
</H3>
The <TT><colorWell></TT> tag inherits all attributes from the generic
<TT><control></TT> and <TT><view></TT> tags; in addition, it has
the following ones:
<UL>
<LI><B>bordered</B>: A boolean attribute; if set to yes, the color
well is bordered (the default), else, it's not.
</LI>
<LI><B>color</B>: A color attribute - the color displayed in the
color well.
</LI>
</UL>
<P>
The <TT><colorWell></TT> tag supports the <TT>instanceOf</TT> attribute.
<P>
<H3><A NAME="SECTION00372300000000000000">
2.7.2.3 Possible object attributes</A>
</H3>
The <TT><colorWell></TT> tag inherits all object attributes from the
generic <TT><control></TT> and <TT><view></TT> tags, but adds no
specific of its own.
<P>
<H3><A NAME="SECTION00372400000000000000">
2.7.2.4 Content</A>
</H3>
A <TT><colorWell></TT> tag has no content.
<P>
<H3><A NAME="SECTION00372500000000000000">
2.7.2.5 Examples</A>
</H3>
The most common type of <TT><colorWell></TT> tag triggers an action on
a target, and is mostly used in preference panels:
<PRE>
<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>
</PRE>
<P>
<H2><A NAME="SECTION00373000000000000000">
2.7.3 The control tag</A>
</H2>
<P>
<H3><A NAME="SECTION00373100000000000000">
2.7.3.1 Description</A>
</H3>
<P>
A <TT><control></TT> tag represents a control, and normally generates
an instance of <TT>NSControl</TT>. Instances of <TT>NSControl</TT>
are not particularly useful as they are (<TT>NSControl</TT> instances
represent rectangular regions in a window which display some data and
react to user events), which is why <TT><control></TT> tags are
normally only used with an <TT>instanceOf</TT> attribute to create
custom control objects.
<P>
The attributes of <TT><control></TT> tags are inherited by all tags
whose instances inherit from <TT>NSControl</TT> - 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.
<P>
<H3><A NAME="SECTION00373200000000000000">
2.7.3.2 Attributes</A>
</H3>
The <TT><control></TT> tag inherits all attributes from the more
generic <TT><view></TT> tag; in addition, it has the following
attributes:
<UL>
<LI><B>action</B>: 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 <TT>NULL</TT> action is used. Please note that the string
should include the <TT>`:'</TT> at the end; for example,
<TT>action="terminate:"</TT>.
</LI>
<LI><B>continuous</B>: This attribute is a boolean; it is optional;
if set to <TT>yes</TT>, the control will send its action
continuously; if set to <TT>no</TT>, it does not.
</LI>
<LI><B>enabled</B>: This attribute is a boolean; it is optional; if
set to <TT>yes</TT> it enables the control, if set to <TT>no</TT> it
disables it.
</LI>
<LI><B>font</B>: 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.
</LI>
<LI><B>sendActionOn</B>: This attribute is a string, and is optional.
It can be set to <TT>leftMouseUp</TT>, <TT>leftMouseDown</TT>,
<TT>leftMouseDragged</TT> or <TT>periodic</TT>. In addition to
that, you can specify combinations of these values by using the
<TT>|</TT> character; for example <TT>leftMouseDown||leftMouseUp</TT>
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).
</LI>
<LI><B>tag</B>: 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.
</LI>
<LI><B>textAlignment</B>: The alignment of the text (if needed).
This attribute is a string, and is optional. It can be set to
<TT>left</TT>, <TT>center</TT>, or <TT>right</TT>. If you specify a
size for the <TT><control></TT> 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.
</LI>
</UL>
<P>
The <TT><control></TT> tag supports the <TT>instanceOf</TT> attribute.
<P>
<H3><A NAME="SECTION00373300000000000000">
2.7.3.3 Possible object attributes</A>
</H3>
The <TT><control></TT> tag inherits all object attributes from the
generic <TT><view></TT>, and adds the following ones:
<UL>
<LI><B>target</B>: The target of the control.
</LI>
</UL>
<P>
<H3><A NAME="SECTION00373400000000000000">
2.7.3.4 Content</A>
</H3>
None.
<P>
<H3><A NAME="SECTION00373500000000000000">
2.7.3.5 Examples</A>
</H3>
In practice, <TT><control></TT> tags are rarely used. The only good
reason to use a <TT><control></TT> tag in practice is to create an
instance of a custom subclass of <TT>NSControl</TT>:
<PRE>
<control instanceOf="MapView" action="clickOnMap:" target="#NSOwner"
width="400" height="400" />
</PRE>
<P>
While <TT><control></TT> tags are rarely used, many common tags
inherit attributes from <TT><control></TT>; for example, buttons
inherit the <TT><control></TT> attributes, in particular the
<TT>action</TT>, <TT>target</TT> and <TT>enabled</TT> attributes used
to control how the control reacts to user actions (very common for
buttons), but also the <TT>font</TT> and <TT>textAlignment</TT>
attributes that control how the text is displayed (very common for
labels and textfields).
<P>
<H2><A NAME="SECTION00374000000000000000">
2.7.4 The hbox tag</A>
</H2>
<P>
<H3><A NAME="SECTION00374100000000000000">
2.7.4.1 Description</A>
</H3>
A <TT><hbox></TT> tag represents an invisible horizontal autolayout
container that can hold other views, and normally generates an
instance of <TT>GSAutoLayoutHBox</TT>.
<P>
There are two types of boxes:
<UL>
<LI><B>standard</B>: 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 <TT><hbox></TT> takes up all the
space allocated to it. If no views are marked as expand or wexpand,
then the <TT><hbox></TT> itself won't be expanding.
</LI>
<LI><B>proportional</B>: 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
<TT>proportion</TT> attribute set, which will cause it to cover a
different number of layout units. By default, all views have
proportion=1.
</LI>
</UL>
<P>
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.
<P>
<H3><A NAME="SECTION00374200000000000000">
2.7.4.2 Attributes</A>
</H3>
The <TT><hbox></TT> tag inherits all attributes from the generic
<TT><view></TT> tag; in addition, it has the following ones:
<UL>
<LI><B>type</B>: 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.
</LI>
</UL>
The <TT><hbox></TT> tag supports the <TT>instanceOf</TT> attribute.
<P>
<H3><A NAME="SECTION00374300000000000000">
2.7.4.3 Possible object attributes</A>
</H3>
The <TT><hbox></TT> tag inherits all object attributes from the
generic <TT><view></TT> tag but has none of its own.
<P>
<H3><A NAME="SECTION00374400000000000000">
2.7.4.4 Content</A>
</H3>
A <TT><hbox></TT> tag has its subviews as its content. They are
created in the order they are listed, and displayed from left to
right.
<P>
<H3><A NAME="SECTION00374500000000000000">
2.7.4.5 Examples</A>
</H3>
<TT><hbox></TT> 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:
<PRE>
<hbox>
<button title="Miniaturize" action="performMiniaturize:" />
<button title="Close" action="performClose:" />
</hbox>
</PRE>
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.
<P>
Here is the same example where the buttons are automatically sized
to have exactly the same size:
<PRE>
<hbox type="proportional">
<button title="Miniaturize" action="performMiniaturize:" />
<button title="Close" action="performClose:" />
</hbox>
</PRE>
<P>
It is quite possible and common to nest <TT><hbox></TT> and
<TT><vbox></TT> tags to create more complex layouts, as in the
following example where a textfield is on top of a row
of buttons:
<PRE>
<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>
</PRE>
<P>
<H2><A NAME="SECTION00375000000000000000">
2.7.5 The hspace tag</A>
</H2>
<P>
<H3><A NAME="SECTION00375100000000000000">
2.7.5.1 Description</A>
</H3>
<P>
A <TT><hspace></TT> tag represents invisible horizontal
weakly-expanding space that can be put into autolayout containers such
as <TT><hbox></TT> objects for alignment purporses. It normally
generates an instance of <TT>GSAutoLayoutHSpace</TT>.
<P>
An <TT><hspace></TT> 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.
<P>
Please note in vertical boxes (<TT><vbox></TT>) you should use
vertical spaces (<TT><vspace></TT>); it does not really make sense to
put a <TT><hspace></TT> inside a <TT><vbox></TT> since the
<TT><hspace></TT> only expand horizontally, not vertically.
<P>
<H3><A NAME="SECTION00375200000000000000">
2.7.5.2 Attributes</A>
</H3>
The <TT><hspace></TT> tag inherits all attributes from the generic
<TT><view></TT> tag but adds no new attributes of its own.
<P>
The <TT><hspace></TT> tag supports the <TT>instanceOf</TT> attribute.
<P>
<H3><A NAME="SECTION00375300000000000000">
2.7.5.3 Possible object attributes</A>
</H3>
The <TT><hspace></TT> tag inherits all object attributes from the
generic <TT><view></TT> tag but has none of its own.
<P>
<H3><A NAME="SECTION00375400000000000000">
2.7.5.4 Content</A>
</H3>
A <TT><hspace></TT> tag has no content.
<P>
<H3><A NAME="SECTION00375500000000000000">
2.7.5.5 Examples</A>
</H3>
<TT><hspace></TT> 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.
<P>
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
<TT><hspace></TT>, so the button always remains at the right end
of the <TT><hbox></TT>:
<PRE>
<hbox>
<hspace />
<button title="Close" action="performClose:" />
</hbox>
</PRE>
<P>
<TT><hspace></TT> tags rarely have any attributes and have never
any content.
<P>
<H2><A NAME="SECTION00376000000000000000">
2.7.6 The image tag</A>
</H2>
<P>
<H3><A NAME="SECTION00376100000000000000">
2.7.6.1 Description</A>
</H3>
An <TT><image></TT> tag represents an image, and normally generates an
instance of <TT>NSImageView</TT>. An <TT>NSImageView</TT> is a
control which is used to display an image. Normally, you specify the
image by putting an <TT>name="xxx"</TT> attribute into the tag, and
the <TT>NSImageView</TT> is automatically sized to fit the image. The
value of the <TT>name</TT> attribute is a string, which is used as
argument to the <TT>NSImage</TT> method <TT>+imageNamed:</TT>.
Typically you put the image (as a .png, or .gif, or .jpeg , or .tiff
file) in the main application bundle.
<P>
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 <TT>-setImage:</TT> of the
<TT>NSImageView</TT>), after the file has been loaded; or you can
force a size of the image view (by using the <TT>width</TT> and
<TT>height</TT> attributes which the <TT><image></TT> tag inherits
from the generic <TT><view></TT> 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 <TT>editable="yes"</TT>), and then the
user can change the image by dragging&dropping images from elsewhere.
<P>
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
<TT>scaling</TT> attribute, and how to align the image in the area (if
not all of it is covered after the specified scaling) by using the
<TT>alignment</TT> attribute. Please check the <TT>NSImageView</TT>
documentation for more information on scaling and alignment.
<P>
<H3><A NAME="SECTION00376200000000000000">
2.7.6.2 Attributes</A>
</H3>
The <TT><image></TT> tag inherits all attributes from the generic
<TT><control></TT> and <TT><view></TT> tags; in addition, it has
the following ones:
<UL>
<LI><B>imageAlignment</B>: The alignment (if needed). This attribute
is a string, and is optional. It can be set to <TT>bottom</TT>,
<TT>bottomLeft</TT>, <TT>bottomRight</TT>, <TT>center</TT>,
<TT>left</TT>, <TT>right</TT>, <TT>top</TT>, <TT>topLeft</TT> or
<TT>topRight</TT>. If you specify a size for the <TT><image></TT>
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.
</LI>
<LI><B>frameStyle</B>: The type of frame (if used). This attribute
is a string, and it is optional. It can be set to <TT>button</TT>,
<TT>grayBezel</TT>, <TT>groove</TT>, <TT>none</TT> or
<TT>photo</TT>. 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 <TT>hasFrame="yes"</TT> and let the
system choose the natural native frame style, whatever that is.
</LI>
<LI><B>hasFrame</B>: A boolean: if set to <TT>yes</TT>, 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.
</LI>
<LI><B>name</B>: 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
<TT>[NSImage +imageNamed:]</TT>, where the value of this attribute
is used as the argument; if this attribute is not set, no image is
actually displayed.
</LI>
<LI><B>scaling</B>: The type of scaling (if needed). This attribute
is a string, and it is optional. It can be set to <TT>none</TT>,
<TT>proportionally</TT> or <TT>toFit</TT>. 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.
</LI>
</UL>
<P>
The <TT><image></TT> tag supports the <TT>instanceOf</TT> attribute.
<P>
<H3><A NAME="SECTION00376300000000000000">
2.7.6.3 Possible object attributes</A>
</H3>
The <TT><image></TT> tag inherits all object attributes from the
generic <TT><control></TT> and <TT><view></TT> tags, but adds no
specific of its own.
<P>
<H3><A NAME="SECTION00376400000000000000">
2.7.6.4 Content</A>
</H3>
An <TT><image></TT> tag has no content.
<P>
<H3><A NAME="SECTION00376500000000000000">
2.7.6.5 Examples</A>
</H3>
In the typical usage, you have an image in your main application
bundle called for example <TT>GreenArrow.png</TT>. To display the
image in a window, you can use the <TT><image></TT> tag:
<PRE>
<image name="GreenArrow" />
</PRE>
<P>
<H2><A NAME="SECTION00377000000000000000">
2.7.7 The instance tag</A>
</H2>
<P>
<H3><A NAME="SECTION00377100000000000000">
2.7.7.1 Description</A>
</H3>
An <TT><instance></TT> tag represents an instance of a custom class. You
specify the custom class and an object of that class is created.
<P>
<H3><A NAME="SECTION00377200000000000000">
2.7.7.2 Attributes</A>
</H3>
<UL>
<LI><B>instanceOf</B>: The name of the class. This attribute is a
string, and is required.
</LI>
</UL>
<P>
<H3><A NAME="SECTION00377300000000000000">
2.7.7.3 Possible object attributes</A>
</H3>
This depends on the class - each class has different object attributes.
<P>
<H3><A NAME="SECTION00377400000000000000">
2.7.7.4 Content</A>
</H3>
No content.
<P>
<H3><A NAME="SECTION00377500000000000000">
2.7.7.5 Examples</A>
</H3>
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.
<PRE>
<instance instanceOf="MyController" id="Controller"
textField="#TextField" />
</PRE>
in this example, the class <TT>MyController</TT> should have the method
<TT>setTextField:</TT>.
<P>
<H2><A NAME="SECTION00378000000000000000">
2.7.8 The label tag</A>
</H2>
<P>
<H3><A NAME="SECTION00378100000000000000">
2.7.8.1 Description</A>
</H3>
A <TT><label></TT> tag represents a non-editable string displayed
inside the window; it normally generates an instance of
<TT>NSTextField</TT> configured to be non-editable and with no border.
<P>
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.
<P>
A <TT><label></TT> tag draws its background if and only if the
<TT>backgroundColor</TT> attribute is set.
<P>
<H3><A NAME="SECTION00378200000000000000">
2.7.8.2 Attributes</A>
</H3>
A <TT><label></TT> inherits all the attributes of the <TT><view></TT>
and <TT><control></TT> tags; moreover, it supports the following ones:
<UL>
<LI><B>backgroundColor</B>: 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.
</LI>
<LI><B>textColor</B>: a color attribute that determines the color
used to draw the text.
</LI>
<LI><B>selectable</B>: 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).
</LI>
</UL>
<P>
The <TT><label></TT> tag supports the <TT>instanceOf</TT> attribute.
<P>
<H3><A NAME="SECTION00378300000000000000">
2.7.8.3 Possible object attributes</A>
</H3>
The <TT><label></TT> tag inherits all object attributes from the
generic <TT><control></TT> and <TT><view></TT> tags, but adds no
specific of its own.
<P>
<H3><A NAME="SECTION00378400000000000000">
2.7.8.4 Content</A>
</H3>
The content of a <TT>label</TT> tag is the localized string that is
displayed by the label.
<P>
<H3><A NAME="SECTION00378500000000000000">
2.7.8.5 Examples</A>
</H3>
In most cases, a <TT>label</TT> tag works very well with no attributes:
<PRE>
<label>Path to the executable</label>
</PRE>
<P>
The most common attribute for labels is the <TT>font</TT> attribute,
as in the following example showing labels with different fonts:
<PRE>
<window>
<vbox>
<label font="big">Big font</label>
<label>Normal font</label>
<label font="small">Small font</label>
</vbox>
</window>
</PRE>
<P>
You may also want to set the color and/or background:
<PRE>
<label textColor="blue" backgroundColor="white">Blue on white</label>
</PRE>
<P>
<H2><A NAME="SECTION00379000000000000000">
2.7.9 The menu tag</A>
</H2>
<P>
<H3><A NAME="SECTION00379100000000000000">
2.7.9.1 Description</A>
</H3>
A <TT><menu></TT> tag represents a menu, and normally generates an
instance of <TT>NSMenu</TT>.
<P>
<H3><A NAME="SECTION00379200000000000000">
2.7.9.2 Attributes</A>
</H3>
<UL>
<LI><B>autoenablesItems</B>: A boolean: if set to <TT>no</TT>,
disables autoenabling of its menu items (which is otherwise enabled
by default).
</LI>
<LI><B>title</B>: The title of the menu (a localizable string).
</LI>
<LI><B>type</B>: If set to <TT>main</TT>, then the menu is made the
application main menu (by invoking <TT>setMainMenu:</TT> of the
shared <TT>NSApplication</TT>). If set to <TT>windows</TT>, then
the menu is made the application windows menu (by invoking
<TT>setWindowsMenu:</TT> of the shared <TT>NSApplication</TT>). If
set to <TT>services</TT>, then the menu is made the application
services menu (by invoking <TT>setServicesMenu:</TT> of the shared
<TT>NSApplication</TT>). If set to <TT>font</TT>, then the menu is
created as the font menu (by using the menu <TT>fontMenu:</TT> of
the shared <TT>NSFontManager</TT>); 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
<TT>apple</TT>, then the menu is made the application apple menu (by
invoking <TT>setAppleMenu:</TT> of the shared
<TT>NSApplication</TT>); if running on Apple Mac OS X; it is ignored
otherwise.
</LI>
</UL>
<P>
The <TT><menu></TT> tag does not support the <TT>instanceOf</TT> attribute.
<P>
<H3><A NAME="SECTION00379300000000000000">
2.7.9.3 Possible object attributes</A>
</H3>
None.
<P>
<H3><A NAME="SECTION00379400000000000000">
2.7.9.4 Content</A>
</H3>
A menu can contain <TT>menuItem</TT>, <TT>menuSeparator</TT> and
<TT>menu</TT> tags. Each <TT>menuItem</TT> tag represents a menu item
which is added to the menu. Each <TT>menuSeparator</TT> tag
represents a menu separator which is added to the menu. Each
<TT>menu</TT> represents a submenu.
<P>
<H3><A NAME="SECTION00379500000000000000">
2.7.9.5 Examples</A>
</H3>
Normally, the only attribute of menus you're likely to use is the
<TT>type</TT> attribute, which is used to make a menu the main, windows,
services or font menu.
<PRE>
<menu type="main">
<menuItem title="Info Panel..." action="orderFrontStandardInfoPanel:" />
<menuItem title="Hide" action="hide:" keyEquivalent="h" />
<menuItem title="Quit" action="terminate:" keyEquivalent="q" />
</menu>
</PRE>
<P>
Here is an example of a menu holding a submenu:
<PRE>
<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>
</PRE>
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.
<P>
<H3><A NAME="SECTION00379600000000000000">
2.7.9.6 Portability</A>
</H3>
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.
<P>
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 <TT>main()</TT> function, before calling
<TT>NSApplicationMain()</TT> (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 <TT>main</TT>
menu, containing the <TT>apple</TT> submenu as its first item. There
should be one, and only one, <TT>apple</TT> 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
<TT>Examples/Applications/CurrencyConverter</TT> in the Renaissance
distribution).
<P>
<H2><A NAME="SECTION003710000000000000000">
2.7.10 The menuItem tag</A>
</H2>
<P>
<H3><A NAME="SECTION003710100000000000000">
2.7.10.1 Description</A>
</H3>
A <TT><menuItem></TT> tag represents a menu item to be added to a menu,
and normally generates an instance of <TT>NSMenuItem</TT>.
<P>
<H3><A NAME="SECTION003710200000000000000">
2.7.10.2 Attributes</A>
</H3>
<UL>
<LI><B>action</B>: The action of the menuItem (a string, non
localized, which is converted into a selector).
</LI>
<LI><B>enabled</B>: A boolean; if <TT>no</TT>, the menuItem is
disabled (it is enabled by default). If your menu autoenables its
items, this is not particularly useful.
</LI>
<LI><B>image</B>: The image of the menuItem (an image).
</LI>
<LI><B>keyEquivalent</B>: The keyEquivalent of the menuItem (normally
a single character).
</LI>
<LI><B>keyEquivalentModifierMask</B>: 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 <TT>commandKey</TT>). It can be set to <TT>noKey</TT>,
<TT>shiftKey</TT>, <TT>commandKey</TT>, <TT>controlKey</TT> or
<TT>alternateKey</TT>. In addition to that, you can specify
combinations of these values by using the <TT>|</TT> character; for
example <TT>commandKey||controlKey</TT> 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).
</LI>
<LI><B>state</B>: The state of the menuItem (either <TT>on</TT>, or
<TT>off</TT> or <TT>mixed</TT>). 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.
</LI>
<LI><B>tag</B>: The tag of the menuItem (an integer).
</LI>
<LI><B>title</B>: The title of the menuItem (a localizable string).
</LI>
</UL>
<P>
The <TT><menuItem></TT> tag does not support the <TT>instanceOf</TT> attribute.
<P>
<H3><A NAME="SECTION003710300000000000000">
2.7.10.3 Possible object attributes</A>
</H3>
<UL>
<LI><B>target</B>: The target of the menuItem.
</LI>
<LI><B>representedObject</B>: The representedObject of the menuItem.
</LI>
</UL>
<P>
<H3><A NAME="SECTION003710400000000000000">
2.7.10.4 Content</A>
</H3>
A menuItem has no content.
<P>
<H3><A NAME="SECTION003710500000000000000">
2.7.10.5 Examples</A>
</H3>
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:
<PRE>
<menuItem title="Quit" action="terminate:" />
</PRE>
Here is an example of a menuItem displaying an on/off tickmark and
changing state:
<PRE>
<menu title="Options">
<menuItem title="Full Headers" state="on" action="fullHeadersChanged:" />
<menuItem title="Hide spam" state="on" action="hideSpamChanged:" />
</menu>
</PRE>
You need to implement the actions, and have them change the state of the
menuItem each time, to see the state change.
<P>
<H2><A NAME="SECTION003711000000000000000">
2.7.11 The menuSeparator tag</A>
</H2>
<P>
<H3><A NAME="SECTION003711100000000000000">
2.7.11.1 Description</A>
</H3>
A <TT><menuSeparator></TT> tag represents a separator in a menu, and
normally inserts into the menu a <TT>[NSMenuItem separatorItem]</TT>.
It is a very simple tag, with no attributes nor content; it is opened,
and immediately closed, as in
<PRE>
<menuSeparator />
</PRE>
It can only be used inside the contents of a menu. It is usually
represented by a <TT>[NSMenuItem separatorItem]</TT> object, but that
is not compulsory - it can be mapped to whatever standard way of
inserting separators in NSMenus is used on that platform.
<P>
<H3><A NAME="SECTION003711200000000000000">
2.7.11.2 Attributes</A>
</H3>
A <TT>menuSeparator</TT> tag has no attributes. The
<TT><menuSeparator></TT> tag does not support the <TT>instanceOf</TT>
attribute.
<P>
<H3><A NAME="SECTION003711300000000000000">
2.7.11.3 Possible object attributes</A>
</H3>
A <TT>menuSeparator</TT> tag has no possible object attributes.
<P>
<H3><A NAME="SECTION003711400000000000000">
2.7.11.4 Content</A>
</H3>
A <TT>menuSeparator</TT> tag has no content.
<P>
<H3><A NAME="SECTION003711500000000000000">
2.7.11.5 Examples</A>
</H3>
A menuSeparator is often used on Apple Mac OS X to visually separate and
group menu items in menus, as in the following example:
<PRE>
<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>
</PRE>
<P>
<H2><A NAME="SECTION003712000000000000000">
2.7.12 The panel tag</A>
</H2>
<P>
<H3><A NAME="SECTION003712100000000000000">
2.7.12.1 Description</A>
</H3>
A <TT><panel></TT> tag represents a panel, and normally generates an
instance of <TT>NSPanel</TT>. 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 <TT>NSPanel</TT>
instead of a <TT>NSWindow</TT> object, and that it has a few more
attributes, specific to panels.
<P>
<H3><A NAME="SECTION003712200000000000000">
2.7.12.2 Attributes</A>
</H3>
All the attributes recognized by the <TT><window></TT> tag, plus:
<UL>
<LI><B>becomesKeyOnlyIfNeeded</B>: A boolean. If set to yes, sets
the panel to become key only if needed.
</LI>
<LI><B>floating</B>: A boolean. If set to yes, sets the panel to be
a floating panel.
</LI>
<LI><B>worksWhenModal</B>: A boolean. If set to yes, sets the panel
to work when modal.
</LI>
</UL>
<P>
The <TT><panel></TT> tag supports the <TT>instanceOf</TT> attribute.
<P>
<H3><A NAME="SECTION003712300000000000000">
2.7.12.3 Possible object attributes</A>
</H3>
The same possible object attributes as for the <TT><window></TT> tag.
<P>
<H3><A NAME="SECTION003712400000000000000">
2.7.12.4 Content</A>
</H3>
The same content as the <TT><window></TT> tag.
<P>
<H3><A NAME="SECTION003712500000000000000">
2.7.12.5 Examples</A>
</H3>
<PRE>
<panel title="Inspector" autosaveName="Inspector" floating="yes">
<vbox>
<!-- all sort of goodies go in here -->
</vbox>
</panel>
</PRE>
<P>
<H2><A NAME="SECTION003713000000000000000">
2.7.13 The secureTextField tag</A>
</H2>
<P>
<H3><A NAME="SECTION003713100000000000000">
2.7.13.1 Description</A>
</H3>
A <TT><secureTextField></TT> 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
<TT>NSSecureTextField</TT> configured to be editable, selectable and
with the distinctive appearance of a secure, editable text field.
<P>
The only difference between a <TT><secureTextField></TT> tag and a
<TT><textField></TT> one is that a <TT><secureTextField></TT> creates
an instance of <TT>NSSecureTextField</TT>, 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.
<P>
<H3><A NAME="SECTION003713200000000000000">
2.7.13.2 Attributes</A>
</H3>
A <TT><secureTextField></TT> has exactly the same attributes as a
<TT><textField></TT> tag.
<P>
<H3><A NAME="SECTION003713300000000000000">
2.7.13.3 Possible object attributes</A>
</H3>
A <TT><secureTextField></TT> has exactly the same possible object
attributes as a <TT><textField></TT> tag.
<P>
<H3><A NAME="SECTION003713400000000000000">
2.7.13.4 Content</A>
</H3>
A <TT><secureTextField></TT> has exactly the same content as a
<TT><textField></TT> tag.
<P>
<H3><A NAME="SECTION003713500000000000000">
2.7.13.5 Examples</A>
</H3>
In most cases, a <TT>secureTextField</TT> tag works very well with no
attributes, or with a minimal width set:
<PRE>
<hbox><label>Password:</label> <secureTextField width="200" /></hbox>
</PRE>
For more examples, see the description of <TT><textField></TT>.
<P>
<H2><A NAME="SECTION003714000000000000000">
2.7.14 The textField tag</A>
</H2>
<P>
<H3><A NAME="SECTION003714100000000000000">
2.7.14.1 Description</A>
</H3>
A <TT><textField></TT> tag represents an editable text field displayed
inside the window; it normally generates an instance of
<TT>NSTextField</TT> configured to be editable, selectable and with
the distinctive appearance of an editable text field.
<P>
You can also make the control non-editable or non-selectable by using
the corresponding attributes.
<P>
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.
<P>
<H3><A NAME="SECTION003714200000000000000">
2.7.14.2 Attributes</A>
</H3>
A <TT><textField></TT> inherits all the attributes of the
<TT><view></TT> and <TT><control></TT> tags; moreover, it supports the
following ones:
<UL>
<LI><B>allowsEditingTextAttributes</B>: a boolean attribute. When
set to yes, the user can edit the font and text attributes of the
text displayed in the text field.
</LI>
<LI><B>backgroundColor</B>: a color attribute that determines the
color of the background.
</LI>
<LI><B>drawsBackground</B>: 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.
</LI>
<LI><B>editable</B>: 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.
</LI>
<LI><B>importsGraphics</B>: a boolean attribute. When set to yes,
the user can drag image files into the text field.
</LI>
<LI><B>selectable</B>: 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.
</LI>
<LI><B>textColor</B>: a color attribute that determines the color
used to draw the text.
</LI>
</UL>
<P>
The <TT><textField></TT> tag supports the <TT>instanceOf</TT> attribute.
<P>
<H3><A NAME="SECTION003714300000000000000">
2.7.14.3 Possible object attributes</A>
</H3>
The <TT><textField></TT> tag inherits all object attributes from the
generic <TT><control></TT> and <TT><view></TT> tags, and adds:
<UL>
<LI><B>delegate</B>: The delegate of the text field (see the
documentation of the NSTextField class for more information on using
delegates).
</LI>
</UL>
<P>
<H3><A NAME="SECTION003714400000000000000">
2.7.14.4 Content</A>
</H3>
The content of a <TT>textField</TT> tag is the localized string that
is displayed in the text field.
<P>
<H3><A NAME="SECTION003714500000000000000">
2.7.14.5 Examples</A>
</H3>
In most cases, a <TT>textField</TT> tag works very well with no attributes:
<PRE>
<hbox><label>Name:</label> <textField /></hbox>
</PRE>
<P>
Sometimes you may want to set the <TT>delegate</TT> attribute if you
want your software to be informed in real-time of changes to the text
field contents:
<PRE>
<hbox><label>Name:</label> <textField delegate="#NSOwner" /></hbox>
</PRE>
You then need to implement the appropriate text field delegate methods
in your file owner object.
<P>
<H2><A NAME="SECTION003715000000000000000">
2.7.15 The vbox tag</A>
</H2>
<P>
<H3><A NAME="SECTION003715100000000000000">
2.7.15.1 Description</A>
</H3>
A <TT><vbox></TT> tag represents an invisible vertical autolayout
container that can hold other views, and normally generates an
instance of <TT>GSAutoLayoutHBox</TT>.
<P>
A <TT><vbox></TT> object is identical to a <TT><hbox></TT> object, but
it holds views in a column instead of a row. Please refer to the
description of the <TT><hbox></TT> tag for details of the tag.
<P>
<H3><A NAME="SECTION003715200000000000000">
2.7.15.2 Attributes</A>
</H3>
The <TT><vbox></TT> tag inherits all attributes from the generic
<TT><view></TT> tag; in addition, it has the following ones:
<UL>
<LI><B>type</B>: 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.
</LI>
</UL>
The <TT><vbox></TT> tag supports the <TT>instanceOf</TT> attribute.
<P>
<H3><A NAME="SECTION003715300000000000000">
2.7.15.3 Possible object attributes</A>
</H3>
The <TT><vbox></TT> tag inherits all object attributes from the
generic <TT><view></TT> tag but has none of its own.
<P>
<H3><A NAME="SECTION003715400000000000000">
2.7.15.4 Content</A>
</H3>
A <TT><vbox></TT> tag has its subviews as its content. They are
created in the order they are listed, and displayed from top to
bottom.
<P>
<H3><A NAME="SECTION003715500000000000000">
2.7.15.5 Examples</A>
</H3>
See the examples for the <TT><hbox></TT> tag.
<P>
<H2><A NAME="SECTION003716000000000000000">
2.7.16 The view tag</A>
</H2>
<P>
<H3><A NAME="SECTION003716100000000000000">
2.7.16.1 Description</A>
</H3>
A <TT><view></TT> tag represents a view, and normally generates an
instance of <TT>NSView</TT>. Instances of <TT>NSView</TT> are not
particularly useful as they are (<TT>NSView</TT> instances represent
rectangular regions in a window, and don't do much), which is why
<TT><view></TT> tags are normally only used with an <TT>instanceOf</TT>
attribute to create custom view objects.
<P>
The attributes of <TT><view></TT> tags are inherited by all tags whose
instances inherit from <TT>NSView</TT> - this includes anything you
can put inside a window. Of particular interest is the autolayout
behaviour, which is again inherited by all tags.
<P>
When the view instance created by a <TT><view></TT> tag is
initialized, the method <TT>sizeToFitContent</TT> of the instance is
first called. This method resizes the instance to fit its content.
Then, the <TT>x</TT>, <TT>y</TT> <TT>height</TT> and <TT>width</TT>
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 <TT>x</TT>,
<TT>y</TT>, <TT>height</TT> or <TT>width</TT> overrides the
automatically computed size and position.
<P>
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 <TT>halign</TT>,
<TT>valign</TT>, <TT>hborder</TT>, <TT>vborder</TT> and <TT>span</TT>.
There is also an additional attribute <TT>border</TT>, which is a
currently a short-cut for setting both the <TT>hborder</TT> and
<TT>vborder</TT> attributes (and might be removed in the future).
<P>
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. <TT>halign</TT> and
<TT>valign</TT> 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; <TT>hborder</TT> and
<TT>vborder</TT> control the horizontal and vertical border around the
view when in the container; <TT>span</TT> is used with proportional
boxes, for special effects when a view spans more than a single slot
in the box.
<P>
The system will also set default values for the
<TT>autoresizingMask</TT> basing on the autolayout properties, so that
if you put your view inside an old-fashioned container such as a
<TT><box></TT>, you can control its autoresizing behaviour using the
usual autolayout flags.
<P>
<H3><A NAME="SECTION003716200000000000000">
2.7.16.2 Attributes</A>
</H3>
<UL>
<LI><B>autoresizesSubviews</B>: 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.
</LI>
<LI><B>autoresizingMask</B>: 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 <TT>halign</TT> and <TT>valign</TT> 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
<TT>halign</TT> and <TT>valign</TT>. 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 '<TT>h</TT>'
means to set the <TT>NSViewHeightSizable</TT> flag; a '<TT>w</TT>'
means to set the <TT>NSViewWidthSizable</TT> flag; a '<TT>x</TT>'
means to set the <TT>NSViewMinXMargin</TT> flag; a '<TT>X</TT>'
means to set the <TT>NSViewMaxXMargin</TT> flag; a '<TT>y</TT>'
means to set the <TT>NSViewMinYMargin</TT> flag; a '<TT>Y</TT>'
means to set the <TT>NSViewMaxYMargin</TT> flag. For example, an
attribute value of ``hw'' means <TT>NSViewHeightSizable |
NSViewWidthSizable</TT>. 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 <TT>halign</TT> and <TT>valign</TT>
property; if any of the two is not set, the object's
<TT>-autolayoutDefaultHorizontalAlignment</TT> or
<TT>-autolayoutDefaultVerticalAlignment</TT> method is called to get
a default value that can be used.
</LI>
<LI><B>border</B>: A float. If set, this is equivalent to setting
both <TT>hborder</TT> and <TT>vborder</TT> to that same value. This
attribute might be removed in future releases.
</LI>
<LI><B>halign</B>: A string, which can take one of the values
<TT>expand</TT>, <TT>wexpand</TT>, <TT>left</TT>, <TT>center</TT>,
<TT>right</TT>. <TT>min</TT> is also accepted as an alias for
<TT>left</TT>, and <TT>max</TT> as an alias for <TT>right</TT>.
This attribute is only used by an eventual enclosing autolayout
container (such as a hbox or a vbox). <TT>expand</TT> 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. <TT>wexpand</TT> 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. <TT>left</TT>, <TT>center</TT> and <TT>right</TT>
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 <A HREF="node11.html#autolayout-flags">1.9</A>.
</LI>
<LI><B>hborder</B>: 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).
</LI>
<LI><B>height</B>: 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.
</LI>
<LI><B>hidden</B>: A boolean. If set to yes, it changes the view to
be hidden.
</LI>
<LI><B>proportion</B>: 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
<TT>proportion="2"</TT> attribute takes up twice the space as normal
view in a proportional hbox.
</LI>
<LI><B>toolTip</B>: A localizable string. If set, the view tool tip
is set to it.
</LI>
<LI><B>valign</B>: A string, which can take one of the values
<TT>expand</TT>, <TT>wexpand</TT>, <TT>top</TT>, <TT>center</TT>,
<TT>bottom</TT>. <TT>min</TT> is also accepted as an alias for
<TT>bottom</TT>, and <TT>max</TT> as an alias for <TT>top</TT>.
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
<TT>halign</TT> attribute; the attribute values have the same
meaning in the vertical direction.
</LI>
<LI><B>vborder</B>: 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).
</LI>
<LI><B>width</B>: 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.
</LI>
<LI><B>x</B>: A float. If set, the x coordinate of the origin of the
view frame is set to this value.
</LI>
<LI><B>y</B>: A float. If set, the y coordinate of the origin of the
view frame is set to this value.
</LI>
</UL>
<P>
The <TT><view></TT> tag supports the <TT>instanceOf</TT> attribute.
<P>
<H3><A NAME="SECTION003716300000000000000">
2.7.16.3 Possible object attributes</A>
</H3>
<UL>
<LI><B>nextKeyView</B>: 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!).
</LI>
</UL>
<P>
<H3><A NAME="SECTION003716400000000000000">
2.7.16.4 Content</A>
</H3>
Usually <TT><view></TT> 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 <TT><hbox></TT> or <TT><vbox></TT> 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.
<P>
To support corner cases and static placement of subviews, if you add
some view tags as content to a <TT><view></TT> 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 <TT><view></TT> 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).
<P>
<H3><A NAME="SECTION003716500000000000000">
2.7.16.5 Examples</A>
</H3>
Usually <TT><view></TT> tags are used to create custom views, in which
case the <TT>instanceOf</TT> is used. Custom views representing
editable areas often have have hardcoded <TT>width</TT> and
<TT>height</TT> attributes - but other types of custom views might
be able/need to autosize.
<PRE>
<view instanceOf="BandView" id="BandView" width="200" height="100" />
</PRE>
<P>
Here is an example of using a <TT><view></TT> tag to create a view and
put some subviews at fixed locations into it:
<PRE>
<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>
</PRE>
<P>
<H2><A NAME="SECTION003717000000000000000">
2.7.17 The vspace tag</A>
</H2>
<P>
<H3><A NAME="SECTION003717100000000000000">
2.7.17.1 Description</A>
</H3>
<P>
A <TT><vspace></TT> tag represents invisible vertical weakly-expanding
space that can be put into autolayout containers such as
<TT><vbox></TT> objects for alignment purporses. It normally
generates an instance of <TT>GSAutoLayoutVSpace</TT>.
<P>
A <TT><vspace></TT> is identical to a <TT><hspace></TT>, but expands
vertically instead of horizontally. You should always use
<TT><vspace></TT> tags inside <TT><vbox></TT> tags, and
<TT><hspace></TT> tags inside <TT><hbox></TT> tags.
<P>
<H3><A NAME="SECTION003717200000000000000">
2.7.17.2 Attributes</A>
</H3>
The <TT><vspace></TT> tag inherits all attributes from the generic
<TT><view></TT> tag but adds no new attributes of its own.
<P>
The <TT><vspace></TT> tag supports the <TT>instanceOf</TT> attribute.
<P>
<H3><A NAME="SECTION003717300000000000000">
2.7.17.3 Possible object attributes</A>
</H3>
The <TT><vspace></TT> tag inherits all object attributes from the
generic <TT><view></TT> tag but has none of its own.
<P>
<H3><A NAME="SECTION003717400000000000000">
2.7.17.4 Content</A>
</H3>
A <TT><vspace></TT> tag has no content.
<P>
<H3><A NAME="SECTION003717500000000000000">
2.7.17.5 Examples</A>
</H3>
See the examples for the <TT><vspace></TT> tag.
<P>
<H2><A NAME="SECTION003718000000000000000">
2.7.18 The window tag</A>
</H2>
<H3><A NAME="SECTION003718100000000000000">
2.7.18.1 Description</A>
</H3>
A <TT><window></TT> tag represents a window, and normally generates an
instance of <TT>NSWindow</TT>. 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.
<P>
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).
<P>
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 <TT>expand</TT> set in a direction, Renaissance
records that the window should be made resizable in that direction; if
it set to anything else (including <TT>wexpand</TT>), 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).
<P>
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.
<P>
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.
<P>
Last, the window is ordered front (by using <TT>orderFront:</TT>),
unless the attribute visible has been set to no; it is also made the
key window (by using <TT>makeKeyWindow</TT>) 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
<TT>makeMainWindow</TT>).
<P>
<H3><A NAME="SECTION003718200000000000000">
2.7.18.2 Attributes</A>
</H3>
<UL>
<LI><B>autosaveName</B>: 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.
</LI>
<LI><B>backgroundColor</B>: A color. If set, the window natural
background color is overridden by this color.
</LI>
<LI><B>borderless</B>: A boolean. If set to yes, the window is
created without any decorations.
</LI>
<LI><B>center</B>: A boolean. If set to yes, the window is
automatically centered when it is created.
</LI>
<LI><B>closable</B>: 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).
</LI>
<LI><B>contentHeight</B>: 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).
</LI>
<LI><B>contentWidth</B>: 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).
</LI>
<LI><B>heigth</B>: A positive float. If set, the heigth of the
window frame is set to this value. See comments for <B>x</B> about
interaction with autosaved frame.
</LI>
<LI><B>keyWindow</B>: 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.
</LI>
<LI><B>mainWindow</B>: 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.
</LI>
<LI><B>maxHeigth</B>: A positive float. If set, the heigth of the
window maximum size is set to this value.
</LI>
<LI><B>maxWidth</B>: A positive float. If set, the width of the
window maximum size is set to this value.
</LI>
<LI><B>minHeigth</B>: A positive float. If set, the heigth of the
window minimum size is set to this value.
</LI>
<LI><B>minWidth</B>: A positive float. If set, the width of the
window minimum size is set to this value.
</LI>
<LI><B>miniaturizable</B>: A boolean. If set to no, the window is
created non miniaturizable (it is miniaturizable otherwise, unless
borderless is set to yes).
</LI>
<LI><B>releasedWhenClosed</B>: 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.
</LI>
<LI><B>resizable</B>: 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).
</LI>
<LI><B>title</B>: A localizable string. If set, the window title is
set to it.
</LI>
<LI><B>titled</B>: A boolean. If set to no, the window is created
without a titlebar (it has a titlebar otherwise, unless borderless
is set to yes).
</LI>
<LI><B>visible</B>: 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 <TT>orderFront:</TT>) after
they are created. By setting visible to no, you can prevent this to
happen.
</LI>
<LI><B>width</B>: A positive float. If set, the width of the window
frame is set to this value. See comments for <B>x</B> about
interaction with autosaved frame.
</LI>
<LI><B>x</B>: 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.
</LI>
<LI><B>y</B>: A float. If set, the y coordinate of the origin of the
window frame is set to this value. See comments for <B>x</B> about
interaction with autosaved frame.
</LI>
</UL>
<P>
The <TT><window></TT> tag supports the <TT>instanceOf</TT> attribute.
<P>
<H3><A NAME="SECTION003718300000000000000">
2.7.18.3 Possible object attributes</A>
</H3>
<UL>
<LI><B>delegate</B>: The window delegate.
</LI>
<LI><B>initialFirstResponder</B>: The window initialFirstResponder.
</LI>
</UL>
<P>
<H3><A NAME="SECTION003718400000000000000">
2.7.18.4 Content</A>
</H3>
A <TT><window></TT> 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.
<P>
<H3><A NAME="SECTION003718500000000000000">
2.7.18.5 Examples</A>
</H3>
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 <TT><panel></TT>
tag, which accepts all the attributes of a <TT><window></TT> tag, but
creates a <TT>NSPanel</TT> rather than a <TT>NSWindow</TT> (and has a
few panelish attributes more). An example window with nothing inside:
<PRE>
<window title="My First Window" />
</PRE>
A window containing a button:
<PRE>
<window title="Test" center="yes" autosaveName="terminate">
<button title="Click to quit the application" action="terminate:">
</window>
</PRE>
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:
<PRE>
<window title="frame of 500x100" autosaveName="fixedFrameExample"
width="500" heigth="100" />
</PRE>
<P>
<HR><B> Next: <A NAME="tex2html753"
HREF="node22.html">2.8 Connector tag reference</A> </B>
<B>Up: <A NAME="tex2html749"
HREF="node14.html">2. The GNUstep Markup</A> </B>
<B> Previous: <A NAME="tex2html743"
HREF="node20.html">2.6 Integrating Renaissance in</A> </B>
<!--End of Navigation Panel-->
<ADDRESS>
2008-03-19
</ADDRESS>
</BODY>
</HTML>
Server : Apache/2.4.41 (Ubuntu)