This field returns the absolute horizontal position of a surface object. The absolute value is calculated based on the surface object's position relative to the top most surface object in the local hierarchy.

It is possible to set this field, but only after initialisation of the surface object has occurred.

This field returns the absolute vertical position of a surface object. The absolute value is calculated based on the surface object's position relative to the top most surface object in the local hierarchy.

It is possible to set this field, but only after initialisation of the surface object has occurred.

If you would like to set an abstract position for a surface area, you can give it an alignment. This feature is most commonly used for horizontal and vertical centring, as aligning to the the edges of a surface area is already handled by existing dimension fields. Note that setting the alignment overrides any settings in related coordinate fields. Valid alignment flags are BOTTOM, CENTER/MIDDLE, LEFT, HORIZONTAL, RIGHT, TOP, VERTICAL.

The BitsPerPixel field may be set prior to initialisation in order to force a particular bits-per-pixel setting that may not match the display. This will result in the graphics system converting each pixel when drawing the surface to the display and as such is not recommended.

A client can prevent a surface object from moving beyond a given point at the bottom of its container by setting this field. If for example you were to set the BottomLimit to 5, then any attempt to move the surface object into or beyond the 5 units at the bottom of its container would fail.

Limits only apply to movement, as induced through the Move() action. This means that limits can be over-ridden by setting the coordinate fields directly (which can be useful in certain cases).

The Surface class supports margin settings, which are similar to the concept of margins on printed paper. Margin values have no significant meaning or effect on a surface object itself, but they are often used by other objects and can be helpful in interface construction. For instance, the Window script uses margins to indicate the space available for placing graphics and other surface objects inside of it.

By default, all margins are set to zero when a new surface object is created.

Each surface is assigned a bitmap buffer that is referred to in this field. In many cases the bitmap will be shared between multiple surfaces. A client should avoid interacting with the buffer unless circumstances are such that there are no other means to get access to internal graphics information.

Please note that the bitmap object represents an off-screen, temporary buffer. Drawing to the bitmap directly will have no impact on the display.

If the surface object should have a plain background colour, set this field to the colour value that you want to use. The colour must be specified in the standard format of #RRGGBB for hexadecimal or Red,Green,Blue for decimal components.

Surface objects that do not have a colour will not be cleared when being drawn. The background will thus consist of 'junk' graphics and the background will need to be drawn using another method. This gives your the power to choose the fastest drawing model to suit your needs.

If you set the Colour and later want to turn the background colour off, write a NULL value to the Colour field or set the Alpha component to zero. Changing the Colour field does not cause a graphics redraw.

The Cursor field provides a convenient way of setting the pointer's cursor image in a single operation. The mouse pointer will automatically switch to the specified cursor image when it enters the surface area.

The available cursor image settings are listed in the Pointer⇒CursorID documentation.

The Cursor field may be written with valid cursor names or their ID's, as you prefer.

The dimension settings of a surface object can be read from this field. The flags indicate the dimension fields that are in use, and whether the values are fixed or relative.

It is strongly recommended that this field is never set manually, because the flags are automatically managed for the client when setting fields such as X and Width. If circumstances require manual configuration, take care to ensure that the flags do not conflict. For instance, FIXED_X and SCALED_X cannot be paired, nor could FIXED_X, FIXED_XOFFSET and FIXED_WIDTH simultaneously.

All surfaces belong to a Display object that manages drawing to the user's video display. This field refers to the Display object of which the surface is a member.

Click-dragging of surfaces is enabled by utilising the Drag field.

To use, write this field with reference to a Surface that is to be dragged when the user starts a click-drag operation. For instance, if you create a window with a title-bar at the top, you would set the Drag field of the title-bar to point to the object ID of the window. If necessary, you can set the Drag field to point back to your surface object (this can be useful for creating icons and other small widgets).

To turn off dragging, set the field to zero.

If the surface is draggable, the DragStatus indicates the current state of the surface with respect to it being dragged.

The Flags field allows special options to be set for a surface object. Use a logical-OR operation when setting this field so that existing flags are not overwritten. To not do so can produce unexpected behaviour.

The height of a surface object is manipulated through this field. Alternatively, use the Resize() action to adjust the Width and Height at the same time. A client can set the Height as a fixed value by default, or as a scaled value in conjunction with the FD_SCALED flag. Scaled values are multiplied by the height of their parent container.

Setting the Height while a surface object is on display causes an immediate graphical update to reflect the change. Any objects that are within the surface area will be re-drawn and resized as necessary.

If a value less than zero is passed to an initialised surface, the height will be 'turned off' - this is convenient for pairing the Y and YOffset fields together for dynamic height adjustment.

A client can determine the internal height of a surface object by reading the InsideHeight field. The returned value is the result of calculating this formula: Height - TopMargin - BottomMargin.

