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.
A <box> tag represents a box, and normally generates an
instance of NSBox. A box is a way of grouping some views and
add a title to the group. Normally the only attributes to set in a
box is the title (the text displayed as a title to the
group). If no title is specified, then the box displays no
title.
A number of other attributes are available to expose some of the
customizations available in the NSBox class; for example, you
can change the border type, the title font and the title position.
Unless you have a special reason to use these attributes, we recommend
not using them so that Your <box> will automatically use the
platform defaults and look at its best.
A <box> tag includes some content, which should be a single
tag. If you want to put more than one view in a <box>, you
should use an autolayout container such as a <vbox>,
<hbox> or <grid>.
The <box> tag inherits all attributes from the generic
<view> tag; in addition, it has the following ones:
- borderType: The type of border. This attribute is a
string, and is optional. It can be set to noBorder,
lineBorder, bezelBorder and grooveBorder.
We recommend not setting this attribute and so using the platform
default unless you have special reasons to change it.
- title: The text of the button, if any. This is an
optional localized string attribute. If this attribute is missing,
the titlePosition of the box is automatically set to noTitle, so if
you want to use the box to group a set of views with no title, you
can simply omit the title attribute.
- titleFont: This attribute is a font string; it is
optional; if set, it determines what font is used to display the
title (if any) displayed by the box. See the discussion on font
attributes for possible values. We recommend not setting this
attribute and so using the platform default unless you have special
reasons to change it.
- titlePosition: The position of the title. This attribute
is a string, and is optional. It can be set to noTitle,
aboveTop, atTop, belowTop,
aboveBottom, atBottom and belowBottom.
We recommend not setting this attribute and so using the platform
default unless you have special reasons to change it.
The <box> tag supports the instanceOf attribute.
The <box> tag inherits all object attributes from the generic
<view> tag, but adds no specific of its own.
A <box> tag has one view as its content. This view is
displayed inside the NSBox. If you put more than one view
directly inside a <box> tag, only the first one is displayed;
use an autolayout container such as a <vbox>, <hbox>
or <grid> if you need to put more than one views.
The most common usage of the <box> tag is to group some options or views. When
used in this way, a <vbox> is very often used as its content:
<window>
<vbox>
<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>
</vbox>
</window>
Sometimes, a <box> is used with no title to group some views:
<window>
<vbox>
<box>
<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>
</vbox>
</window>
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.
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.
The <button> tag inherits all object attributes from the
generic <control> and <view> tags, but adds no
specific of its own.
A <button> tag has no content.
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>
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).
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.
The <colorWell> tag inherits all object attributes from the
generic <control> and <view> tags, but adds no
specific of its own.
A <colorWell> tag has no content.
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>
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.
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.
The <control> tag inherits all object attributes from the
generic <view>, and adds the following ones:
- target: The target of the control.
None.
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).
A <grid> tag represents an invisible autolayout container
that can hold other views, and normally generates an instance of
GSAutoLayoutGrid. This is a fairly general autolayout
container which keeps views in an invisible grid with rows and
columns; it provides functionality which is a superset of horizontal
boxes and vertical boxes.
The grid can have standard or proportional columns,
and standard or proportional rows. These settings
are almost identical to the ones for horizontal and vertical boxes.
Standard rows or columns are the default. The size of each row or
column only depends on the views in that row or column. Setting the
row or column type to proportional causes a different behaviour, where
all the rows (or columns) are forced to have the same (or a
proportional) size. For example, if you want to organize your views
in 3 invisible columns of identical size, you would set
columnType to proportional.
See the description of the hbox tag for a more detailed
explanation of standard and proportional.
Normally you should use standard columns and rows unless you are
trying to recreate some eye-pleasing special alignment, such as having
rows or columns of the same (or proportional) size.
The <grid> tag inherits all attributes from the generic
<view> tag; in addition, it has the following ones:
- columnType: The type of columns; this attribute is a
string, and is optional. It can be 'standard' (the default) or
'proportional'. A grid with standard columns resize the columns to
fit the views that they contain; there is no particular relationship
between the widths of the various columns. A grid with proportional
columns instead holds columns which have a width that is
proportional to a layout unit (normally each column takes up 1
layout unit; this can be changed by specifying a 'proportion'
attribute for some of them). If nothing is specified, the grid is
by default created with standard columns.
- rowType: The type of rows; this attribute is a string, and
is optional. It can be 'standard' (the default) or 'proportional'.
A grid with standard rows resize the rows to fit the views that they
contain; there is no particular relationship between the widths of
the various rows. A grid with proportional rows instead holds rows
which have a width that is proportional to a layout unit (normally
each row takes up 1 layout unit; this can be changed by specifying a
'proportion' attribute for some of them). If nothing is specified,
the grid is by default created with standard rows.
The <grid> tag supports the instanceOf attribute.
The <grid> tag inherits all object attributes from the
generic <view> tag but has none of its own.
A <grid> tag has a number of <gridRow> tags as its
content. They are created in the order they are listed, and displayed
from top to bottom. Each <gridRow> contains the views to
display in that row. If a view is missing (because some views use a
columnSpan to span multiple columns), <gridEmptyCell /> tags
can be used to fill the voids.
<grid> are advanced autolayout containers and are used only
when advanced layouts are required. In most cases, they have no
attributes and only have content (consisting of a number of
<gridRow> tags). Here is an example with two buttons in a
row, showing a <grid> doing the job of a <hbox>:
<grid>
<gridRow>
<button title="Miniaturize" action="performMiniaturize:" />
<button title="Close" action="performClose:" />
</gridRow>
</grid>
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:
<grid columnType="proportional">
<gridRow>
<button title="Miniaturize" action="performMiniaturize:" />
<button title="Close" action="performClose:" />
</gridRow>
</grid>
The following example is more interesting as it shows a layout which
can not be obtained by using only <hbox> and <vbox>
tags. There are two rows, but the labels are also vertically aligned:
<grid>
<gridRow>
<label halign="right">Name:</label>
<textField id="name" width="150" />
</gridRow>
<gridRow>
<label halign="right">Surname:</label>
<textField id="surname" width="150" />
</gridRow>
</grid>
A <gridEmptyCell> tag represents an empty cell in a
<grid>. This tag is used to describe the positioning of
views inside a grid, and does not generate any actual object. It is
mostly used when the cell is already occupied by another view which
has a rowSpan or a columnSpan set to a number
greater than 1.
Note that a <gridEmptyCell> is different from a
<space>. A <space> would generate a view with zero
size. A <gridEmptyCell> instead generates nothing so that
the cell is left completely empty. In the case where the cell is
already occupied by a view which spans multiple rows or columns, a
<space> wouldn't work as the cell is already occupied by
another view, which is why a <gridEmptyCell> must be used
instead.
The <gridEmptyCell> tag has no attributes.
The <gridEmptyCell> tag does not support the instanceOf
attribute.
The <gridEmptyCell> tag has no object attributes.
A <gridEmptyCell> tag has no content.
<gridEmptyCell> are used whenever a <grid> is used,
and some view spans more than one row or column. For example:
<grid>
<gridRow>
<label halign="center" columnSpan="2">London</label>
<gridEmptyCell />
</gridRow>
<gridRow>
<label halign="right">Timezone:</label>
<label halign="left">GMT</label>
</gridRow>
<gridRow>
<label halign="right">Date:</label>
<label halign="left">7 May 2010</label>
</gridRow>
<gridRow>
<label halign="right">Time:</label>
<label halign="left">00:54</label>
</gridRow>
</grid>
In this case, the first label spans two columns, and a
<gridEmptyCell> is used as a placeholder in the slot in the
second column.
A <gridRow> tag represents a row in a <grid>. This
tag is used to describe the positioning of views inside a grid, and
does not generate any actual object.
The gridRow contains the views that are displayed in that row of the
grid.
The <gridRow> tag has a single attribute:
- proportion: A float. If set, the proportion of the row is
set to that value. This is only used by the enclosing grid if is
configured with rowType set to proportional. For
example, a row with a proportion="2" attribute takes up
twice the space as normal row in a grid with proportional rows.
The <gridRow> tag does not support the instanceOf
attribute.
The <gridRow> tag has no object attributes.
A <gridRow> tag has a number of views as its content. These
views are added to the grid row in the order in which they are
introduced.
If a view has a rowSpan or columnSpan attribute set,
it will occupy more than one slot in the grid. For example, a view
with columnSpan="2" will span two columns. The spot in the
next column should be left empty; you do this by adding a
<gridEmptyCell /> tag.
<gridRow> are used whenever a <grid> is used. See
the description of the grid tag for examples; here we only
provide one to show how to use the proportion attribute of
<gridRow>.
<grid rowType="proportional">
<gridRow>
<label halign="right">Summary:</label>
<scrollView height="60" width="200"><textView /></scrollView>
</gridRow>
<gridRow proportion="4">
<label halign="right">Full Text:</label>
<scrollView height="100" width="200"><textView /></scrollView>
</gridRow>
</grid>
In this case, the second row is automatically and always kept 4 times
bigger, in height, than the first one.
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.
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.
The <hbox> tag inherits all object attributes from the
generic <view> tag but has none of its own.
A <hbox> tag has its subviews as its content. They are
created in the order they are listed, and displayed from left to
right.
<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>
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.
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.
The <hspace> tag inherits all object attributes from the
generic <view> tag but has none of its own.
A <hspace> tag has no content.
<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.
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
imageAlignment 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:
- animates: A boolean. It is optional and determines if the
image automatically plays animated images or not.
- allowsCutCopyPaste: A boolean. It is optional and
determines if the image view allows cut, copy and paste or not.
- editable: A boolean. It is optional; if set to
yes, the image will be editable. If not set, by default
images are not editable.
- 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.
- imageAlignment: The alignment (if needed). This attribute
is a string, and is optional. The name of the attribute is
'imageAlignment' instead of simply 'alignment' to clarify that it
has no relationship with the Renaissance autolayout alignment. 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.
An <image> tag has 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 <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.
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.
The <label> tag inherits all object attributes from the
generic <control> and <view> tags, but adds no
specific of its own.
The content of a label tag is the localized string that is
displayed by the label.
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>
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, 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.
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:" 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.
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 [NSApp
run]. 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).
- 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.
- 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 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.
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:" 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>
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 <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.
A <secureTextField> has exactly the same attributes as a
<textField> tag.
A <secureTextField> has exactly the same possible object
attributes as a <textField> tag.
A <secureTextField> has exactly the same content as a
<textField> tag.
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>.
A <space> tag represents invisible weakly-expanding space
that can be put into autolayout containers such as <grid>
objects for alignment purporses. It normally generates an instance of
GSAutoLayoutSpace.
An <space> has zero size by default, but expands horizontally
if there is horizontal space available and vertically if there is
vertical space available. It is usually used to fill an empty grid
position in a <grid>.
Please note that the only difference between <space>,
<hspace> and <vspace> is their default expanding
behaviour. A <space> will expand in all directions if space
is available; a <hspace> will expand only horizontally and a
<vspace> will expand only vertically. By using the
halign and valign flags, you can effectively convert
one space object into another one; for example, <space
halign="center" /> will create a space object that behaves exactly
like a <vspace> since it would only expand vertically.
The default behaviour is such that <hspace> is the natural
choice in hboxes, <vspace> in vboxes and <space> in
grids.
The <space> tag inherits all attributes from the generic
<view> tag but adds no new attributes of its own.
The <space> tag supports the instanceOf attribute.
The <space> tag inherits all object attributes from the
generic <view> tag but has none of its own.
A <space> tag has no content.
<space> is mostly useful when using a <grid> object.
In a grid object, you may want to leave some positions in the grid
empty; a <space> tag provides you with something to put in
there. By default, a <space> tag will expand in all
directions when more space is available; you can inhibit this by using
the attribute halign="center" (which will prevent it from
expanding horizontally) or valign="center" (which will
prevent it from expanding vertically). This may be important; for
example if you put your <space> in a grid column where all
the other elements in the column do not expand horizontally, the
<space> would be the one causing the column to expand
horizontally when more space is available. You can stop it by simply
adding halign="center" to the <space>.
The following unlikely example shows a grid displaying the month, day
of the month and day of the week. There is a space at the bottom left
which is filled by using a <space> tag. Everything is static
and doesn't expand; for this reason, the <space> tag is made
non-expanding by using halign="center" and
valign="center":
<grid>
<gridRow>
<label>MAY</label> <label>5</label>
</gridRow>
<gridRow>
<space halign="center" valign="center" /> <label>WED</label>
</gridRow>
</grid>
<space> tags rarely have any attributes other than
halign and valign and have never any content.
A <splitView> tag is a container that displays a number of
subviews separated by horizontal (or vertical) bars that the user can
drag to increase/decrease the space allocated to the various subviews.
It normally generates an instance of NSSplitView. The
content of the tag are the splitview's subviews; they are displayed
separated by dividers that the user can drag to adjust how much
visible space is given to each subview.
The <splitView> tag inherits all attributes from the generic
<view> tag; in addition, it has the following ones:
- autosaveName: A string (not localized). If set, the
splitView autosaveName is set to it causing the splitView to
automatically save and restore in the user defaults the position of
the split bars. This currently only works on Apple Mac OS X >= 10.5
and GNUstep GUI >= 0.13.3; but it's safe to use it since on other
platforms it will be simply ignored.
- isPaneSplitter: a boolean attribute. When set, the value
is passed to -setIsPaneSplitter: and determines how the splitView
split bar appears. This currently has some effect only on Apple Mac
OS X.
- vertical: a boolean attribute. When set to yes, the
splitview's divider is vertical instead of horizontal. The default
is no.
The <splitView> tag supports the instanceOf attribute.
The <splitView> tag inherits all object attributes from the
generic <view> tag and adds:
- delegate: The delegate of the splitview (see the
documentation of the NSSplitView class for more information on using
delegates).
A <splitView> tag has its subviews as its content. They are
created in the order they are listed, and displayed from top to bottom
(or from left to right).
A typical usage of a <splitView> is with one or more large
<textView> to allow the user to shrink on demand the visible
space used by each text view in favour of displaying other controls,
as in the following example where the splitView contains two text
views:
<splitView>
<scrollView width="400" height="300">
<textView id="code" />
</scrollView>
<scrollView width="400" height="300">
<textView id="compilerOutput" editable="no" />
</scrollView>
</splitView>
This could be used for example when the top textView allows the user
to type in code in a programming language, and the bottom contains the
output of some programming tool (eg, a compiler compiling the code in
the top view).
The most useful attribute of a <splitView> is the
vertical attribute, which can be used to have a vertical,
instead of horizontal, divider, as in the following example, where a
list of files on the left subview is displayed alongside a textView
constituting the right subview:
<splitView vertical="yes">
<vbox>
<label>/home/nicola/devmodules/dev-libs/libobjc</label>
<label>/home/nicola/devmodules/core/make</label>
<label>/home/nicola/devmodules/core/base</label>
<label>/home/nicola/devmodules/core/gui</label>
<label>/home/nicola/devmodules/core/back</label>
<label>/home/nicola/devmodules/dev-libs/renaissance</label>
</vbox>
<scrollView width="300" height="200">
<textView id="editArea" />
</scrollView>
</splitView>
A <tabView> tag represents a tabView, and normally generates
an instance of NSTabView. A tabView is used to manage a
number of tabViewItems; one tabViewItem, the selected one, is
displayed, while the others are hidden. By default the selection of
which tabViewItem to display is usually done by the user by selecting
the ``label'' corresponding to the tabViewItem to display. It is also
possible to set the viewType attribute to
noTabsNoBorder which causes the tabView to not display the
labels; in this case, switching between the tabViews can be done
programmatically. This is a good solution for inspector windows, for
example, which contains a view that changes depending on what is
selected or focused in another window.
So, a <tabView> tag normally contains a number of
<tabViewItem> tags, each of them repesenting a tabViewItem.
Usually it has no attributes, but the viewType attribute can
be used to remove the tabs.
The <tabView> tag inherits all attributes from the generic
<view> tag; in addition, it has the following ones:
- allowsTruncatedLabels: A boolean attribute; if set to yes,
the tabView allows truncating labels that are too big to be
displayed in a tab; if set to no, it does not. If this attribute is
not set, the default for the platform is used, which should be no
according to the documentation.
- drawsBackground: A boolean attribute which is only useful
when the viewType is set to noTabsNoBorder. In
that case, if drawsBackground is set to yes, the tabView will draw a
background; if set to no, it will not. If this attribute is not
set, the default for the platform is used. We recommend not setting
this attribute unless there is a special reason to, and using the
default platform behaviour.
- viewType: The type of tab view. This is a string, and
controls if tabs are displayed, and where. The possible values are
topTabsBezelBorder, which is the default and displays tabs
on top, leftTabsBezelBorder, rightTabsBezelBorder
and bottomTabsBezelBorder, which display tabs but in
different positions, noTabsNoBorder,
noTabsLineBorder and noTabsBezelBorder, which
display no tabs and a different border. We recommend not setting
this attribute if you need the default behaviour of having tabs
displayed on top, and setting it to noTabsNoBorder if you
are using the tabView as a fixed-size container to switch between
different views programmatically.
The <tabView> tag supports the instanceOf attribute.
The <tabView> tag inherits all object attributes from the
generic <view> tag, and adds:
- delegate: The delegate of the tab view (see the
documentation of the NSTabView class for more information on using
delegates).
A <tabView> tag has a number of <tabViewItem> tags
as content. Each <tabViewItem> tag represents a tabViewItem.
They are added in the order specified in the XML. Please refer to the
<tabViewItem> tag documentation for more information on
creating tabViewItems.
The most common type of <tabView> tag is used in preference
panels and similar panels to allow the user to switch between
different views:
<window title="Mail Preferences">
<tabView>
<tabViewItem label="Servers">
<vbox>
<form width="200">
<formItem title="Incoming Server:" />
<formItem title="Outgoing Server:" />
<formItem title="Username:" />
<formItem title="Password:" />
</form>
</vspace>
</vbox>
</tabViewItem>
<tabViewItem label="Editor">
<vbox>
<hbox>
<label>Text color:</label>
<colorWell id="textColorWell" color="red" action="changedColor:"
target="#NSOwner" />
</hbox>
<vspace />
</vbox>
</tabViewItem>
</tabView>
</window>
It could also be used to have a number of views that can be swapped in
and out programmatically. To do so, simply use the
viewType="noTabsNoBorder" attribute, as in the following
example:
<window title="Inspector">
<tabView viewType="noTabsNoBorder">
<tabViewItem id="title">
<vbox>
<form width="200">
<formItem title="Title:" />
<formItem title="Alternate Title:" />
</form>
<vspace />
</vbox>
</tabViewItem>
<tabViewItem id="color">
<vbox>
<hbox>
<label>Color:</label>
<colorWell id="textColorWell" color="red" action="changedColor:"
target="#NSOwner" />
</hbox>
<vspace />
</vbox>
</tabViewItem>
</tabView>
</window>
Obviously, if you try this example without any supporting code, there
is no way of viewing the second tabViewItem. It is hidden and can
only be displayed programmatically. So you would need to select the
second view by writing code, for example you could select a different
view in the pane when a certain window or view is focused.
A <tabViewItem> tag represents a tabViewItem, and normally
generates an instance of NSTabViewItem. A tabViewItem
displays a view inside a tabView; only one tabViewItem is visible at
any time, while the others are hidden. The tabView controls the
selection of the tabViewItem to display.
A <tabViewItem> tag normally has a single attribute, the
label which is displayed in the tab. When the user clicks on
that label, the tabViewItem is selected. If tabs are hidden (because
the <tabView> has the attribute viewType set to
noTabsNoBorder), then the id attribute is usually
set to a string that can be used to programmatically identify the tab.
The id is automatically set as the programmatical identifier
of the tabViewItem.
A <tabViewItem> typically contains a single view as content,
usually an autolayout container such as a <hbox> or
<vbox>.
First of all, if the standard id attribute is set for a
<tabViewItem> tag, it is used as the NSTabViewItem
identifier. If you are not happy about this behaviour, you can
override it by using the identifier attribute described
below.
The <tabViewItem> tag has the following attributes:
- identifier: A string attribute that can set the
tabViewItem's identifier if you want it to be different from the
default, which is the id of the tag (if set). The
tabViewItem identifier can be used to programmatically select the
tabViewItem, for example using the NSTabView method
-selectTabViewItemWithIdentifier:. If this attribute is
not set, the tag's id attribute will be used as identifier.
We generally recommend using the id attribute instead of
the identifier attribute.
- label: A localizable string. If set, the tabViewItem
label is set to it.
- toolTip: A localizable string. If set, the tabViewItem
tool tip is set to it. This is only available in recent versions of
Apple Mac OS X and GNUstep, but it's safe to use it; if you set it
and the system does not support it, it simply won't be used.
The <tabView> tag supports the instanceOf attribute.
The <tabViewItem> tag has the following object attribute:
- initialFirstResponder: The initial first responder of the
tabViewItem (see the documentation of NSTabViewItem for more
information).
A <tabViewItem> tag has a single view as its content. This
view is set to be the tabViewItem's view by using the NSTabViewItem's
method -setView:. We recommend using an autolayout container
as this view; for example a <vbox> or <hbox>. You
would usually add a <vspace /> at the bottom of the
<vbox> to make sure the view is displayed on top.
Check the <tabView> tag documentation for examples.
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.
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.
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).
The content of a textField tag is the localized string that
is displayed in the text field.
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.
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.
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.
The <vbox> tag inherits all object attributes from the
generic <view> tag but has none of its own.
A <vbox> tag has its subviews as its content. They are
created in the order they are listed, and displayed from top to
bottom.
See the examples for the <hbox> tag.
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, topPadding, bottomPadding,
leftPadding, rightPadding and span. There
are also the additional attributes hPadding,
vPadding and padding, which are a short-cut for
setting multiple padding attribues in a single go: hPadding
sets both leftPadding and rightPadding,
vPadding sets both bottomPadding and
TopPadding, and padding sets all the padding
attributes.
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;
bottomPadding, topPadding, leftPadding and
rightPadding control the horizontal and vertical padding
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.
- 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.
- bottomPadding: A float. If set, the bottom padding of the view
is set to that value. This is only used by an eventual enclosing
autolayout container (such as a hbox or vbox).
- columnSpan: An integer. If set, the column span is set to
that value. This is only used by an eventual enclosing grid. For
example, a view with a columnSpan="2" attribute takes up
two columns in a grid.
- halign: A string, which can take one of the values
expand, wexpand, left, center,
right. bottom is also accepted an alias for
left, and top 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.
- hPadding: A float. If set, the leftPadding and
rightPadding are both 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.
- leftPadding: A float. If set, the left padding of the
view is set to that value. This is only used by an eventual
enclosing autolayout container (such as a hbox or vbox).
- padding: A float. If set, this is equivalent to setting
all of bottomPadding, topPadding, leftPadding
and rightPadding to that same value.
- 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.
- rightPadding: A float. If set, the right padding of the
view is set to that value. This is only used by an eventual
enclosing autolayout container (such as a hbox or vbox).
- rowSpan: An integer. If set, the row span is set to
that value. This is only used by an eventual enclosing grid. For
example, a view with a rowSpan="2" attribute takes up
two rows in a grid.
- toolTip: A localizable string. If set, the view tool tip
is set to it.
- topPadding: A float. If set, the top padding of the view
is set to that value. This is only used by an eventual enclosing
autolayout container (such as a hbox or vbox).
- valign: A string, which can take one of the values
expand, wexpand, top, center,
bottom. 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.
- vPadding: A float. If set, the bottomPadding and
topPadding are both 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!).
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).
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>
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.
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.
The <vspace> tag inherits all object attributes from the
generic <view> tag but has none of its own.
A <vspace> tag has no content.
See the examples for the <vspace> tag.
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).
- 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.
- 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
2010-06-30