This field returns the surface's horizontal position relative to the top-level surface in its local hierarchy.

Writing AbsX moves the surface so that its absolute horizontal position matches the supplied value. The surface must be initialised before this field can be changed.

This field returns the surface's vertical position relative to the top-level surface in its local hierarchy.

Writing AbsY moves the surface so that its absolute vertical position matches the supplied value. The surface must be initialised before this field can be changed.

Set BitsPerPixel before initialisation to request a fixed pixel depth for the surface buffer. If the requested depth differs from the display or parent buffer, the graphics system converts pixels when the surface is drawn, which is usually slower than using the native display depth.

Reading this field returns the active tracked depth for the surface. A value of zero is returned if the surface is not available in the display surface list.

Each surface is assigned a bitmap buffer for drawing. In many cases this buffer is shared between multiple surfaces, so clients should treat it as an implementation detail unless no public drawing API provides the required access.

The bitmap is an off-screen buffer. Direct changes to it are not exposed to the display automatically.

Set this field when a surface should be cleared to a solid background colour before drawing. String values may use #RRGGBB hexadecimal notation or Red,Green,Blue decimal components.

A surface that does not define a colour is not cleared during redraw. In that case, draw the full background manually to avoid stale or uninitialised graphics appearing in exposed areas.

A preset colour can be disabled by writing NULL, which clears the colour by setting its alpha component to zero. Changing Colour does not schedule a redraw.

The pointer automatically switches to the selected 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 a valid cursor name or cursor ID.

All surfaces belong to a Display object that manages drawing to the user's video display. This field identifies the display that owns the surface.

Set this field to the Surface that should move when the user starts a click-drag operation over the current surface. For example, a window title bar would set Drag to the window surface. A surface may also set Drag to itself for icon-like or small draggable objects.

Set Drag to zero to disable drag handling.

Read this field to determine whether the surface is idle, anchored for dragging or actively being moved.

Use Flags to enable optional surface behaviours. Preserve existing flags when updating this field, typically by combining the current value with the flags being added.

Read-only flags cannot be changed by writing this field. Initialisation-only flags can be set before the surface is initialised, but are preserved once the surface is active.

Set Height to change the surface height. Alternatively, call Resize() to change Width and Height together.

By default the value is a fixed coordinate unit. With the FD_SCALED flag, the value is treated as a multiplier of the parent surface height.

A plain read returns the height resolved to a fixed pixel count, even when Height was defined as a scaled value. Request the value with the FD_SCALED flag to retrieve it as a multiplier of the parent height instead. Reading the field verbatim (with FD_PURE), or before initialisation, returns the value exactly as it was last defined.

Changing Height on a visible surface updates the displayed area immediately, including any child surfaces that need to be redrawn or resized.

Before initialisation, setting Height to zero or less clears the height dimension so that Y and YOffset can define the height dynamically. After initialisation, values of zero or less are invalid.

Set MaxHeight to limit the maximum height that can be applied through resizing. Resize() cannot increase the surface beyond this value.

Direct writes to Height bypass this limit.

Set MaxWidth to limit the maximum width that can be applied through resizing. Resize() cannot increase the surface beyond this value.

Direct writes to Width bypass this limit.

Set MinHeight to limit the minimum height that can be applied through resizing. Resize() cannot shrink the surface below this value.

Direct writes to Height bypass this limit. Values less than 1 are clamped to 1.

Set MinWidth to limit the minimum width that can be applied through resizing. Resize() cannot shrink the surface below this value.

Direct writes to Width bypass this limit. Values less than 1 are clamped to 1.

If set to true, the surface becomes the program's modal surface when shown. This prevents interaction with other surfaces until the modal surface is hidden, destroyed or no longer modal. Children of the modal surface remain interactive.

Clearing this field restores the previous modal surface if one was recorded.

Opacity is expressed as a normalised multiplier. The default value of 1.0 draws the surface as fully opaque. Lower values make the surface more transparent. Values outside the allowable range are clipped.

Non-opaque surfaces are drawn by rendering the surface content to its internal buffer and blending it with the background graphics. This can be costly, and the pre-copy feature may give better results for some compositions.

Translucency can significantly increase CPU usage.

Child surfaces use this field to identify their parent. Top-level surfaces have no parent.

If Parent is not set before initialisation, the surface class searches the ownership chain for the nearest Surface. Set Parent to zero before initialisation to disable that automatic lookup. An initialised child surface may be reparented, but a top-level surface cannot be converted into a child surface after initialisation.

