SetPosition

Specifies the front-to-back position of a control in a window, a window, or an object within a DataWindow.

To	Use
Specify the front-to-back position of a control in a window, or specify that a window should always display on top of other windows	Syntax 1 For positioning windows and controls in windows
Move an object in a DataWindow to another band or to specify its front-to-back position within a band	Syntax 2 For positioning objects within a DataWindow

Syntax 1 For positioning windows and controls in windows

Description

For controls in a window, specifies the position of a control in the front-to-back order within a window. For a window, specifies whether it always displays on top of other open windows.

Applies to

A control within a window or a window

Syntax

objectname.SetPosition ( position {, precedingobject } )

Argument	Description
objectname	The name of a control for which you want to specify a location in the front-to-back order within the window, or the name of a window for which you want to specify whether it always displays on top. Objectname cannot be a child window or a sheet.
position	A SetPosType enumerated datatype. The values you can specify depend on whether objectname is a control or a window. For controls, values are: Behind! – Position objectname behind precedingobject in the order ToTop! – Position objectname on top of all other controls ToBottom! – Position objectname behind all other controls For windows, values are: TopMost! – Always display objectname on top of all other open windows NoTopMost! – Do not always display objectname on top of all other open windows
precedingobject (optional)	The name of the object you want to position objectname behind. Precedingobject is required if position is Behind!.

Argument

Description

objectname

The name of a control for which you want to specify a location in the front-to-back order within the window, or the name of a window for which you want to specify whether it always displays on top. Objectname cannot be a child window or a sheet.

position

A SetPosType enumerated datatype. The values you can specify depend on whether objectname is a control or a window.

For controls, values are:

Behind! – Position objectname behind precedingobject in the order
ToTop! – Position objectname on top of all other controls
ToBottom! – Position objectname behind all other controls

For windows, values are:

TopMost! – Always display objectname on top of all other open windows
NoTopMost! – Do not always display objectname on top of all other open windows

precedingobject (optional)

The name of the object you want to position objectname behind. Precedingobject is required if position is Behind!.

Returns

Integer. Returns 1 when it succeeds and -1 if an error occurs. If any argument’s value is null, SetPosition returns null.

Usage

The front-to-back order for controls determines which control covers another when they overlap. If a control completely covers another control, the control that is in back becomes inaccessible to the user.

When you specify TopMost! for more than one window, the most recently executed SetPosition function controls which window displays on top.

Examples

Example 1

This statement positions cb_two on top:

cb_two.SetPosition(ToTop!)

Example 2

This statement positions cb_two behind cb_three:

cb_two.SetPosition(Behind!, cb_three)

Example 3

This statement makes the window w_signon the topmost window:

w_signon.SetPosition(TopMost!)

Example 4

This statement makes the window w_signon no longer necessarily the topmost window:

w_signon.SetPosition(NoTopMost!)

Syntax 2 For positioning objects within a DataWindow

Description

Moves an object within the DataWindow to another band or changes the front-to-back order of objects within a band.

Applies to

DataWindow controls and DataStores

Syntax

dwcontrol.SetPosition ( objectname, band, bringtofront )

Argument	Description
dwcontrol	The name of the DataWindow control or DataStore containing the object.
objectname	The name of the object within the DataWindow that you want to move. You assign names to the DataWindow objects in the DataWindow painter.
band	The name of the band or layer in which you want to position objectname. Layer names are background and foreground. Band names are detail, header, footer, summary, header.#, and trailer.#. # is the group level number. Enter the empty string ("") if you do not want to change the band
bringtofront	A boolean indicating whether you want to bring objectname to the front within the band: TRUE – Bring it to the front FALSE – Do not bring it to the front

Returns

Integer. Returns 1 when it succeeds and -1 if an error occurs. If any argument’s value is null, SetPosition returns null.

Examples

Example 5

This statement moves oval_red in dw_rpt to the header and brings it to the front:

dw_rpt.SetPosition("oval_red", "header", TRUE)

Example 6

This statement does not change the position of oval_red , but does bring it to the front:

dw_rpt.SetPosition("oval_red", "", TRUE)

Example 7

This statement moves oval_red to the footer but does not bring it to the front:

dw_rpt.SetPosition("oval_red", "footer", FALSE)