Next: 2.8 Connector tag reference Up: 2. The GNUstep Markup Previous: 2.6 Integrating Renaissance in

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

2.7.1.1 Description

An <image> tag represents an image, and 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.1.2 Attributes

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

alignment: 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.
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.1.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.1.4 Content

No content.

2.7.1.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.2 The instance tag

2.7.2.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.2.2 Attributes

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

2.7.2.3 Possible object attributes

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

2.7.2.4 Content

No content.

2.7.2.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.3 The menu tag

2.7.3.1 Description

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

2.7.3.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, the menu is made the application main menu (by invoking setMainMenu: of the shared NSApplication). If set to windows, the menu is made the application windows menu (by invoking setWindowsMenu: of the shared NSApplication). If set to services, the menu is made the application services menu (by invoking setServicesMenu: of the shared NSApplication). If set to font, 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, 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.3.3 Possible object attributes

None.

2.7.3.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.3.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:" key="h"/>
  <menuItem title="Quit" action="terminate:" key="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:" key="h"/>
  <menuItem title="Quit" action="terminate:" key="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.3.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).

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).
key: The keyEquivalent of the menuItem (normally a single character).
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 files
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