itemlocation

Specifies the location of an item in the page layout and also allows you set the size of the item, either in relation to another item, or in absolute terms.

Itemlocation offers three ways to position items on the page:

Absolute positioning – Anchors the top left corner of an item to a particular location on the page, using an x-y coordinate. For example, you might place an item 10 pixels in from the left margin, and 10 pixels down from the top of the page.
Relative positioning – Places items on the page in relation to one another. For example, it might place one item under another.
Offset positioning – Allows you to place an item on the page relative to another item, and then move it a set amount. For example, you might place an item under another, and then move it 10 pixels to the right.

Itemlocation also provides two ways to set the size for an item:

Relative positioning – Allows you set the size of an item relative to another item on the page. For example, you might expand an item so that it's right edge lines up with the right edge of a different item.
Extent sizing – Allows you to set the absolute size of an item, to the pixels. For example, you might set an item to be 100 pixels wide and 30 pixels tall.

Note: You can also combine these methods for positioning and sizing. For example, you might place an item on the form using absolute positioning, and then place a second item under the first using relative positioning.

Syntax

   <itemlocation>
      settings
   </itemlocation>

Table 1. itemlocation parameters
Parameter	Type	Description
settings	(see the following)	The setting describes where to position the item and how to size it. This can take four forms: absolute positioning, relative positioning, offset positioning, and extent sizing.

Available in

box, button, check, checkgroup, field, label, line, list, popup, combobox, radio, radiogroup, richtext, slider, spacer.

Absolute positioning

Absolute positioning places the item at a specific x-y coordinate on the page. This location is measured from the top left corner of the page to the top left corner of the item, and is expressed in pixels. When using absolute positioning, the syntax is:

   <itemlocation>
      <x>x-coordinate</x>
      <y>y-coordinate</y>
   </itemlocation>

Table 2. absolute positioning parameters
Parameter	Type	Description
x-coordinate	short (must be positive)	The horizontal distance in pixels from the form's top left corner. If the item is parented under a container item using the Left-To-Right orientation, x suboption defines the offset of the item's leftmost edge from the container's leftmost edge. If the item is parented under a container item using the Right-To-Left orientation, x suboption defines the offset of the kid's rightmost edge from the container's rightmost edge.
y-coordinate	short (must be positive)	The vertical distance in pixels from the form's top left corner.

Example

This sample places a label on the page so that its top left corner is 20 pixels in from the page's left edge, and 30 pixels down from the top of the page.

   <label sid="persInfo_label">
      <value>Personal Information</value>
      <itemlocation>
         <x>20</x>
         <y>30</y>
      </itemlocation>
   </label>

Relative positioning

Relative positioning allows an item to be placed relative to the location of another item. It also allows for the specification of an item's size relative to the size and location of other items. The other items (called reference points or anchor items) must be defined earlier in the XFDL form description before they can be used in an itemlocation statement.

When using the relative positioning scheme, the first external item placed on the form appears in the top left corner. It cannot be placed in relation to any other item, since no other items exist. All subsequent items can be placed in relation to items that appear before them in the form's description. If no relational position for an item is specified, it will appear under the previous item, with its left edge against the page's left edge.

When using relative positioning, the syntax is:

   <itemlocation>
      <modifier>item reference</modifier>
   </itemlocation>
or
   <itemlocation>
      <modifier>
         <itemref>item reference</itemref>
         <itemref>item reference</itemref>
      </modifier>
   </itemlocation>

Note: The second syntax is used when an item is positioned between two other items.

Table 3. relative positioning parameters
Parameter	Type	Description
modifier	(see the following)	Determines where in relation to the reference point the item is placed. For example, you can specify that the item goes "under" the reference item.
item reference	string	Identifies the reference point item. This item must be on the same page, or within the same toolbar, as the item you are placing.

Modifiers

There are three types of modifiers:

position modifiers – Used to position an item
alignment modifiers – Used to align one edge of an item (relative positioning only)
expansion modifiers – Used to alter an item's size (relative positioning only)

Position Modifiers:

above: Places item a small distance above reference point item; aligns left edges.
after: Within a ltr (Left-To-Right) orientation, places item a small distance right of the reference point item; aligns top edges.; Within a rtl (Right-To-Left) orientation, places item a small distance left of the reference point item; aligns top edges.
before: Within a ltr (Left-To-Right) orientation, places the item a small distance left of the reference point item; aligns top edges; Within a rtl (Right-To-Left) orientation, places the item a small distance right of the reference point item; aligns top edges
under: Places item a small distance under reference point item; aligns left edges.
within: Options defined within a page or item can override global settings for that particular page or item.

Alignment Modifiers:

