Subsections

- 2.7.1 The button tag
  - 2.7.1.1 Description
  - 2.7.1.2 Attributes
  - 2.7.1.3 Possible object attributes
  - 2.7.1.4 Content
  - 2.7.1.5 Examples
- 2.7.2 The colorWell tag
  - 2.7.2.1 Description
  - 2.7.2.2 Attributes
  - 2.7.2.3 Possible object attributes
  - 2.7.2.4 Content
  - 2.7.2.5 Examples
- 2.7.3 The control tag
  - 2.7.3.1 Description
  - 2.7.3.2 Attributes
  - 2.7.3.3 Possible object attributes
  - 2.7.3.4 Content
  - 2.7.3.5 Examples
- 2.7.4 The hbox tag
  - 2.7.4.1 Description
  - 2.7.4.2 Attributes
  - 2.7.4.3 Possible object attributes
  - 2.7.4.4 Content
  - 2.7.4.5 Examples
- 2.7.5 The hspace tag
  - 2.7.5.1 Description
  - 2.7.5.2 Attributes
  - 2.7.5.3 Possible object attributes
  - 2.7.5.4 Content
  - 2.7.5.5 Examples
- 2.7.6 The image tag
  - 2.7.6.1 Description
  - 2.7.6.2 Attributes
  - 2.7.6.3 Possible object attributes
  - 2.7.6.4 Content
  - 2.7.6.5 Examples
- 2.7.7 The instance tag
  - 2.7.7.1 Description
  - 2.7.7.2 Attributes
  - 2.7.7.3 Possible object attributes
  - 2.7.7.4 Content
  - 2.7.7.5 Examples
- 2.7.8 The label tag
  - 2.7.8.1 Description
  - 2.7.8.2 Attributes
  - 2.7.8.3 Possible object attributes
  - 2.7.8.4 Content
  - 2.7.8.5 Examples
- 2.7.9 The menu tag
  - 2.7.9.1 Description
  - 2.7.9.2 Attributes
  - 2.7.9.3 Possible object attributes
  - 2.7.9.4 Content
  - 2.7.9.5 Examples
  - 2.7.9.6 Portability
- 2.7.10 The menuItem tag
  - 2.7.10.1 Description
  - 2.7.10.2 Attributes
  - 2.7.10.3 Possible object attributes
  - 2.7.10.4 Content
  - 2.7.10.5 Examples
- 2.7.11 The menuSeparator tag
  - 2.7.11.1 Description
  - 2.7.11.2 Attributes
  - 2.7.11.3 Possible object attributes
  - 2.7.11.4 Content
  - 2.7.11.5 Examples
- 2.7.12 The panel tag
  - 2.7.12.1 Description
  - 2.7.12.2 Attributes
  - 2.7.12.3 Possible object attributes
  - 2.7.12.4 Content
  - 2.7.12.5 Examples
- 2.7.13 The secureTextField tag
  - 2.7.13.1 Description
  - 2.7.13.2 Attributes
  - 2.7.13.3 Possible object attributes
  - 2.7.13.4 Content
  - 2.7.13.5 Examples
- 2.7.14 The textField tag
  - 2.7.14.1 Description
  - 2.7.14.2 Attributes
  - 2.7.14.3 Possible object attributes
  - 2.7.14.4 Content
  - 2.7.14.5 Examples
- 2.7.15 The vbox tag
  - 2.7.15.1 Description
  - 2.7.15.2 Attributes
  - 2.7.15.3 Possible object attributes
  - 2.7.15.4 Content
  - 2.7.15.5 Examples
- 2.7.16 The view tag
  - 2.7.16.1 Description
  - 2.7.16.2 Attributes
  - 2.7.16.3 Possible object attributes
  - 2.7.16.4 Content
  - 2.7.16.5 Examples
- 2.7.17 The vspace tag
  - 2.7.17.1 Description
  - 2.7.17.2 Attributes
  - 2.7.17.3 Possible object attributes
  - 2.7.17.4 Content
  - 2.7.17.5 Examples
