Next: 2.8 Connector tag reference
Up: 2. The GNUstep Markup
Previous: 2.6 Integrating Renaissance in
Subsections
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.
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.
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.
The <image> tag inherits all object attributes from the
generic <control> and <view> tags, but adds no
specific of its own.
No content.
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"/>
An <instance> tag represents an instance of a custom class. You
specify the custom class and an object of that class is created.
- instanceOf: The name of the class. This attribute is a string,
and is required.
This depends on the class - each class has different object attributes.
No content.
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:.
A <menu> tag represents a menu, and normally generates an
instance of NSMenu.
- 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.
None.
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.
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.
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).
A <menuItem> tag represents a menu item to be added to a menu,
and normally generates an instance of NSMenuItem.
- 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 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.
- target: The target of the menuItem.
- representedObject: The representedObject of the menuItem.
A menuItem has no content.
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.
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.
A menuSeparator tag has no attributes. The
<menuSeparator> tag does not support the instanceOf
attribute.
A menuSeparator tag has no possible object attributes.
A menuSeparator tag has no content.
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>
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.
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.
The same possible object attributes as for the <window> tag.
The same content as the <window> tag.
<panel title="Inspector" autosaveName="Inspector" floating="yes">
<vbox>
<!-- all sort of goodies go in here -->
</vbox>
</panel>
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.
- autoresizingMask: A string. If this string is set, it is
used to manually override the default autoresizing mask with the one
provided. 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.
If you are trying to use the legacy OpenStep autoresizing system, then
this 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.
- border: A float. If set, this is equivalent to setting
both hborder and vborder to that same value.
- 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.
- span: A float. If set, the span of the view is set to that
value. This is only used by an eventual enclosing autolayout
container supporting view spans (such as a proportional hbox or vbox).
For example, a view with a span="2" attribute takes up twice
the space as normal view in a proportional hbox.
- 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.
- 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!).
TODO: It seems that the content should be a list of subviews. This is
not implemented yet.
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"/>
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.
- 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.
- 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.
- delegate: The window delegate.
- initialFirstResponder: The window initialFirstResponder.
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.
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