alignb2b: Aligns bottom edge of item with bottom edge of reference point item.
alignb2c: Aligns bottom edge of item with vertical center of reference point item.
alignb2t: Aligns bottom edge of item with top edge of reference point item.
alignc2b: Aligns vertical center of item with bottom edge of reference point item.
alignc2l: Within a ltr (Left-To-Right) orientation, aligns horizontal center of item with left edge of reference point item.; Within a rtl (Right-To-Left) orientation, aligns horizontal center of item with right edge of reference point item.
alignc2r: Within a ltr (Left-To-Right) orientation, aligns horizontal center of item with right edge of reference point item.; Within a rtl (Right-To-Left) orientation, aligns horizontal center of item with left edge of reference point item.
alignc2t: Aligns vertical center of item with top edge of reference point item.
alignhoriz between: Aligns horizontal center of item between right edge of first reference point item and left edge of second reference point item.
alignhorizc2c: Aligns horizontal center of item with horizontal center of reference point item; center under. Note that this modifier requires two reference points.
alignl2c: Within a ltr (Left-To-Right) orientation, aligns left edge of item with horizontal center of reference point item.; Within a rtl (Right-To-Left) orientation, aligns right edge of item with horizontal center of reference point item.
alignl2l: Within a ltr (Left-To-Right) orientation, aligns left edge of item with left edge of reference point item.; Within a rtl (Right-To-Left) orientation, aligns right edge of item with right edge of reference point item.
alignl2r: Within a ltr (Left-To-Right) orientation, aligns left edge of item with right edge of reference point item.; Within a rtl (Right-To-Left) orientation, aligns right edge of item with left edge of reference point item.
alignr2c: Within a ltr (Left-To-Right) orientation, aligns right edge of item with horizontal center of reference point item.; Within a rtl (Right-To-Left) orientation, aligns left edge of item with horizontal center of reference point item.
alignr2l: Within a ltr( Left-To-Right) orientation, aligns right edge of item with left edge of reference point item.; Within a rtl (Right-To-Left) orientation, aligns left edge of item with right edge of reference point item.
alignr2r: Within a ltr (Left-To-Right) orientation, aligns right edge of item with right edge of reference point item.; Within a rtl (Right-To-Left) orientation, aligns left edge of item with left edge of reference point item.
alignt2b: Aligns top edge of item with bottom edge of reference point item.
alignt2c: Aligns top edge of item with vertical center of reference point item.
alignt2t: Aligns top edge of item with top edge of reference point item.
alignvertbetween: Aligns vertical center of item between bottom edge of first reference point item and top edge of second reference point item. Note that this modifier requires two reference points.
alignvertc2c: Aligns vertical center of item with vertical center of reference point item.

Expansion Modifiers:

expandb2b: Holds top edge of item constant and expands bottom edge to align with bottom edge of reference point item.
expandb2c: Holds top edge of item constant and expands bottom edge to align with vertical center of reference point item.
expandb2t: Holds top edge of item constant and expands bottom edge to align with top edge of reference point item.
expandl2c: Within a ltr (Left-To-Right) orientation, holds right edge of item constant and expands left edge to align with horizontal center of reference point item.; Within a rtl (Right-To-Left) orientation, holds left edge of item constant and expands right edge to align with horizontal center of reference point item.
expandl2l: Within a ltr (Left-To-Right) orientation, holds right edge of item constant and expands left edge to align with left edge of reference point item.; Within a rtl (Right-To-Left) orientation, holds left edge of item constant and expands right edge to align with right edge of reference point item.
expandl2r: Within a ltr (Left-To-Right) orientation, holds right edge of item constant and expands left edge to align with right edge of reference point item.; Within a rtl (Right-To-Left) orientation, holds left edge of item constant and expands right edge to align with left edge of reference point item.
expandr2c: Within a ltr (Left-To-Right) orientation, holds left edge of item constant and expands right edge to align with horizontal center of reference point item.; Within a rtl (Right-To-Left) orientation, holds right edge of item constant and expands left edge to align with horizontal center of reference point item.
expandr2l: Within a ltr (Left-To-Right) orientation, holds left edge of item constant and expands right edge to align with left edge of reference point item.; Within a rtl (Right-To-Left) orientation, holds right edge of item constant and expands left edge to align with right edge of reference point item.
expandr2r: Holds left edge of item constant and expands right edge to align with right edge of reference point item.
expandt2b: Holds bottom edge of item constant and expands top edge to align with bottom edge of reference point item.
expandt2c: Holds bottom edge of item constant and expands top edge to align with vertical center of reference point item.
expandt2t: Holds bottom edge of item constant and expands top edge to align with top edge of reference point item.
expandheight: Resizes the height of an item by a specified number of pixels.
expandwidth: Resizes the width of an item by a specified number of pixels.

Examples

This sample aligns the vertical center of an item between the bottom edge of the item label_one and the top edge of the item label_two.

   <itemlocation>
      <alignvertbetween>
         <itemref>label_one</itemref>
         <itemref>label_two</itemref>
      </alignvertbetween>
   </itemlocation>

This sample aligns the item's left edge with the center of item the_firm and expands the right edge to align with the right edge of the same reference item (the_firm).

   <itemlocation>
      <alignl2c>the_firm</alignl2c>
      <expandr2r>the_firm</expandr2r>
   </itemlocation>

This sample assigns an item to the toolbar main_toolbar and positions it under the company logo company_logo.

   <itemlocation>
      <within>main_toolbar</within>
      <under>company_logo</under>
   </itemlocation>