If the TopMargin and BottomMargin fields are not set, the returned value will be equal to the surface object's height.

A client can determine the internal width of a surface object by reading the InsideWidth field. The returned value is the result of calculating this formula: Width - LeftMargin - RightMargin.

If the LeftMargin and RightMargin fields are not set, the returned value will be equal to the surface object's width.

A client can prevent a surface object from moving beyond a given point at the left-hand side of its container by setting this field. If for example you were to set the LeftLimit to 3, then any attempt to move the surface object into or beyond the 3 units at the left of its container would fail.

Limits only apply to movement, as induced through the Move() action. This means it is possible to override limits by setting the coordinate fields directly.

The Surface class supports margin settings, which are similar to the concept of margins on printed paper. Margin values have no significant meaning or effect on a surface object itself, but they are often used by other objects and can be helpful in interface construction. For instance, the Window template uses margins to indicate the space available for placing graphics and other surface objects inside of it.

By default, all margins are set to zero when a new surface object is created.

A client can limit the maximum height of a surface object by setting this field. Limiting the height affects resizing, making it impossible to use the Resize() action to extend beyond the height you specify.

It is possible to circumvent the MaxHeight by setting the Height field directly. Note that the MaxHeight value refers to the inside-height of the surface area, thus the overall maximum height will include both the TopMargin and BottomMargin values.

A client can limit the maximum width of a surface object by setting this field. Limiting the width affects resizing, making it impossible to use the Resize() action to extend beyond the width you specify.

It is possible to circumvent the MaxWidth by setting the Width field directly. Note that the MaxWidth value refers to the inside-width of the surface area, thus the overall maximum width will include both the LeftMargin and RightMargin values.

A client can prevent the height of a surface object from shrinking too far by setting this field. This feature specifically affects resizing, making it impossible to use the Resize() action to shrink the height of a surface object to a value less than the one you specify.

It is possible to circumvent the MinHeight by setting the Height field directly.

A client can prevent the width of a surface object from shrinking too far by setting this field. This feature specifically affects resizing, making it impossible to use the Resize() action to shrink the width of a surface object to a value less than the one you specify.

It is possible to circumvent the MinWidth by setting the Width field directly.

If true, the surface will become the modal surface for the program when it is shown. This prevents interaction with other surfaces until the modal surface is either hidden or destroyed. Children of the modal surface may be interacted with normally.

The directions in which a surface object can move can be limited by setting the Movement field. By default, a surface object is capable of moving both horizontally and vertically.

This field is only effective in relation to the Move action, and it is possible to circumvent the restrictions by setting the coordinate fields directly.

This field determines the translucency level of a surface area. The default setting is 100%, which means that the surface will be solid. Any other value that you set here will alter the impact of a surface over its destination area. High values will retain the boldness of the graphics, while low values can surface it close to invisible.

Note: The translucent drawing routine works by drawing the surface content to its internal buffer first, then copying the graphics that are immediately in the background straight over the top with an alpha-blending routine. This is not always ideal and better results might be obtainable with the pre-copy feature.

Please note that the use of translucency is realised at a significant cost to CPU usage.

The parent for child surfaces is defined here. Top level surfaces will have no parent. If the Parent field is not set prior to initialisation, the surface class will attempt to discover a valid parent by checking its ownership chain for a surface object. This behaviour can be switched off by setting a Parent of zero prior to initialisation.

Setting the PopOver field to a sibling surface ID will keep the surface in front of its sibling at all times. For dialog windows, it is recommended that the popover and modal options be combined together to prevent interaction with other surfaces created by the current program.

Setting the PopOver field to zero will return the surface to its normal state.

If an object that does not belong to the Surface class is detected, an attempt will be made to read that object's Surface field, if available. If this does not yield a valid surface then ERR::InvalidObject is returned.

A client can prevent a surface object from moving beyond a given point at the right-hand side of its container by setting this field. If for example you were to set the RightLimit to 8, then any attempt to move the surface object into or beyond the 8 units at the right-hand side of its container would fail.

Limits only apply to movement, as induced through the Move() action. This means that limits can be over-ridden by setting the coordinate fields directly (which can be useful in certain cases).

The Surface class supports margin settings, which are similar to the concept of margins on printed paper. Margin values have no significant meaning or effect on a surface object itself, but they are often used by other objects and can be helpful in interface construction. For instance, the Window template uses margins to indicate the space available for placing graphics and other surface objects inside of it.

By default, all margins are set to zero when a new surface object is created.

A client can prevent a surface object from moving beyond a given point at the top of its container by setting this field. If for example you were to set the TopLimit to 10, then any attempt to move the surface object into or beyond the 10 units at the top of its container would fail.

Limits only apply to movement, as induced through the Move() action. This means that limits can be over-ridden by setting the coordinate fields directly (which can be useful in certain cases).

