Subsections

- 2.8.1 The control tag
  - 2.8.1.1 Description
  - 2.8.1.2 Attributes
  - 2.8.1.3 Examples
- 2.8.2 The outlet tag
  - 2.8.2.1 Description
  - 2.8.2.2 Attributes
  - 2.8.2.3 Examples

# 2.8 Connector tag reference

## 2.8.1 The control tag

### 2.8.1.1 Description

A <control> tag represents a control connector (a connector used to connect controls) and is converted into an instance of GSMarkupControlConnector. When the connection is established, the following code is executed

      [source setAction: action];
      [source setTarget: target];

where source is the source object, target is the target object, and action is obtained by converting the action attribute into a selector.

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

### 2.8.1.2 Attributes

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

### 2.8.1.3 Examples

Control connectors are used very rarely. Here is how a control connector would look:

    <connectors>
      <control source="#myButton" target="#myController" action="buttonPressed:" />
    </connectors>

this is rarely used, because usually you can more simply do

    <objects>
      ...
        <button action="buttonPressed:" target="#myController" ... />
      ...
    </objects>

this is equivalent, but it is preferred because it is much more natural: you set the action and the target of the button in the same place where you create the button, rather than in the separate connectors section. The system automatically writes all action connectors in this way when it writes gsmarkup files – if it can: if the source is not created in the gsmarkup file, this can't be done, and you would need to use a control connector explicitly.

## 2.8.2 The outlet tag

### 2.8.2.1 Description

An <outlet> tag represents an outlet connector (a generic connector), and is converted into an instance of GSMarkupOutletConnector. When the connection is established, the following code is executed

      [source takeValue: target  forKey: key];

where source is the source object, target is the target object, and label is the key. Often an outlet can be embedded directly into the objects section, which results in simpler, better code.

### 2.8.2.2 Attributes

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

### 2.8.2.3 Examples

Outlet connectors are not used often, but they are needed sometimes. Here is how an outlet connector would look:

    <connectors>
      <outlet source="#myController" target="#myButton" key="button" />
    </connectors>

this (in which the source is an object already existing in the application) is the only form of outlet connector which is normally used, because if the object is created in the gsmarkup file itself, the outlet can be embedded in the object creation by using the syntax

    <objects>
      ...
        <textView delegate="#myController" ... />
      ...
    </objects>

which is perfectly equivalent to:

    <objects>
      ...
        <textView id="myTextView" ... />
      ...
    </objects>

    <connectors>
      <outlet source="#myTextView" target="#myController" key="delegate" />
    </connectors>

this second explicit form is much more long, artificial and cumbersome. The system automatically writes all outlet connectors inside the objects section when it writes gsmarkup files – if it can. In some cases (when the source is created outside the gsmarkup file) this can't be done; these are the cases in which the connector is created manually inside the connectors section.