Offset positioning

The relative positioning scheme also allows an item to be offset from its original position, by a particular number of pixels. This is a quick way to create an indented layout on a form. You can offset an item in any of these four directions: right, left, up, down. The offset is expressed as an x and y value, and follows the relative positioning statement, as shown:

   <itemlocation>
      relative positioning
      <offsetx>x-offset</offsetx>
      <offsety>y-offset</offsety>
   </itemlocation>

Table 4. off-set positioning parameters
Parameter	Type	Description
relative positioning	(see previous)	Sets the position of the item relative to one or more items on the form.
x-offset	integer	The number of pixels to move the item along the x axis. When ltr (Left-To-Right) orientation is used, a positive number moves the item to the right, and a negative number moves the item to the left. When rtl (Right-To-Left) orientation is used, a positive number moves the item to the left and a negative number moves the item to the right.
y-offset	integer	The number of pixels to move the item along the y axis. A positive number moves the item down, a negative number moves the item up.

Example

This sample places an item under a label called persInfo_label, and then uses offset to move the item 15 pixels to the left and 20 pixels down:

   <itemlocation>
      <under>persInfo_label</under>
      <offsetx>-15</offsetx>
      <offsety>20</offsety>
   </itemlocation>

In the following sample we wanted to add a line under a field with a grey border without leaving any extra padding. The line is positioned under the field and expanded right to right.

By default, the relative under placement causes the line to be positioned 5 pixels under the field. The offsety is used to bring it up 2 pixels. This places it against the bottom of the grey border, but the line also starts 3 pixels to the left of the text in the field. To line it up with the grey border, so that there is only 1 pixel of padding to the left of the field, we set offsetx to 2 pixels. This moves the left edge over 2 pixels. However, the right edge also moves over 2 pixels, so it is now 4 pixels past the grey border on the right (2 pixels for the movement, and 2 pixels for the automatic padding to the right of the field). To fix this we adjust the length by setting the expandwidth option to -4 to shrink the line by the 4 pixels.

An image illustrating where pixels are removed.

     <field sid="FIELD1">
         <itemlocation>
            <x>85</x>
            <y>86</y>
         </itemlocation>
         <scrollhoriz>wordwrap</scrollhoriz>
         <value></value>
         <bgcolor>200,200,200</bgcolor>
         <border>off</border>
      </field>
      <line sid="LINE1">
         <itemlocation>
            <under>FIELD1</under>
            <expandr2r>FIELD1</expandr2r>
            <offsetx>2</offsetx>
            <offsety>-7</offsety>
            <expandwidth>-4</expandwidth>
         </itemlocation>
      </line>

Extent sizing

Extent sizing provides a different way to set the size of an item, and works in conjunction with either absolute or relative positioning. Unlike the size option, which sets the size of an item in terms of the number of internal characters, you can use extent sizing to set the absolute size of the exterior, or bounding box, of an item. Futhermore, using extent sizing overrides the size option.

Extent sizing sets the size of an item in pixels, using separate values for the width and the height. When an extent is specified, the item's top left corner will stay where it is, and the item will be resized so that it is as many pixels wide as the width value and as many pixels tall as the height value.

Extent sizing uses the following syntax:

   <itemlocation>
      positioning
      <width>width</width>
      <height>height</height>
   </itemlocation>

Table 5. extent sizing parameters
Parameter	Type	Description
positioning	(see previous)	Sets the position of the item on the form. This can be either absolute or relative positioning.
width	integer	The width of the item, in pixels.
height	integer	The height of the item, in pixels.

Example

This sample shows an extent setting on a field that has been placed using absolute positioning. The field is first placed at an x-y coordinate of 10, 10. It is then sized to be 300 pixels wide and 30 pixels high.

   <itemlocation>
      <x>10</x>
      <y>10</y>
      <width>300</width>
      <height>30</height>
   </itemlocation>

Usage details

Default item location:
- in the body of the page
- under the previous item in the page definition
- aligned along the left margin of the page
Itemlocation overrides size. If the itemlocation affects the size of the item (using extent sizing) and the size option has also been set for the item, the itemlocation will determine the size.
There are two measurements for sizing items when using absolute positioning: in pixels (using extent sizing) or in characters (using the size option). If you choose to size items using characters, you should be aware that different platforms and video cards use differently sized fonts. Even with so-called cross-platform fonts, an item's actual size (in pixels) might change from one platform to the next if it is sized using character height and width. As a result, absolutely positioned items sized with characters may have overlap sizing problems if displayed on different platforms, different video cards, or in both small font and large font modes. To ensure that forms appear the same on any platform, and under any video card or font mode while using absolute positioning, size items in pixels or inches.
An item's vertical center is halfway between the top and bottom edges. The horizontal center is halfway between the left and right edges.
expandheight, the expandwidth allows you to resize items more precisely. This is particularly useful for re-sizing lines that are used to separate table rows and columns.
itemlocation overrides layoutflow. Delete itemlocation coordinate values to control the flow of items.
The orientation option affects the X coordinate.