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

Move an object in a DataWindow to another band or to specify its front-to-back position within a band

Syntax 2


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!.


Return value

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

This statement positions cb_two on top:

cb_two.SetPosition(ToTop!)

This statement positions cb_two behind cb_three:

cb_two.SetPosition(Behind!, cb_three)

This statement makes the window w_signon the topmost window:

w_signon.SetPosition(TopMost!)

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


Return value

Integer.

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

Examples

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

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

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

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

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

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