- 2.7.18 The window tag
  - 2.7.18.1 Description
  - 2.7.18.2 Attributes
  - 2.7.18.3 Possible object attributes
  - 2.7.18.4 Content
  - 2.7.18.5 Examples

# 2.7 Object tag reference

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

- The description of the tag, telling you what the tag is.
- 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 id attribute is always available for all objects so it's not listed here.
- 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.
- A description of what content the tag accepts.
- One or more example gsmarkup code using the tag.
- In a few specific cases, a discussion of portability issues.

## 2.7.1 The button tag

### 2.7.1.1 Description

A <button> tag represents a button, and normally generates an instance of NSButton. The most common attributes to set in a button are the title (the text displayed in the button), the target and action (controlling what happens when the button is clicked). It's also possible to set the image attribute to set the image displayed in the button, and to create different types of buttons by using the type attribute. Some of the button types will be highlighted by the system; some others will display the alternateText and/or alternateImage when highlighted.

### 2.7.1.2 Attributes

The <button> tag inherits all attributes from the generic <control> and <view> tags; in addition, it has the following ones:

- alternateImage: The alternate image of the button, if any. This is an image attribute.
- alternateTitle: The alternate text of the button, if any. This is an optional localized string attribute.
- image: The image of the button (an image).
- imagePosition: The position of the button image (if needed). This attribute is a string, and is optional. It can be set to above, below, left, right, overlaps and imageOnly.
- keyEquivalent: The keyEquivalent of the button (normally a single character).
- keyEquivalentModifierMask: 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 noKey (the default), commandKey, controlKey or alternateKey. In addition to that, you can specify combinations of these values by using the | character; for example commandKey||controlKey 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).
- sound: 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 [NSSound +soundNamed:], where the value of this attribute is used as the argument.
- title: The text of the button, if any. This is an optional localized string attribute.
- type: The type of button. This is a string, and can be set to momentaryPushIn (a standard button that is highlighted when you click, and unhighlighted when the mouse goes up), momentaryChange (the same as momentaryPushIn, but the highlighting is done by displayed the alternate text and image), pushOnPushOff (a button that gets pushed on when you click, and gets pushed back off when you click again), toggle (the same as pushOnPushOff, but the 'pushed on' state is shown by displaying the alternate text and image) and switch (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 momentaryPushIn.

The <button> tag supports the instanceOf attribute.

### 2.7.1.3 Possible object attributes

The <button> tag inherits all object attributes from the generic <control> and <view> tags, but adds no specific of its own.

### 2.7.1.4 Content

A <button> tag has no content.

### 2.7.1.5 Examples

The most common type of <button> tag triggers an action on a target:

    <button title="Click this button to quit" action="terminate:" target="NSApp" />

In preference panels, it's also common to use switch buttons:

    <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>

## 2.7.2 The colorWell tag

### 2.7.2.1 Description

A <colorWell> tag represents a colorWell (a small rectangular control used to display or choose a color), and normally generates an instance of NSColorWell. The most common attribute to set in a colorWell is the color (the color displayed/edited in the color well).

### 2.7.2.2 Attributes

The <colorWell> tag inherits all attributes from the generic <control> and <view> tags; in addition, it has the following ones:

- bordered: A boolean attribute; if set to yes, the color well is bordered (the default), else, it's not.
- color: A color attribute – the color displayed in the color well.

The <colorWell> tag supports the instanceOf attribute.

### 2.7.2.3 Possible object attributes

The <colorWell> tag inherits all object attributes from the generic <control> and <view> tags, but adds no specific of its own.

### 2.7.2.4 Content

A <colorWell> tag has no content.

### 2.7.2.5 Examples

The most common type of <colorWell> tag triggers an action on a target, and is mostly used in preference panels:

    <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>

## 2.7.3 The control tag

### 2.7.3.1 Description

A <control> tag represents a control, and normally generates an instance of NSControl. Instances of NSControl are not particularly useful as they are (NSControl instances represent rectangular regions in a window which display some data and react to user events), which is why <control> tags are normally only used with an instanceOf attribute to create custom control objects.

The attributes of <control> tags are inherited by all tags whose instances inherit from NSControl – 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.

### 2.7.3.2 Attributes

The <control> tag inherits all attributes from the more generic <view> tag; in addition, it has the following attributes:

- action: 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 NULL action is used. Please note that the string should include the `:' at the end; for example, action="terminate:".
- continuous: This attribute is a boolean; it is optional; if set to yes, the control will send its action continuously; if set to no, it does not.
- enabled: This attribute is a boolean; it is optional; if set to yes it enables the control, if set to no it disables it.
- font: 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.
- sendActionOn: This attribute is a string, and is optional. It can be set to leftMouseUp, leftMouseDown, leftMouseDragged or periodic. In addition to that, you can specify combinations of these values by using the | character; for example leftMouseDown||leftMouseUp 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).
- tag: 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.
- textAlignment: The alignment of the text (if needed). This attribute is a string, and is optional. It can be set to left, center, or right. If you specify a size for the <control> 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.

The <control> tag supports the instanceOf attribute.

### 2.7.3.3 Possible object attributes

The <control> tag inherits all object attributes from the generic <view>, and adds the following ones:

- target: The target of the control.

### 2.7.3.4 Content

None.

### 2.7.3.5 Examples

In practice, <control> tags are rarely used. The only good reason to use a <control> tag in practice is to create an instance of a custom subclass of NSControl:

    <control instanceOf="MapView" action="clickOnMap:" target="#NSOwner"
             width="400" height="400" />

While <control> tags are rarely used, many common tags inherit attributes from <control>; for example, buttons inherit the <control> attributes, in particular the action, target and enabled attributes used to control how the control reacts to user actions (very common for buttons), but also the font and textAlignment attributes that control how the text is displayed (very common for labels and textfields).

## 2.7.4 The hbox tag

### 2.7.4.1 Description

A <hbox> tag represents an invisible horizontal autolayout container that can hold other views, and normally generates an instance of GSAutoLayoutHBox.

There are two types of boxes:

- standard: 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 <hbox> takes up all the space allocated to it. If no views are marked as expand or wexpand, then the <hbox> itself won't be expanding.
- proportional: 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 proportion attribute set, which will cause it to cover a different number of layout units. By default, all views have proportion=1.

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.

### 2.7.4.2 Attributes

The <hbox> tag inherits all attributes from the generic <view> tag; in addition, it has the following ones:

- type: 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.

The <hbox> tag supports the instanceOf attribute.

### 2.7.4.3 Possible object attributes

The <hbox> tag inherits all object attributes from the generic <view> tag but has none of its own.

### 2.7.4.4 Content

A <hbox> tag has its subviews as its content. They are created in the order they are listed, and displayed from left to right.

### 2.7.4.5 Examples

<hbox> 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:

    <hbox>
      <button title="Miniaturize" action="performMiniaturize:" />
      <button title="Close" action="performClose:" />
    </hbox>

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.

Here is the same example where the buttons are automatically sized to have exactly the same size:

    <hbox type="proportional">
      <button title="Miniaturize" action="performMiniaturize:" />
      <button title="Close" action="performClose:" />
    </hbox>

It is quite possible and common to nest <hbox> and <vbox> tags to create more complex layouts, as in the following example where a textfield is on top of a row of buttons:

    <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>

## 2.7.5 The hspace tag

### 2.7.5.1 Description

A <hspace> tag represents invisible horizontal weakly-expanding space that can be put into autolayout containers such as <hbox> objects for alignment purporses. It normally generates an instance of GSAutoLayoutHSpace.

An <hspace> 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.

Please note in vertical boxes (<vbox>) you should use vertical spaces (<vspace>); it does not really make sense to put a <hspace> inside a <vbox> since the <hspace> only expand horizontally, not vertically.

### 2.7.5.2 Attributes

The <hspace> tag inherits all attributes from the generic <view> tag but adds no new attributes of its own.

The <hspace> tag supports the instanceOf attribute.

### 2.7.5.3 Possible object attributes

The <hspace> tag inherits all object attributes from the generic <view> tag but has none of its own.

### 2.7.5.4 Content

A <hspace> tag has no content.

### 2.7.5.5 Examples

<hspace> 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.

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 <hspace>, so the button always remains at the right end of the <hbox>:

    <hbox>
      <hspace />
      <button title="Close" action="performClose:" />
    </hbox>

<hspace> tags rarely have any attributes and have never any content.

## 2.7.6 The image tag

### 2.7.6.1 Description

An <image> tag represents an image, and normally generates an instance of NSImageView. An NSImageView is a control which is used to display an image. Normally, you specify the image by putting an name="xxx" attribute into the tag, and the NSImageView is automatically sized to fit the image. The value of the name attribute is a string, which is used as argument to the NSImage method +imageNamed:. Typically you put the image (as a .png, or .gif, or .jpeg , or .tiff file) in the main application bundle.

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 -setImage: of the NSImageView), after the file has been loaded; or you can force a size of the image view (by using the width and height attributes which the <image> tag inherits from the generic <view> 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 editable="yes"), and then the user can change the image by dragging&dropping images from elsewhere.

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 scaling attribute, and how to align the image in the area (if not all of it is covered after the specified scaling) by using the alignment attribute. Please check the NSImageView documentation for more information on scaling and alignment.

### 2.7.6.2 Attributes

The <image> tag inherits all attributes from the generic <control> and <view> tags; in addition, it has the following ones:

- imageAlignment: The alignment (if needed). This attribute is a string, and is optional. It can be set to bottom, bottomLeft, bottomRight, center, left, right, top, topLeft or topRight. If you specify a size for the <image> 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.
- frameStyle: The type of frame (if used). This attribute is a string, and it is optional. It can be set to button, grayBezel, groove, none or photo. 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 hasFrame="yes" and let the system choose the natural native frame style, whatever that is.
- hasFrame: A boolean: if set to yes, 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.
- name: 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 [NSImage +imageNamed:], where the value of this attribute is used as the argument; if this attribute is not set, no image is actually displayed.
- scaling: The type of scaling (if needed). This attribute is a string, and it is optional. It can be set to none, proportionally or toFit. 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.

The <image> tag supports the instanceOf attribute.

### 2.7.6.3 Possible object attributes

The <image> tag inherits all object attributes from the generic <control> and <view> tags, but adds no specific of its own.

### 2.7.6.4 Content

An <image> tag has no content.

### 2.7.6.5 Examples

In the typical usage, you have an image in your main application bundle called for example GreenArrow.png. To display the image in a window, you can use the <image> tag:

    <image name="GreenArrow" />

## 2.7.7 The instance tag

### 2.7.7.1 Description

An <instance> tag represents an instance of a custom class. You specify the custom class and an object of that class is created.

### 2.7.7.2 Attributes

- instanceOf: The name of the class. This attribute is a string, and is required.

### 2.7.7.3 Possible object attributes

This depends on the class – each class has different object attributes.

### 2.7.7.4 Content

No content.

### 2.7.7.5 Examples

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.

    <instance instanceOf="MyController" id="Controller"
              textField="#TextField" />

in this example, the class MyController should have the method setTextField:.

## 2.7.8 The label tag

### 2.7.8.1 Description

A <label> tag represents a non-editable string displayed inside the window; it normally generates an instance of NSTextField configured to be non-editable and with no border.

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.

A <label> tag draws its background if and only if the backgroundColor attribute is set.

### 2.7.8.2 Attributes

A <label> inherits all the attributes of the <view> and <control> tags; moreover, it supports the following ones:

- backgroundColor: 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.
- textColor: a color attribute that determines the color used to draw the text.
- selectable: 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).

The <label> tag supports the instanceOf attribute.

### 2.7.8.3 Possible object attributes

The <label> tag inherits all object attributes from the generic <control> and <view> tags, but adds no specific of its own.

### 2.7.8.4 Content

The content of a label tag is the localized string that is displayed by the label.

### 2.7.8.5 Examples

In most cases, a label tag works very well with no attributes:

    <label>Path to the executable</label>

The most common attribute for labels is the font attribute, as in the following example showing labels with different fonts:

    <window>
      <vbox>
        <label font="big">Big font</label>
        <label>Normal font</label>
        <label font="small">Small font</label>
      </vbox>
    </window>

You may also want to set the color and/or background:

    <label textColor="blue" backgroundColor="white">Blue on white</label>

## 2.7.9 The menu tag

### 2.7.9.1 Description

A <menu> tag represents a menu, and normally generates an instance of NSMenu.

### 2.7.9.2 Attributes

- autoenablesItems: A boolean: if set to no, disables autoenabling of its menu items (which is otherwise enabled by default).
- title: The title of the menu (a localizable string).
- type: If set to main, then the menu is made the application main menu (by invoking setMainMenu: of the shared NSApplication). If set to windows, then the menu is made the application windows menu (by invoking setWindowsMenu: of the shared NSApplication). If set to services, then the menu is made the application services menu (by invoking setServicesMenu: of the shared NSApplication). If set to font, then the menu is created as the font menu (by using the menu fontMenu: of the shared NSFontManager); 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 apple, then the menu is made the application apple menu (by invoking setAppleMenu: of the shared NSApplication); if running on Apple Mac OS X; it is ignored otherwise.

The <menu> tag does not support the instanceOf attribute.

### 2.7.9.3 Possible object attributes

None.

### 2.7.9.4 Content

A menu can contain menuItem, menuSeparator and menu tags. Each menuItem tag represents a menu item which is added to the menu. Each menuSeparator tag represents a menu separator which is added to the menu. Each menu represents a submenu.

### 2.7.9.5 Examples

Normally, the only attribute of menus you're likely to use is the type attribute, which is used to make a menu the main, windows, services or font menu.

    <menu type="main">
      <menuItem title="Info Panel..." action="orderFrontStandardInfoPanel:" />
      <menuItem title="Hide" action="hide:" keyEquivalent="h" />
      <menuItem title="Quit" action="terminate:" keyEquivalent="q" />
    </menu>

Here is an example of a menu holding a submenu:

    <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>

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.

### 2.7.9.6 Portability

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.

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 main() function, before calling NSApplicationMain() (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 main menu, containing the apple submenu as its first item. There should be one, and only one, apple 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 Examples/Applications/CurrencyConverter in the Renaissance distribution).

## 2.7.10 The menuItem tag

### 2.7.10.1 Description

A <menuItem> tag represents a menu item to be added to a menu, and normally generates an instance of NSMenuItem.

### 2.7.10.2 Attributes

- action: The action of the menuItem (a string, non localized, which is converted into a selector).
- enabled: A boolean; if no, the menuItem is disabled (it is enabled by default). If your menu autoenables its items, this is not particularly useful.
- image: The image of the menuItem (an image).
- keyEquivalent: The keyEquivalent of the menuItem (normally a single character).
- keyEquivalentModifierMask: 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 commandKey). It can be set to noKey, shiftKey, commandKey, controlKey or alternateKey. In addition to that, you can specify combinations of these values by using the | character; for example commandKey||controlKey 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).
- state: The state of the menuItem (either on, or off or mixed). 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.
- tag: The tag of the menuItem (an integer).
- title: The title of the menuItem (a localizable string).

The <menuItem> tag does not support the instanceOf attribute.

### 2.7.10.3 Possible object attributes

- target: The target of the menuItem.
- representedObject: The representedObject of the menuItem.

### 2.7.10.4 Content

A menuItem has no content.

### 2.7.10.5 Examples

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:

    <menuItem title="Quit" action="terminate:" />

Here is an example of a menuItem displaying an on/off tickmark and changing state:

    <menu title="Options">
      <menuItem title="Full Headers" state="on" action="fullHeadersChanged:" />
      <menuItem title="Hide spam" state="on" action="hideSpamChanged:" />
    </menu>

You need to implement the actions, and have them change the state of the menuItem each time, to see the state change.

## 2.7.11 The menuSeparator tag

### 2.7.11.1 Description

A <menuSeparator> tag represents a separator in a menu, and normally inserts into the menu a [NSMenuItem separatorItem]. It is a very simple tag, with no attributes nor content; it is opened, and immediately closed, as in

    <menuSeparator />

It can only be used inside the contents of a menu. It is usually represented by a [NSMenuItem separatorItem] object, but that is not compulsory – it can be mapped to whatever standard way of inserting separators in NSMenus is used on that platform.

### 2.7.11.2 Attributes

A menuSeparator tag has no attributes. The <menuSeparator> tag does not support the instanceOf attribute.

### 2.7.11.3 Possible object attributes

A menuSeparator tag has no possible object attributes.

### 2.7.11.4 Content

A menuSeparator tag has no content.

### 2.7.11.5 Examples

A menuSeparator is often used on Apple Mac OS X to visually separate and group menu items in menus, as in the following example:

    <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>

## 2.7.12 The panel tag

### 2.7.12.1 Description

A <panel> tag represents a panel, and normally generates an instance of NSPanel. 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 NSPanel instead of a NSWindow object, and that it has a few more attributes, specific to panels.

### 2.7.12.2 Attributes

All the attributes recognized by the <window> tag, plus:

- becomesKeyOnlyIfNeeded: A boolean. If set to yes, sets the panel to become key only if needed.
- floating: A boolean. If set to yes, sets the panel to be a floating panel.
- worksWhenModal: A boolean. If set to yes, sets the panel to work when modal.

The <panel> tag supports the instanceOf attribute.

### 2.7.12.3 Possible object attributes

The same possible object attributes as for the <window> tag.

### 2.7.12.4 Content

The same content as the <window> tag.

### 2.7.12.5 Examples

      <panel title="Inspector" autosaveName="Inspector" floating="yes">
        <vbox>
          <!-- all sort of goodies go in here -->
        </vbox>
      </panel>

## 2.7.13 The secureTextField tag

### 2.7.13.1 Description

A <secureTextField> 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 NSSecureTextField configured to be editable, selectable and with the distinctive appearance of a secure, editable text field.

The only difference between a <secureTextField> tag and a <textField> one is that a <secureTextField> creates an instance of NSSecureTextField, 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.

### 2.7.13.2 Attributes

A <secureTextField> has exactly the same attributes as a <textField> tag.

### 2.7.13.3 Possible object attributes

A <secureTextField> has exactly the same possible object attributes as a <textField> tag.

### 2.7.13.4 Content

A <secureTextField> has exactly the same content as a <textField> tag.

### 2.7.13.5 Examples

In most cases, a secureTextField tag works very well with no attributes, or with a minimal width set:

    <hbox><label>Password:</label> <secureTextField width="200" /></hbox>

For more examples, see the description of <textField>.

## 2.7.14 The textField tag

### 2.7.14.1 Description

A <textField> tag represents an editable text field displayed inside the window; it normally generates an instance of NSTextField configured to be editable, selectable and with the distinctive appearance of an editable text field.

You can also make the control non-editable or non-selectable by using the corresponding attributes.

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.

### 2.7.14.2 Attributes

A <textField> inherits all the attributes of the <view> and <control> tags; moreover, it supports the following ones:

- allowsEditingTextAttributes: a boolean attribute. When set to yes, the user can edit the font and text attributes of the text displayed in the text field.
- backgroundColor: a color attribute that determines the color of the background.
- drawsBackground: 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.
- editable: 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.
- importsGraphics: a boolean attribute. When set to yes, the user can drag image files into the text field.
- selectable: 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.
- textColor: a color attribute that determines the color used to draw the text.

The <textField> tag supports the instanceOf attribute.

### 2.7.14.3 Possible object attributes

The <textField> tag inherits all object attributes from the generic <control> and <view> tags, and adds:

- delegate: The delegate of the text field (see the documentation of the NSTextField class for more information on using delegates).

### 2.7.14.4 Content

The content of a textField tag is the localized string that is displayed in the text field.

### 2.7.14.5 Examples

In most cases, a textField tag works very well with no attributes:

    <hbox><label>Name:</label> <textField /></hbox>

Sometimes you may want to set the delegate attribute if you want your software to be informed in real-time of changes to the text field contents:

    <hbox><label>Name:</label> <textField delegate="#NSOwner" /></hbox>

You then need to implement the appropriate text field delegate methods in your file owner object.

## 2.7.15 The vbox tag

### 2.7.15.1 Description

A <vbox> tag represents an invisible vertical autolayout container that can hold other views, and normally generates an instance of GSAutoLayoutHBox.

A <vbox> object is identical to a <hbox> object, but it holds views in a column instead of a row. Please refer to the description of the <hbox> tag for details of the tag.

### 2.7.15.2 Attributes

The <vbox> tag inherits all attributes from the generic <view> tag; in addition, it has the following ones:

- type: 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.

The <vbox> tag supports the instanceOf attribute.

### 2.7.15.3 Possible object attributes

The <vbox> tag inherits all object attributes from the generic <view> tag but has none of its own.

### 2.7.15.4 Content

A <vbox> tag has its subviews as its content. They are created in the order they are listed, and displayed from top to bottom.

### 2.7.15.5 Examples

See the examples for the <hbox> tag.

## 2.7.16 The view tag

### 2.7.16.1 Description

A <view> tag represents a view, and normally generates an instance of NSView. Instances of NSView are not particularly useful as they are (NSView instances represent rectangular regions in a window, and don't do much), which is why <view> tags are normally only used with an instanceOf attribute to create custom view objects.

The attributes of <view> tags are inherited by all tags whose instances inherit from NSView – this includes anything you can put inside a window. Of particular interest is the autolayout behaviour, which is again inherited by all tags.

When the view instance created by a <view> tag is initialized, the method sizeToFitContent of the instance is first called. This method resizes the instance to fit its content. Then, the x, y height and width 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 x, y, height or width overrides the automatically computed size and position.

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 halign, valign, hborder, vborder and span. There is also an additional attribute border, which is a currently a short-cut for setting both the hborder and vborder attributes (and might be removed in the future).

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. halign and valign 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; hborder and vborder control the horizontal and vertical border around the view when in the container; span is used with proportional boxes, for special effects when a view spans more than a single slot in the box.

The system will also set default values for the autoresizingMask basing on the autolayout properties, so that if you put your view inside an old-fashioned container such as a <box>, you can control its autoresizing behaviour using the usual autolayout flags.

### 2.7.16.2 Attributes

- autoresizesSubviews: 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.
- autoresizingMask: 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 halign and valign 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 halign and valign. 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 'h' means to set the NSViewHeightSizable flag; a 'w' means to set the NSViewWidthSizable flag; a 'x' means to set the NSViewMinXMargin flag; a 'X' means to set the NSViewMaxXMargin flag; a 'y' means to set the NSViewMinYMargin flag; a 'Y' means to set the NSViewMaxYMargin flag. For example, an attribute value of “hw” means NSViewHeightSizable | NSViewWidthSizable. 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 halign and valign property; if any of the two is not set, the object's -autolayoutDefaultHorizontalAlignment or -autolayoutDefaultVerticalAlignment method is called to get a default value that can be used.
- border: A float. If set, this is equivalent to setting both hborder and vborder to that same value. This attribute might be removed in future releases.
- halign: A string, which can take one of the values expand, wexpand, left, center, right. min is also accepted as an alias for left, and max as an alias for right. This attribute is only used by an eventual enclosing autolayout container (such as a hbox or a vbox). expand 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. wexpand 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. left, center and right 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 1.9.
- hborder: 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).
- height: 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.
- hidden: A boolean. If set to yes, it changes the view to be hidden.
- proportion: 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 proportion="2" attribute takes up twice the space as normal view in a proportional hbox.
- toolTip: A localizable string. If set, the view tool tip is set to it.
- valign: A string, which can take one of the values expand, wexpand, top, center, bottom. min is also accepted as an alias for bottom, and max as an alias for top. 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 halign attribute; the attribute values have the same meaning in the vertical direction.
- vborder: 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).
- width: 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.
- x: A float. If set, the x coordinate of the origin of the view frame is set to this value.
- y: A float. If set, the y coordinate of the origin of the view frame is set to this value.

The <view> tag supports the instanceOf attribute.

### 2.7.16.3 Possible object attributes

- nextKeyView: 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!).

### 2.7.16.4 Content

Usually <view> 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 <hbox> or <vbox> 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.

To support corner cases and static placement of subviews, if you add some view tags as content to a <view> 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 <view> 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).

### 2.7.16.5 Examples

Usually <view> tags are used to create custom views, in which case the instanceOf is used. Custom views representing editable areas often have have hardcoded width and height attributes – but other types of custom views might be able/need to autosize.

    <view instanceOf="BandView" id="BandView" width="200" height="100" />

Here is an example of using a <view> tag to create a view and put some subviews at fixed locations into it:

    <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>

## 2.7.17 The vspace tag

### 2.7.17.1 Description

A <vspace> tag represents invisible vertical weakly-expanding space that can be put into autolayout containers such as <vbox> objects for alignment purporses. It normally generates an instance of GSAutoLayoutVSpace.

A <vspace> is identical to a <hspace>, but expands vertically instead of horizontally. You should always use <vspace> tags inside <vbox> tags, and <hspace> tags inside <hbox> tags.

### 2.7.17.2 Attributes

The <vspace> tag inherits all attributes from the generic <view> tag but adds no new attributes of its own.

The <vspace> tag supports the instanceOf attribute.

### 2.7.17.3 Possible object attributes

The <vspace> tag inherits all object attributes from the generic <view> tag but has none of its own.

### 2.7.17.4 Content

A <vspace> tag has no content.

### 2.7.17.5 Examples

See the examples for the <vspace> tag.

## 2.7.18 The window tag

### 2.7.18.1 Description

A <window> tag represents a window, and normally generates an instance of NSWindow. 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.

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).

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 expand set in a direction, Renaissance records that the window should be made resizable in that direction; if it set to anything else (including wexpand), 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).

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.

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.

Last, the window is ordered front (by using orderFront:), unless the attribute visible has been set to no; it is also made the key window (by using makeKeyWindow) 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 makeMainWindow).

### 2.7.18.2 Attributes

- autosaveName: 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.
- backgroundColor: A color. If set, the window natural background color is overridden by this color.
- borderless: A boolean. If set to yes, the window is created without any decorations.
- center: A boolean. If set to yes, the window is automatically centered when it is created.
- closable: 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).
- contentHeight: 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).
- contentWidth: 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).
- heigth: A positive float. If set, the heigth of the window frame is set to this value. See comments for x about interaction with autosaved frame.
- keyWindow: 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.
- mainWindow: 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.
- maxHeigth: A positive float. If set, the heigth of the window maximum size is set to this value.
- maxWidth: A positive float. If set, the width of the window maximum size is set to this value.
- minHeigth: A positive float. If set, the heigth of the window minimum size is set to this value.
- minWidth: A positive float. If set, the width of the window minimum size is set to this value.
- miniaturizable: A boolean. If set to no, the window is created non miniaturizable (it is miniaturizable otherwise, unless borderless is set to yes).
- releasedWhenClosed: 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.
- resizable: 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).
- title: A localizable string. If set, the window title is set to it.
- titled: A boolean. If set to no, the window is created without a titlebar (it has a titlebar otherwise, unless borderless is set to yes).
- visible: 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 orderFront:) after they are created. By setting visible to no, you can prevent this to happen.
- width: A positive float. If set, the width of the window frame is set to this value. See comments for x about interaction with autosaved frame.
- x: 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.
- y: A float. If set, the y coordinate of the origin of the window frame is set to this value. See comments for x about interaction with autosaved frame.

The <window> tag supports the instanceOf attribute.

### 2.7.18.3 Possible object attributes

- delegate: The window delegate.
- initialFirstResponder: The window initialFirstResponder.

### 2.7.18.4 Content

A <window> 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.

### 2.7.18.5 Examples

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 <panel> tag, which accepts all the attributes of a <window> tag, but creates a NSPanel rather than a NSWindow (and has a few panelish attributes more). An example window with nothing inside:

      <window title="My First Window" />

A window containing a button:

      <window title="Test" center="yes" autosaveName="terminate">
        <button title="Click to quit the application" action="terminate:">
      </window>

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:

    <window title="frame of 500x100" autosaveName="fixedFrameExample"
            width="500" heigth="100" />