Subsections

- 2.4.1 How objects are given ids
- 2.4.2 Connector tags
- 2.4.3 Outlet connectors
- 2.4.4 Details of how outlet connections are established

# 2.4 The connectors section

The connectors section is used to establish connections between objects.

## 2.4.1 How objects are given ids

Objects are identified by their id. There are various ways in which an object can be given an id:

- Objects created by the file are given an id if the tags which creates them contains the id attribute. For example,

      <textField id="pop3" width="200" />

  the textField object is given the id pop3.
- 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 id NSOwner.
- 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 id to any existing object in the application (and so making it available for establishing connections to/from it).
- Some predefined objects have a predefined id given to them automatically by the system. For example, the main NSApplication instance is automatically available with id NSApp.

Any object which has been given an id can be the source or the target of a connection set up in the connectors section.

## 2.4.2 Connector tags

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

## 2.4.3 Outlet connectors

An outlet connector is created with the <outlet> tag. For example,

    <connectors>
     <outlet source="#NSOwner" target="#Controller" key="controller" />
    </connectors>

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

    [#NSOwner setController: #Controller];

(where #NSOwner is the object which has id NSOwner and #Controller is the object which has id Controller).

As an advanced extension, if the source or target of an outlet connector contains a dot (that is, the '.' 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 source or target. For example, when the outlet

    <connectors>
     <outlet source="#NSOwner" target="#Controller.name" key="controllerName" />
    </connectors>

is established, it's result will likely to be to invoke

    [#NSOwner setControllerName: [#Controller name]];

assuming that #Controller responds to a method name (if it doesn't, key-value coding – as explained in the next section – is used to retrieve the value for key name of the object #Controller).

## 2.4.4 Details of how outlet connections are established

When an outlet connection is established, the following things happen:

1. 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, #NSController.delegate.name would be broken into #NSController and delegate.name. The first part of the string is looked up in the name table, producing an object. Then, key value coding is used to retrieve the value for the key path given by the second string on this object. In practice, if the first part of the string is xxx, and the second part is yyy, the source or target is set to the result of the following operations:

       [[nameTable objectForKey: xxx] valueForKeyPath: yyy];

   (please check the documentation for valueForKeyPath: to learn more about this operation).
2. the outlet connector calls

       [source takeValue: target forKey: key];

   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 takeValue:forKey: method.
   1. if the key is xxx, the system searches for the setXxx: method in the source (please note that the first letter of xxx is made uppercase). If that method exists, the following code is executed:

          [source setXxx: target];

      and the outlet connection can be considered established.
   2. if the method wasn't found, the _setXxx: method is searched, and if it exists is used.
   3. if this fails, the system searches an instance variable with name _xxx in the source, and if it finds it, it ASSIGNs to it the target2.3. Assigning includes releasing the previous value, and retaining the new one.
   4. if the _xxx instance variable is not found, the system searches for an instance variable called xxx, and tries to set that.
   5. if even this fails, the system calls the method -handleTakeValue:forUnboundKey: of the source, which – unless overridden by the source class – raises an exception.

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.