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/thread-self/root/usr/share/doc/renaissance-doc/html/manual/
Upload File :
Current File : //proc/thread-self/root/usr/share/doc/renaissance-doc/html/manual/node18.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.4 The connectors section</TITLE>
<META NAME="description" CONTENT="2.4 The connectors 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="node19.html">
<LINK REL="previous" HREF="node17.html">
<LINK REL="up" HREF="node14.html">
<LINK REL="next" HREF="node19.html">
</HEAD>
<BODY BGCOLOR="#FFFFFF" text="#000000" link="#0000FF" vlink="#4444FF" alink="#3388FF">
<B> Next: <A NAME="tex2html698"
HREF="node19.html">2.5 The GSMarkup NSBundle</A> </B>
<B>Up: <A NAME="tex2html694"
HREF="node14.html">2. The GNUstep Markup</A> </B>
<B> Previous: <A NAME="tex2html688"
HREF="node17.html">2.3 The objects section</A> </B>
<BR> <P>
<!--End of Navigation Panel-->
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
<UL>
<LI><A NAME="tex2html699"
HREF="node18.html#SECTION00341000000000000000">2.4.1 How objects are given ids</A>
<LI><A NAME="tex2html700"
HREF="node18.html#SECTION00342000000000000000">2.4.2 Connector tags</A>
<LI><A NAME="tex2html701"
HREF="node18.html#SECTION00343000000000000000">2.4.3 Outlet connectors</A>
<LI><A NAME="tex2html702"
HREF="node18.html#SECTION00344000000000000000">2.4.4 Details of how outlet connections are established</A>
</UL>
<!--End of Table of Child-Links-->
<HR>
<H1><A NAME="SECTION00340000000000000000">
2.4 The connectors section</A>
</H1>
<P>
The connectors section is used to establish connections between
objects.
<P>
<H2><A NAME="SECTION00341000000000000000">
2.4.1 How objects are given ids</A>
</H2>
Objects are identified by their <TT>id</TT>. There are various ways
in which an object can be given an <TT>id</TT>:
<UL>
<LI>Objects created by the file are given an id if the tags which
creates them contains the <TT>id</TT> attribute. For example,
<PRE>
<textField id="pop3" width="200" />
</PRE>
the textField object is given the <TT>id</TT> <TT>pop3</TT>.
</LI>
<LI>The file owner - an object which is specified by the code
loading the GSMarkup file, and normally is the main way of
connecting objects in the GSMarkup file with the rest of the
application - is automatically given the <TT>id</TT>
<TT>NSOwner</TT>.
</LI>
<LI>Additional objects which the code loading the GSMarkup file
wants to make available to the GSMarkup file. By specifying an
external name table when loading the GSMarkup file, the code can
give an <TT>id</TT> to any existing object in the application (and
so making it available for establishing connections to/from it).
</LI>
<LI>Some predefined objects have a predefined <TT>id</TT> given to
them automatically by the system. For example, the main
<TT>NSApplication</TT> instance is automatically available with
<TT>id</TT> <TT>NSApp</TT>.
</LI>
</UL>
Any object which has been given an id can be the source or the target
of a connection set up in the connectors section.
<P>
<H2><A NAME="SECTION00342000000000000000">
2.4.2 Connector tags</A>
</H2>
Inside the connectors section tags are interpreted in a different way
than inside the objects section. Inside the connectors sections, tags
are interpreted as being connectors tags rather than object tags.
Connector tags might vary, but normally you only need to know about
outlet connectors, so we only describe outlet connectors here.
<P>
<H2><A NAME="SECTION00343000000000000000">
2.4.3 Outlet connectors</A>
</H2>
An outlet connector is created with the <TT><outlet></TT> tag. For
example,
<PRE>
<connectors>
<outlet source="#NSOwner" target="#Controller" key="controller" />
</connectors>
</PRE>
An outlet has a source (an object specified by id), a target (another
object again specified by id), and a key (a string). The outlet
describes a connection which should be established between the source
and target object; the key represents a key in the source object. By
using key-value coding, when the outlet connection is established, the
value for the key in the source is set to the target (I'll try to
explain this better in a minute). In the example, when the outlet is
established, it's result will likely to be to invoke
<PRE>
[#NSOwner setController: #Controller];
</PRE>
(where <TT>#NSOwner</TT> is the object which has id <TT>NSOwner</TT>
and <TT>#Controller</TT> is the object which has id
<TT>Controller</TT>).
<P>
As an advanced extension, if the <TT>source</TT> or <TT>target</TT> of
an outlet connector contains a dot (that is, the <TT>'.'</TT>
character), then the part of the string before the dot is interpreted
as an object specified by id, and the part of the string after the dot
is interpreted as a key value path to use on the object to get the
actual <TT>source</TT> or <TT>target</TT>. For example, when the outlet
<PRE>
<connectors>
<outlet source="#NSOwner" target="#Controller.name" key="controllerName" />
</connectors>
</PRE>
is established, it's result will likely to be to invoke
<PRE>
[#NSOwner setControllerName: [#Controller name]];
</PRE>
assuming that <TT>#Controller</TT> responds to a method
<TT>name</TT> (if it doesn't, key-value coding - as explained
in the next section - is used to retrieve the value for key
<TT>name</TT> of the object <TT>#Controller</TT>).
<P>
<H2><A NAME="SECTION00344000000000000000">
2.4.4 Details of how outlet connections are established</A>
</H2>
When an outlet connection is established, the following things happen:
<OL>
<LI>the outlet connector determines the source and target objects
from their ids (by performing a lookup in the name tables which
store the mappings from ids to objects). If the ids do not contains
dots, a simple lookup in the name table is done. If the source or
target strings contain a dot, then the advanced key value coding
support is used: the string is broken in two parts: before and after
the first dot in the string. For example,
<TT>#NSController.delegate.name</TT> would be broken into
<TT>#NSController</TT> and <TT>delegate.name</TT>. The first part
of the string is looked up in the name table, producing an object.
Then, key value coding is used to retrieve the value for the key
path given by the second string on this object. In practice, if the
first part of the string is <TT>xxx</TT>, and the second part is
<TT>yyy</TT>, the <TT>source</TT> or <TT>target</TT> is set to the
result of the following operations:
<PRE>
[[nameTable objectForKey: xxx] valueForKeyPath: yyy];
</PRE>
(please check the documentation for <TT>valueForKeyPath:</TT> to
learn more about this operation).
</LI>
<LI>the outlet connector calls
<PRE>
[source takeValue: target forKey: key];
</PRE>
to set target as the value for the key key in the source. If you
don't know what this really mean, we describe here briefly what this
does; for more information please read the documentation of the
<TT>takeValue:forKey:</TT> method.
<OL>
<LI>if the key is xxx, the system searches for the <TT>setXxx:</TT>
method in the source (please note that the first letter of xxx is
made uppercase). If that method exists, the following code is
executed:
<PRE>
[source setXxx: target];
</PRE>
and the outlet connection can be considered established.
</LI>
<LI>if the method wasn't found, the <TT>_setXxx:</TT> method is
searched, and if it exists is used.
</LI>
<LI>if this fails, the system searches an instance variable with
name <TT>_xxx</TT> in the source, and if it finds it, it
<TT>ASSIGN</TT>s to it the target<A NAME="tex2html4"
HREF="footnode.html#foot1608"><SUP>2.3</SUP></A>. Assigning includes
releasing the previous value, and retaining the new one.
</LI>
<LI>if the <TT>_xxx</TT> instance variable is not found, the system
searches for an instance variable called <TT>xxx</TT>, and tries to
set that.
</LI>
<LI>if even this fails, the system calls the method
<TT>-handleTakeValue:forUnboundKey:</TT> of the source, which -
unless overridden by the source class - raises an exception.
</LI>
</OL>
</LI>
</OL>
As you can see, you can automatically set up instance variables of
objects to point to other objects when you load a gsmarkup file. This is
very handy to establish connections between objects.
<P>
<HR><B> Next: <A NAME="tex2html698"
HREF="node19.html">2.5 The GSMarkup NSBundle</A> </B>
<B>Up: <A NAME="tex2html694"
HREF="node14.html">2. The GNUstep Markup</A> </B>
<B> Previous: <A NAME="tex2html688"
HREF="node17.html">2.3 The objects section</A> </B>
<!--End of Navigation Panel-->
<ADDRESS>
2008-03-19
</ADDRESS>
</BODY>
</HTML>
Server : Apache/2.4.41 (Ubuntu)