The Surface class supports margin settings, which are similar to the concept of margins on printed paper. Margin values have no significant meaning or effect on a surface object itself, but they are often used by other objects and can be helpful in interface construction. For instance, the Window template uses margins to indicate the space available for placing graphics and other surface objects inside of it.

By default, all margins are set to zero when a new surface object is created.

Returns the surface object that has the primary user focus. Returns zero if no object has the focus.

If you need to know if a surface object is visible or hidden, you can read this field to find out either way. A true value is returned if the object is visible and false is returned if the object is invisible. Note that visibility is subject to the properties of the container that the surface object resides in. For example, if a surface object is visible but is contained within a surface object that is invisible, the end result is that both objects are actually invisible.

Visibility is directly affected by the Hide() and Show() actions if you wish to change the visibility of a surface object.

To determine the visible area of a surface, read the VisibleX, VisibleY, VisibleWidth and VisibleHeight fields.

The 'visible area' is determined by the position of the surface relative to its parents. For example, if the surface is 100 pixels across and smallest parent is 50 pixels across, the number of pixels visible to the user must be 50 pixels or less, depending on the position of the surface.

If none of the surface area is visible then zero is returned. The result is never negative.

To determine the visible area of a surface, read the VisibleX, VisibleY, VisibleWidth and VisibleHeight fields.

The 'visible area' is determined by the position of the surface relative to its parents. For example, if the surface is 100 pixels across and smallest parent is 50 pixels across, the number of pixels visible to the user must be 50 pixels or less, depending on the position of the surface.

If none of the surface area is visible then zero is returned. The result is never negative.

To determine the visible area of a surface, read the VisibleX, VisibleY, VisibleWidth and VisibleHeight fields.

The 'visible area' is determined by the position of the surface relative to its parents. For example, if the surface is 100 pixels across and smallest parent is 50 pixels across, the number of pixels visible to the user must be 50 pixels or less, depending on the position of the surface.

If none of the surface area is visible then zero is returned. The result is never negative.

To determine the visible area of a surface, read the VisibleX, VisibleY, VisibleWidth and VisibleHeight fields.

The 'visible area' is determined by the position of the surface relative to its parents. For example, if the surface is 100 pixels across and smallest parent is 50 pixels across, the number of pixels visible to the user must be 50 pixels or less, depending on the position of the surface.

If none of the surface area is visible then zero is returned. The result is never negative.

The width of a surface object is manipulated through this field. Alternatively, use the Resize() action to adjust the Width and Height at the same time. A client can set the Width as a fixed value by default, or as a scaled value in conjunction with the FD_SCALED flag. Scaled values are multiplied by the width of their parent container.

Setting the Width while a surface object is on display causes an immediate graphical update to reflect the change. Any objects that are within the surface area will be re-drawn and resized as necessary.

Width values of 0 or less are illegal, and will result in an ERR::OutOfRange error-code.

This field refers to the window handle of a surface object, but only if such a thing is relevant to the platform that the system is running on. Currently, this field is only usable when creating a primary surface object within an X11 window manager or Microsoft Windows.

It is possible to set the WindowHandle field prior to initialisation if you want a surface object to be based on a window that already exists.

This field affects a surface's status on hosted desktops such as Windows and X11. It only affects top-level surfaces that have no parent - child surfaces ignore this field. Surfaces created in the desktop area will also ignore this field, as the desktop is treated as a parent.

It is the responsibility of the developer to provide window gadgets such as titlebars and set the resize borders for custom surfaces.

The horizontal position of a surface object can be set through this field. You have the choice of setting a fixed coordinate (the default) or a scaled coordinate if you use the FD_SCALED flag.

If you set the X while the surface object is on display, the position of the surface area will be updated immediately.

The XOffset has a dual purpose depending on whether or not it is set in conjunction with the X or Width fields.

If set in conjunction with the X field, the width of the surface object will be from that X coordinate up to the width of the container, minus the value given in the XOffset. This means that the width of the surface object is dynamically calculated in relation to the width of its container.

If the XOffset field is set in conjunction with a fixed or scaled width then the surface object will be positioned at an X coordinate calculated from the formula X = ContainerWidth - SurfaceWidth - XOffset.

The vertical position of a surface object can be set through this field. You have the choice of setting a fixed coordinate (the default) or a scaled coordinate if you use the FD_SCALED flag.

If the value is changed while the surface is on display, its position will be updated immediately.

The YOffset has a dual purpose depending on whether or not it is set in conjunction with the Y or Height fields.

If set in conjunction with the Y field, the height of the surface object will be from that Y coordinate up to the height of the container, minus the value given in the YOffset. This means that the height of the surface object is dynamically calculated in relation to the height of its container.

If the YOffset field is set in conjunction with a fixed or scaled height then the surface object will be positioned at a Y coordinate calculated from the formula Y = ContainerHeight - SurfaceHeight - YOffset.