Set PopOver before initialisation to the object ID of a sibling Surface that this surface should stay in front of. For dialog windows, combine this field with Modal to keep the dialog in front and prevent interaction with other surfaces in the current program.

Set PopOver to zero before initialisation to use normal Z-order behaviour.

This field cannot be changed after initialisation. The value must identify a Surface; otherwise ERR::InvalidObject is returned.

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

Read this field to determine whether the surface itself is marked visible. A true value means the surface is shown; false means it is hidden.

Effective on-screen visibility also depends on the parent chain. A visible child of a hidden parent is not displayed.

Set this field, or call Hide() and Show(), to change the surface visibility.

Set Width to change the surface width. Alternatively, call Resize() to change Width and Height together.

By default the value is a fixed coordinate unit. With the FD_SCALED flag, the value is treated as a multiplier of the parent surface width.

A plain read returns the width resolved to a fixed pixel count, even when Width was defined as a scaled value. Request the value with the FD_SCALED flag to retrieve it as a multiplier of the parent width instead. Reading the field verbatim (with FD_PURE), or before initialisation, returns the value exactly as it was last defined.

Changing Width on a visible surface updates the displayed area immediately, including any child surfaces that need to be redrawn or resized.

Before initialisation, setting Width to zero or less clears the width dimension so that X and XOffset can define the width dynamically. After initialisation, values of zero or less are invalid.

This field exposes the host window handle for platforms that provide one. It is currently relevant when creating a primary surface within an X11 window manager or Microsoft Windows.

Set WindowHandle before initialisation to attach the surface to an existing native window. The field is immutable after initialisation.

This field affects hosted desktops such as Windows and X11. It only applies to top-level surfaces that have no parent. Child surfaces ignore this field, and surfaces created inside the desktop area treat the desktop as their parent.

Custom surfaces remain responsible for their own window controls, such as title bars and resize borders.

Set X to change the horizontal position of the surface relative to its parent.

By default the value is a fixed coordinate unit. With the FD_SCALED flag, the value is treated as a multiplier of the parent surface width.

A plain read returns the horizontal position resolved to a fixed pixel coordinate relative to the parent, even when X was defined as a scaled value. Request the value with the FD_SCALED flag to retrieve it as a multiplier of the parent width instead. Reading the field verbatim (with FD_PURE), or before initialisation, returns the value exactly as it was last defined. Read AbsX for the absolute horizontal pixel position within the surface hierarchy.

Changing X on a visible surface updates its position immediately. If XOffset also defines the right-hand edge, the surface width is recalculated to preserve that offset.

XOffset defines a distance from the right-hand edge of the parent surface.

When X is set and Width is not set, XOffset makes the surface width dynamic. The width extends from X to the parent width minus XOffset.

When Width is set, XOffset positions the surface from the parent right-hand edge: X = ParentWidth - Width - XOffset.

A plain read returns the offset resolved to a fixed pixel distance, even when the offset was defined as a scaled value. If no offset has been defined but both X and Width are present, the offset is derived from the parent width. Request the value with the FD_SCALED flag to retrieve it as a multiplier of the surface width. Reading the field verbatim (with FD_PURE), or before initialisation, returns the value exactly as it was last defined.

Set Y to change the vertical position of the surface relative to its parent.

By default the value is a fixed coordinate unit. With the FD_SCALED flag, the value is treated as a multiplier of the parent surface height.

A plain read returns the vertical position resolved to a fixed pixel coordinate relative to the parent, even when Y was defined as a scaled value. Request the value with the FD_SCALED flag to retrieve it as a multiplier of the parent height instead. Reading the field verbatim (with FD_PURE), or before initialisation, returns the value exactly as it was last defined. Read AbsY for the absolute vertical pixel position within the surface hierarchy.

Changing Y on a visible surface updates its position immediately.

YOffset defines a distance from the bottom edge of the parent surface.

When Y is set and Height is not set, YOffset makes the surface height dynamic. The height extends from Y to the parent height minus YOffset.

When Height is set, YOffset positions the surface from the parent bottom edge: Y = ParentHeight - Height - YOffset.

A plain read returns the offset resolved to a fixed pixel distance, even when the offset was defined as a scaled value. If no offset has been defined but both Y and Height are present, the offset is derived from the parent height. Request the value with the FD_SCALED flag to retrieve it as a multiplier of the surface height. Reading the field verbatim (with FD_PURE), or before initialisation, returns the value exactly as it was last defined.