SetToolbarPos

Sets the position of the specified toolbar.

To set

Use

Docking position of a docked toolbar

Syntax 1

Coordinates and size of a floating toolbar

Syntax 2


Syntax 1: For docked toolbars

Description

Sets the position of a docked toolbar.

Applies to

MDI frame and sheet windows

Syntax

window.SetToolbarPos ( toolbarindex, dockrow, offset, insert )

Argument

Description

window

The MDI frame or sheet to which the toolbar belongs.

toolbarindex

An integer whose value is the index of the toolbar whose settings you want to change.

dockrow

An integer whose value is the number of the docking row for the toolbar. Docking rows are numbered from left to right or top to bottom.

offset

An integer whose value specifies the distance of the toolbar from the beginning of the docking row. For toolbars at the top or bottom, offset is measured from the left edge. For toolbars on the left or right, offset is measured from the top.

If insert is true, the offset you specify is adjusted so that the toolbar does not overlap others in the row.

Specify an offset of 0 to position the toolbar ahead of other toolbars in dockrow.

insert

A boolean value specifying whether you want to insert the specified toolbar before the toolbars in dockrow causing them to move over or down a row, or you want to add toolbarindex to dockrow. Values are:

  • TRUE -- Move any toolbars already in dockrow or higher rows over or down a row so that the toolbar you are moving is the only toolbar in the row.

  • FALSE -- Add the toolbar you are moving to dockrow. Its position in relation to other toolbars in the row is determined by offset.


Return value

Integer.

Returns 1 if it succeeds. SetToolbarPos returns -1 if there is no toolbar for the index you specify or if an error occurs. If any argument's value is null, returns null.

Usage

To find out whether the docked toolbar is at the top, bottom, left, or right edge of the window, call GetToolbar.

If the toolbar's alignment is floating, instead of docked, then values you specify with Syntax 1 of SetToolbarPos take effect when you change the alignment to a docked position with SetToolbar.

When insert is false, to move the toolbar before other toolbars in dockrow, specify a value that is less than the offset for the existing toolbars. If there is already a toolbar at offset 1, then you can move the toolbar to the beginning of the row by setting offset to 0. If offset is equal to or greater than the offset of existing toolbars, but less than their end, the newly positioned toolbar will begin just after the existing one. Otherwise, the toolbar will be positioned at offset.

If the user drags the toolbar to a docked position, the new row and offset replace values set with SetToolbarPos.

Examples

This example docks toolbar 1 at the left, adding it to docking row 1:

w_frame.SetToolbar(1, TRUE, AlignAtLeft!)
w_frame.SetToolbarPos(1, 1, 1, FALSE)

This example docks toolbar 2 at the left, adding it to docking row 1. If the toolbars already in the dock extend past offset 250, then the offset of toolbar 2 is increased to accommodate them. Otherwise, it is positioned at offset 250:

w_frame.SetToolbar(2, TRUE, AlignAtLeft!)
w_frame.SetToolbarPos(2, 1, 250, FALSE)

This example docks toolbar 2 at the left in docking row 2. Any toolbar docked on the left in row 2 or higher is moved over a row:

w_frame.SetToolbar(1, TRUE, AlignAtLeft!)
w_frame.SetToolbarPos(1, 2, 1, TRUE)

See also

GetToolbar

GetToolbarPos

SetToolbar

Syntax 2: For floating toolbars

Description

Sets the position and size of a floating toolbar.

Applies to

MDI frame and sheet windows

Syntax

window.SetToolbarPos ( toolbarindex, x, y, width, height )

Argument

Description

window

The MDI frame or sheet to which the toolbar belongs

toolbarindex

An integer whose value is the index of the toolbar whose settings you want to change

x

An integer whose value is the x coordinate of the floating toolbar

y

An integer whose value is the y coordinate of the floating toolbar

width

An integer whose value is the width of the floating toolbar

height

An integer whose value is the height of the floating toolbar


Return value

Integer.

Returns 1 if it succeeds. SetToolbarPos returns -1 if there is no toolbar for the index you specify or if an error occurs. If any argument's value is null, SetToolbarPos returns null.

Usage

If the toolbar's alignment is a docked position, instead of floating, then values you specify with Syntax 2 of SetToolbarPos take effect when you change the alignment to floating in a script with SetToolbar.

If the user drags the toolbar to a floating position, the new position values replace values set with SetToolbarPos.

The floating toolbar is never too large or too small for the buttons. If you specify width and height values that are too small to accommodate the buttons, the width and height are adjusted to make room for the buttons. If both width and height are larger than needed, the height is reduced.

If you specify x and y coordinates that are outside the frame, the toolbar becomes inaccessible to the user.

Examples

This example displays toolbar 1 near the upper-left corner of the frame. An arbitrary width and height lets PowerBuilder size the toolbar as needed:

w_frame.SetToolbarPos(1, 10, 10, 400, 1)
w_frame.SetToolbar(1, TRUE, Floating!)

This example displays toolbar 2 close to the lower-right corner of the frame. GetToolbarPos gets the current width and height of the toolbar so that the toolbar stays the same size:

integer ix, iy, iw, ih
 
w_frame.GetToolbarPos(2, ix, iy, iw, ih)
 
w_frame.SetToolbarPos(2, &
      w_frame.WorkspaceWidth()-400, &
         w_frame.WorkspaceHeight()-400, &
            iw, ih)
w_frame.SetToolbar(2, TRUE, Floating!)

This example positions floating toolbar 2 just inside the lower-right corner of the MDI frame. GetToolbarPos gets the current width and height of the toolbar. These values and the height of the MicroHelp are used to calculate the x and y coordinates for the floating toolbar:

integer ix, iy, iw, ih
 
// Find out toolbar size
w_frame.GetToolbarPos(2, ix, iy, iw, ih)
 
// Set the position, taking the size into account
w_frame.SetToolbarPos(2, &
      w_frame.WorkspaceWidth( ) - iw, &
         w_frame.WorkspaceHeight( ) &
            - ih - w_frame.MDI_1.MicroHelpHeight, &
               iw, ih)
 
// Set the alignment to floating
w_frame.SetToolbar(2, TRUE, Floating!)

See also

GetToolbar

SetToolbar

SetToolbarPos