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

Subsections


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

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:

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

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

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

2.7.4 The menuItem tag

2.7.4.1 Description

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

2.7.4.2 Attributes

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

2.7.4.3 Possible object attributes

2.7.4.4 Content

A menuItem has no content.

2.7.4.5 Examples

In most cases, you just set title, action and key 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.5 The menuSeparator tag

2.7.5.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.5.2 Attributes

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

2.7.5.3 Possible object attributes

A menuSeparator tag has no possible object attributes.

2.7.5.4 Content

A menuSeparator tag has no content.

2.7.5.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:" key="h"/>
    <menuItem title="Hide Others" action="hideOtherApplications:"/>
    <menuItem title="Show All" action="unhideAllApplications:"/>
    <menuSeparator/>
    <menuItem title="Quit CurrencyConverter" action="terminate:" key="q"/>
  </menu>
</menu>

2.7.6 The panel tag

2.7.6.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.6.2 Attributes

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

The <panel> tag supports the instanceOf attribute.

2.7.6.3 Possible object attributes

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

2.7.6.4 Content

The same content as the <window> tag.

2.7.6.5 Examples

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

2.7.7 The view tag

2.7.7.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 this 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.

2.7.7.2 Attributes

The <view> tag supports the instanceOf attribute.

2.7.7.3 Possible object attributes

2.7.7.4 Content

TODO: It seems that the content should be a list of subviews. This is not implemented yet.

2.7.7.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"/>

2.7.8 The window tag

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

2.7.8.2 Attributes

The <window> tag supports the instanceOf attribute.

2.7.8.3 Possible object attributes

2.7.8.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.8.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"/>


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