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/node17.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.3 The objects section</TITLE>
<META NAME="description" CONTENT="2.3 The objects section">
<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="node18.html">
<LINK REL="previous" HREF="node16.html">
<LINK REL="up" HREF="node14.html">
<LINK REL="next" HREF="node18.html">
</HEAD>
<BODY BGCOLOR="#FFFFFF" text="#000000" link="#0000FF" vlink="#4444FF" alink="#3388FF">
<B> Next: <A NAME="tex2html665"
HREF="node18.html">2.4 The connectors section</A> </B>
<B>Up: <A NAME="tex2html661"
HREF="node14.html">2. The GNUstep Markup</A> </B>
<B> Previous: <A NAME="tex2html655"
HREF="node16.html">2.2 General overview of</A> </B>
<BR> <P>
<!--End of Navigation Panel-->
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
<UL>
<LI><A NAME="tex2html666"
HREF="node17.html#SECTION00331000000000000000">2.3.1 Relationship between tags and objects</A>
<LI><A NAME="tex2html667"
HREF="node17.html#SECTION00332000000000000000">2.3.2 Object tags - basic example</A>
<LI><A NAME="tex2html668"
HREF="node17.html#SECTION00333000000000000000">2.3.3 Object tags - attributes</A>
<UL>
<LI><A NAME="tex2html669"
HREF="node17.html#SECTION00333100000000000000">2.3.3.1 String attributes</A>
<LI><A NAME="tex2html670"
HREF="node17.html#SECTION00333200000000000000">2.3.3.2 Localizable strings attributes</A>
<LI><A NAME="tex2html671"
HREF="node17.html#SECTION00333300000000000000">2.3.3.3 Boolean attributes</A>
<LI><A NAME="tex2html672"
HREF="node17.html#SECTION00333400000000000000">2.3.3.4 Number attributes</A>
<LI><A NAME="tex2html673"
HREF="node17.html#SECTION00333500000000000000">2.3.3.5 Image attributes</A>
<LI><A NAME="tex2html674"
HREF="node17.html#SECTION00333600000000000000">2.3.3.6 Sound attributes</A>
<LI><A NAME="tex2html675"
HREF="node17.html#SECTION00333700000000000000">2.3.3.7 Color attributes</A>
<LI><A NAME="tex2html676"
HREF="node17.html#SECTION00333800000000000000">2.3.3.8 Font attributes</A>
<LI><A NAME="tex2html677"
HREF="node17.html#SECTION00333900000000000000">2.3.3.9 The instanceOf attribute</A>
<LI><A NAME="tex2html678"
HREF="node17.html#SECTION003331000000000000000">2.3.3.10 The id attribute</A>
<LI><A NAME="tex2html679"
HREF="node17.html#SECTION003331100000000000000">2.3.3.11 Mask attributes</A>
<LI><A NAME="tex2html680"
HREF="node17.html#SECTION003331200000000000000">2.3.3.12 Attributes referring to other objects</A>
<LI><A NAME="tex2html681"
HREF="node17.html#SECTION003331300000000000000">2.3.3.13 Technical details of embedded outlets</A>
<LI><A NAME="tex2html682"
HREF="node17.html#SECTION003331400000000000000">2.3.3.14 Advanced embedded outlets using key value paths</A>
</UL>
<BR>
<LI><A NAME="tex2html683"
HREF="node17.html#SECTION00334000000000000000">2.3.4 Object tags - content</A>
<UL>
<LI><A NAME="tex2html684"
HREF="node17.html#SECTION00334100000000000000">2.3.4.1 No content</A>
<LI><A NAME="tex2html685"
HREF="node17.html#SECTION00334200000000000000">2.3.4.2 String content</A>
<LI><A NAME="tex2html686"
HREF="node17.html#SECTION00334300000000000000">2.3.4.3 Tag content</A>
</UL></UL>
<!--End of Table of Child-Links-->
<HR>
<H1><A NAME="SECTION00330000000000000000">
2.3 The objects section</A>
</H1>
<P>
<H2><A NAME="SECTION00331000000000000000">
2.3.1 Relationship between tags and objects</A>
</H2>
<P>
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:
<PRE>
<button title="Quit" action="terminate:" />
</PRE>
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.
<P>
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.
<P>
In some cases, different tags produce objects of the same class; for
example the <TT><label></TT> tag creates a <TT>NSTextField</TT> object
used to display a non-editable string (such as a title or a message),
while the <TT><textField></TT> tag creates a <TT>NSTextField</TT>
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.
<P>
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
<TT>instanceOf</TT> 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,
<PRE>
<button title="Example" />
</PRE>
would create a button object (an instance of <TT>NSButton</TT>). Now
if <TT>MyButton</TT> is a subclass of <TT>NSButton</TT>, then
<PRE>
<button title="Example" instanceOf="MyButton" />
</PRE>
would do exactly the same, but allocating the object using the custom
subclass <TT>MyButton</TT> instead of the default class
<TT>NSButton</TT>. This is a very powerful and simple way of embedding
customized objects in windows.
<P>
Normally, each tag creates an object, except in special cases, which
are clearly documented.
<P>
<H2><A NAME="SECTION00332000000000000000">
2.3.2 Object tags - basic example</A>
</H2>
Consider for example the <TT><window></TT> tag, used to create a
window object. In the simplest case, the tag is just opened and
closed:
<PRE>
<?xml version="1.0"?>
<!DOCTYPE gsmarkup>
<gsmarkup>
<objects>
<window>
</window>
</objects>
</gsmarkup>
</PRE>
or more simply (using the abbreviation <TT><window /></TT>,
which in XML means <TT><window></TT> <TT></window></TT>):
<PRE>
<?xml version="1.0"?>
<!DOCTYPE gsmarkup>
<gsmarkup>
<objects>
<window />
</objects>
</gsmarkup>
</PRE>
(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.
<P>
<H2><A NAME="SECTION00333000000000000000">
2.3.3 Object tags - attributes</A>
</H2>
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
<TT><window></TT> 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 -
<PRE>
<window closable="no" />
</PRE>
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 <TT>closable="no"</TT>.
<P>
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
<PRE>
<window closable="no" resizable="no" />
</PRE>
<P>
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.
<P>
<H3><A NAME="SECTION00333100000000000000">
2.3.3.1 String attributes</A>
</H3>
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 <TT>Game Board</TT>, you
write
<PRE>
<window title="Game Board" />
</PRE>
The attribute <TT>title</TT> is set to a string, <TT>Game Board</TT>
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 <A HREF="#XML-entities">2.1</A>. 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.
<P>
<H3><A NAME="SECTION00333200000000000000">
2.3.3.2 Localizable strings attributes</A>
</H3>
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
<PRE>
<window title="Game Board" />
</PRE>
created in your <TT>main.gsmarkup</TT> file. To translate the window
into Italian, you need to add a file
<TT>Italian.lproj/main.strings</TT> to your application, containing
the following line:
<PRE>
"Game Board"="Tavolo di Gioco";
</PRE>
when the application loads the .gsmarkup file, it automatically translates
it into the appropriate language by using the appropriate
<TT>main.strings</TT> file for that language. In this example, when the
user sets Italian as his preferred language, the window will be
created with title <TT>Tavolo di Gioco</TT> rather than <TT>Game
Board</TT>. 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.
<P>
<H3><A NAME="SECTION00333300000000000000">
2.3.3.3 Boolean attributes</A>
</H3>
Boolean attributes are used to set a boolean property of the object.
The valid values of a boolean attributes are <TT>yes</TT> and
<TT>no</TT> - for example, you can write
<PRE>
<window resizable="no" />
</PRE>
Resizable is a boolean attribute, which can be <TT>YES</TT> or
<TT>NO</TT>. The example sets it to <TT>NO</TT>. For consistency
with other stuff which is always written lowercase, we prefer to use
<TT>yes</TT> and <TT>no</TT> (lowercase), but it is only a matter of taste:
<TT>Yes</TT>, <TT>YES</TT> are valid as well as attribute values, and they
mean the same thing as <TT>yes</TT>; <TT>No</TT> and <TT>NO</TT> are
valid as well to mean <TT>no</TT>. For example, it is perfectly
correct to write
<PRE>
<window resizable="NO" />
</PRE>
and it means the same as before.
<P>
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 <TT>yes</TT> or a <TT>no</TT>, then it's ignored,
which implicitly means that the default for it is used.
<P>
<H3><A NAME="SECTION00333400000000000000">
2.3.3.4 Number attributes</A>
</H3>
Number attributes are used to set a property to a number (integer or
float). For example, to create window with width <TT>200</TT> and
heigth <TT>50</TT>, you do
<PRE>
<window width="200" height="50" />
</PRE>
<P>
<H3><A NAME="SECTION00333500000000000000">
2.3.3.5 Image attributes</A>
</H3>
Image attributes are used to set a property to an image. The image is
found by invoking the method <TT>+imageNamed:</TT> of
<TT>NSImage</TT>. For example,
<PRE>
<button image="mail" title="Read Mail" imagePosition="above" />
</PRE>
would set the button image to the result of calling
<PRE>
[NSImage imageNamed: @"mail"]
</PRE>
and position it above the title.
<P>
<H3><A NAME="SECTION00333600000000000000">
2.3.3.6 Sound attributes</A>
</H3>
Sound attributes are used to set a property to a sound. The sound is
found by invoking the method <TT>+soundNamed:</TT> of
<TT>NSSound</TT>. For example,
<PRE>
<button sound="mail" title="Read Mail" />
</PRE>
would set the button sound to the result of calling
<PRE>
[NSSound soundNamed: @"mail"]
</PRE>
<P>
<H3><A NAME="SECTION00333700000000000000">
2.3.3.7 Color attributes</A>
</H3>
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.
<P>
Color attributes are evaluated in the following way by the system:
<OL>
<LI>First, the system checks if <TT>NSColor</TT> responds to the
method <TT>+xxxColor</TT>, where <TT>xxx</TT> is the value of the
attribute. If it does, the method is invoked, and the result is
used as the color. For example,
<PRE>
<colorWell width="50" height="50" color="red" />
</PRE>
will create a colorWell which displays the color returned by
<TT>[NSColor redColor]</TT>. In this way, you can access all
standard colors by name, such as <TT>black</TT>, <TT>white</TT>,
<TT>red</TT>, <TT>blue</TT>, <TT>green</TT>, <TT>yellow</TT>,
<TT>windowBackground</TT>, etc. (advanced tip: if you want to
access a non-standard one by name, you can always implement a
<TT>NSColor</TT> category, and add the method you need).
</LI>
<LI>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
<TT>#</TT> at the beginning). For example, <TT>FFFFFF</TT> is
white, <TT>000000</TT> is black, <TT>FF0000</TT> is red, and
<TT>FF000065</TT> is a semi-transparent red color.
</LI>
</OL>
<P>
<H3><A NAME="SECTION00333800000000000000">
2.3.3.8 Font attributes</A>
</H3>
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.
<P>
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.
<P>
The font for labels is normally found by calling the <TT>[NSFont
labelFontOfSize:0]</TT> method (or the <TT>[NSFont systemFontOfSize:0]</TT>
on older systems which don't have <TT>+labelFontOfSize:</TT>).
<P>
You normally only need to make the font bigger or smaller. To do it,
you can use the following font values:
<UL>
<LI><B>Tiny</B>: uses the same font, reduced to 1/3 of the original size.
</LI>
<LI><B>tiny</B>: uses the same font, reduced to 1/2 of the original size.
</LI>
<LI><B>Small</B>: uses the same font, reduced to 2/3 of the original size.
</LI>
<LI><B>small</B>: uses the same font, reduced to 4/5 of the original size.
</LI>
<LI><B>medium</B>: uses the same font, with no size change.
</LI>
<LI><B>big</B>: uses the same font, enlarged 5/4 times the original size.
</LI>
<LI><B>Big</B>: uses the same font, enlarged 3/2 times the original size.
</LI>
<LI><B>huge</B>: uses the same font, enlarged 2 times the original size.
</LI>
<LI><B>Huge</B>: uses the same font, enlarged 3 times the original size.
</LI>
</UL>
For example,
<PRE>
<label font="Big">Contents</label>
</PRE>
displays <TT>Contents</TT> using the default label font, with the
default label font size multiplied by 1.5.
<P>
You can also specify a float, which is read and interpreted as a
scaling factor. For example,
<PRE>
<label font="1.5">Contents</label>
</PRE>
is completely equivalent to setting the font to <TT>Big</TT>.
<P>
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, <TT>[NSFont userFontOfSize: 0]</TT> returns the font to be
used for user editable text, in the default size. To choose that type
of font, you just specify <TT>user</TT> as the font value, as in
<PRE>
<label font="user">Testing fonts</label>
</PRE>
this draws the label using the font <TT>[NSFont userFontOfSize:
0]</TT>. In general, if the value of the font attribute is xxx, the
NSFont method <TT>+xxxFontOfSize:</TT> (if it exists) is used to get
the font. The types of fonts available on gsmarkup at the moment are
<TT>label</TT>, <TT>boldSystem</TT>, <TT>user</TT>,
<TT>userFixedPitch</TT>, <TT>menu</TT>, <TT>message</TT>,
<TT>palette</TT>, <TT>system</TT>, <TT>titleBar</TT>,
<TT>toolTips</TT>. 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.
<P>
Anyway, if for example you want to display a button containing a title
with a bigger font, you may need them.
<P>
You can use one of those standard fonts in any size, for example
<PRE>
<label font="user big">Testing fonts</label>
</PRE>
is valid, and uses the same font returned by <TT>[NSFont
userFontOfSize: 0]</TT> but enlarged by a factor of 1.20.
<P>
<H3><A NAME="SECTION00333900000000000000">
2.3.3.9 The instanceOf attribute</A>
</H3>
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
<TT>NPWindow</TT>, which is a subclass of <TT>NSWindow</TT> with some
special behaviour added to it, then you can create a window of you
subclass by doing
<PRE>
<window instanceOf="NPWindow" />
</PRE>
This will create a window using the standard procedure used for
windows, except it will lookup the class named <TT>NPWindow</TT> at
run time, and allocate the object using that class instead of
<TT>NSWindow</TT> class. Please note that all the standard attributes
of a window object are still recognized:
<PRE>
<window instanceOf="NPWindow" width="100" height="100" resizable="no" />
</PRE>
the attributes will be read, and applied to the window exactly as if
the window was a standard <TT>NSWindow</TT> object. Because
<TT>NPWindow</TT> is a subclass of <TT>NSWindow</TT> (and Renaissance
will check it at run time), all the attributes and methods which are
valid for a <TT>NSWindow</TT> are expect to be available for an
<TT>NPWindow</TT> object too, so this is expected to work.
<P>
In detail, when you specify a <TT>instanceOf="XXX"</TT> attribute for a
view or window tag, Renaissance at run time looks up <TT>XXX</TT> 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 <TT>instanceOf</TT> attribute had been specified). If it is, then
Renaissance allocates the new object using class <TT>XXX</TT> instead
of the default class. It is important to check that the class
<TT>XXX</TT> 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.
<P>
The reference documentation should mark clearly tags which recognize
the <TT>instanceOf</TT> attribute, and tags which ignore it.
<P>
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 <TT><instance></TT>
tag, which allows you to allocate an instance of any class (still
specified with the <TT>instanceOf</TT> attribute). This is mostly used to
create controller objects. Because of the wide generality of the
objects allocated by the <TT><instance></TT> 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 <TT><instance></TT>
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 <TT>instanceOf</TT> attribute,
because then Renaissance will know what type of object it is and will
treat it accordingly, including recognizing all the appropriate
attributes.
<P>
<H3><A NAME="SECTION003331000000000000000">
2.3.3.10 The id attribute</A>
</H3>
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 <TT>id</TT>, and its value is a string
which is the internal name to give to the object<A NAME="tex2html2"
HREF="footnode.html#foot1606"><SUP>2.1</SUP></A>. For example,
<PRE>
<window id="board" />
</PRE>
creates a window, and tags it with the id <TT>board</TT>. 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.
<P>
<H3><A NAME="SECTION003331100000000000000">
2.3.3.11 Mask attributes</A>
</H3>
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 <TT>|</TT> character
can be used to specify multiple values at the same time (the
<TT>|</TT> character is used because internally a bitfield OR will be
used to calculate the final value). For example, a <TT><button></TT>
tag has a <TT>sendActionOn</TT> attribute (inherited from
<TT><control></TT>) which can be used to control when the button
specific action is triggered. The <TT>sendActionOn</TT> attribute can
take a number of values, such as <TT>leftMouseUp</TT> or
<TT>leftMouseDown</TT> (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 <TT>|</TT> character as in the
following example:
<PRE>
<button title="Test" action="dummyAction:"
sendActionOn="leftMouseDown | leftMouseUp" />
</PRE>
Note that spaces around the <TT>|</TT> character are ignored, so you
can use them for readability if you want.
<P>
<H3><A NAME="SECTION003331200000000000000">
2.3.3.12 Attributes referring to other objects</A>
</H3>
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 (<TT>#</TT>). For example, if you create a window and give
it an id of <TT>board</TT>, as in
<PRE>
<window id="board" />
</PRE>
then you can refer to that window object by using the syntax
<TT>#board</TT>. <TT>#board</TT> simply means <I>the object whose id name
is</I> <TT>board</TT>.
<P>
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.
<P>
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:
<PRE>
<window delegate="#myDelegate">
</PRE>
When this file is loaded in a running application, the attribute
<TT>delegate</TT> is treated specially. It is treated specially because
its value begins with a hash (<TT>#</TT>), which means it is a
reference to another object (in the file or even outside the file).
When the file is loaded, the method <TT>setDelegate:</TT> of the
window object will automatically be called, with argument the object
which has id name <TT>myDelegate</TT>. This object can be
<OL>
<LI>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 <TT>myDelegate</TT>, and then make it the
window controller.
<P>
</LI>
<LI>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
<TT>NSOwner</TT>. For example, to make the file owner the delegate
of your window, you would do
<PRE>
<window delegate="#NSOwner">
</PRE>
Normally, all connections between the objects loaded in the file and
the existing application objects are done through the file owner.
<P>
</LI>
<LI>NSApp (the shared application instance), which is automatically
made available by Renaissance with the id name <TT>NSApp</TT>. For
example, to create a popup button with an item which terminates the
application, you would do
<PRE>
<popUpButton>
<popUpButtonItem title="terminate the app" action="terminate:"
target="#NSApp" />
</popUpButton>
</PRE>
<P>
</LI>
<LI>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.
<P>
</LI>
</OL>
<P>
Here is another example -
<PRE>
<window>
<hbox>
<button title="yes" id="yes" nextKeyView="#no" />
<button title="no" id="no" nextKeyView="#yes" />
</hbox>
</window>
</PRE>
in this example, a window with two buttons is created. The first
button has title <TT>yes</TT>, the second one has title <TT>no</TT>.
The first button is given id <TT>yes</TT>, and the second one is given
id <TT>no</TT>. 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.
<P>
<H3><A NAME="SECTION003331300000000000000">
2.3.3.13 Technical details of embedded outlets</A>
</H3>
You can skip this section at a first reading. It is explaining the
technical details of attributes referring to objects.
<P>
Technically, whenever an attribute has a value which begins with a
single hash (<TT>#</TT>), 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
<PRE>
<window delegate="#myDelegate">
</PRE>
you are effectively establishing that the value of the key
<TT>delegate</TT> of the created window object should be set to the
object whose id is <TT>myDelegate</TT>.
<P>
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.
<P>
<H3><A NAME="SECTION003331400000000000000">
2.3.3.14 Advanced embedded outlets using key value paths</A>
</H3>
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.
<P>
Renaissance allows the advanced syntax
<PRE>
<window delegate="#NSOwner.windowDelegate" />
</PRE>
to mean extracting the value for the key <TT>windowDelegate</TT> of
the <TT>#NSOwner</TT> object, and setting it as the <TT>delegate</TT>
of the window. ``Extracting the value for the key'' will use
key-value coding to get it. In practice, if the <TT>#NSOwner</TT>
responds to one of the methods <TT>getWindowDelegate</TT>,
<TT>windowDelegate</TT>, <TT>_getWindowDelegate</TT>,
<TT>_windowDelegate</TT>, or has an instace variable called
<TT>_windowDelegate</TT> or <TT>windowDelegate</TT>, to get the value
for the key, the method will be called, or the instance variable
will be read<A NAME="tex2html3"
HREF="footnode.html#foot1607"><SUP>2.2</SUP></A>.
<P>
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 <TT>#NSOwner</TT>. It's an additional layer of
flexibility.
<P>
Renaissance also allows multiple key-value coding in sequence, for example
<PRE>
<window delegate="#NSOwner.controller.preferenceWindowDelegate" />
</PRE>
This will start with <TT>#NSOwner</TT>, use key-value coding to
extract the value for key <TT>controller</TT> of that object, then use
key-value coding to extract the value for key
<TT>preferenceWindowDelegate</TT> of the resulting object, and finally
set the window's <TT>delegate</TT> to the result.
<P>
To support both simple and multiple key-value coding, Renaissance uses
<TT>-valueForKeyPath:</TT>. For example, when Renaissance processes the
code
<PRE>
<window delegate="#NSOwner.windowDelegate" />
</PRE>
it assigns to the window's <TT>delegate</TT> the result of calling
<PRE>
[#NSOwner valueForKeyPath: @"windowDelegate"]
</PRE>
which, in this case, because there are no dots in the keypath, does
the same as <TT>[#NSOwner valueForKey: @"windowDelegate"]</TT>.
<P>
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
<TT>'.'</TT>), 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, <TT>#xxx.yyy</TT> is to be interpreted
as meaning ``the result of <TT>[#xxx valueForKeyPath: @"yyy"]</TT>,
where <TT>#xxx</TT> is the object with id <TT>xxx</TT>.''
<P>
For example, the expression <TT>#NSApp.mainMenu</TT> means the result
of calling
<PRE>
[NSApp valueForKeyPath: @"mainMenu"]
</PRE>
which will return the application main menu.
<TT>#NSApp.delegate.description</TT> means the result of calling
<PRE>
[NSApp valueForKeyPath: @"delegate.description"]
</PRE>
which will invoke the <TT>description</TT> method of the delegate of
<TT>NSApp</TT>.
<P>
For more information, please refer to the documentation of key-value
coding, for example the documentation for the
<TT>-valueForKeyPath:</TT> and <TT>-valueForKey:</TT> methods.
<P>
<H2><A NAME="SECTION00334000000000000000">
2.3.4 Object tags - content</A>
</H2>
Everything which is found between an open tag and the corresponding
close tag is called the content of the tag. For example, in
<PRE>
<label>Please reboot your system</label>
</PRE>
the open tag is <TT><label></TT>, the close tag is <TT></label></TT>,
and the string inside is the content of the tag. Often, the content
of a tag can include other tags. For example,
<PRE>
<window>
<button title="Click me to quit" action="terminate:" />
</window>
</PRE>
in this case, the content of the window tag is the button tag.
<P>
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 <I>inside</I> the object. This
concept is of course human and not completely well defined, anyway the
idea is that, for example, the attributes of a <TT><window></TT> tag
(such as <TT>closable="no"</TT>, <TT>width="200"</TT>,
<TT>title="Main Window"</TT>) change the general properties of the
window, while the tags inside the <TT>window</TT> tag represent
objects which should be displayed inside the window.
<P>
Now we examine typical examples of tags and the type of content they
can hold.
<P>
<H3><A NAME="SECTION00334100000000000000">
2.3.4.1 No content</A>
</H3>
Some gui objects do not contain anything. For example, a button or a
colorWell do not contain anything and never have a content.
<P>
<H3><A NAME="SECTION00334200000000000000">
2.3.4.2 String content</A>
</H3>
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,
<PRE>
<label>Missing image</label>
</PRE>
displays a label with the string <TT>Missing image</TT>, while
<PRE>
<textField>user@host</textField>
</PRE>
displays an editable textField which contains the string
<TT>user@host</TT> 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 ?).
<P>
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.
<P>
<H3><A NAME="SECTION00334300000000000000">
2.3.4.3 Tag content</A>
</H3>
Other gui objects have content which is composed of other objects.
Typical examples include:
<UL>
<LI>Menus. A menu contains menu items, or other menus. Here is an
example:
<PRE>
<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>
</PRE>
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.
</LI>
<LI>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.
</LI>
<LI>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,
<PRE>
<hbox>
<button title="Save" />
<button title="Discard" />
<button title="Cancel" />
</hbox>
</PRE>
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,
<PRE>
<box title="Mail Preferences">
<vbox>
<!-- missing - vbox content -->
</vbox>
</box>
</PRE>
displays a border box with title <TT>Mail Preferences</TT>, and
inside it a vertical (invisible) box containing any sort of objects
(not shown in the example).
</LI>
<LI>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.
</LI>
<LI>Tables. A table contains various columns.
</LI>
</UL>
<P>
<HR><B> Next: <A NAME="tex2html665"
HREF="node18.html">2.4 The connectors section</A> </B>
<B>Up: <A NAME="tex2html661"
HREF="node14.html">2. The GNUstep Markup</A> </B>
<B> Previous: <A NAME="tex2html655"
HREF="node16.html">2.2 General overview of</A> </B>
<!--End of Navigation Panel-->
<ADDRESS>
2008-03-19
</ADDRESS>
</BODY>
</HTML>
Server : Apache/2.4.41 (Ubuntu)