## position parameter

The position is a parameter that defines the position and the dimensions of an object.

It is used in 2 kind of methods:

§ when creating a DFrame with the 'new' constructor or when creating Bars, Buttons and Menus with the addXXX methods (addBar, addMenu, addButton etc…)

§ with the setPos method which apply to all Styles: DFrameStyle, BarStyle, ButtonStyle and MenuStyle. As all Style methods the setPos method can be used to define a Style or, if apply to an object, to modify the Style of a the object before it is graphically created.

The position parameter can have different data type. All are not valid for all objects but each object can use different types:

### If String:

Authorized values: 'TOP', 'RIGHT', 'BOTTOM' and 'LEFT'

Apply to Bar / BarStyle only

This kind of position is used to easily define the position of a Bar on a DFrame.

Examples:

var bar = dFrame.addBar('TOP')

or

var barStyle = new BarStyle()

barStyle.setPos('TOP')

var bar = dFrame.addBar(barStyle)

or

var bar = dFrame.addBar()

bar.setPos('TOP')

### If Array:

Apply to all objects: DFrame/DFrameStyle, Bar/BarStyle, Menu/MenuStyle and Button/ButtonStyle.

This type of position defines the coordinates and dimension of an object. It is an array of 4 values:

§ The first two values define the coordinates of the left-top corner.

§ The last two values define the coordinates of the right-bottom corner.

The type (numeric of string) of the values of the array are described below.

Examples:

var bar = dFrame.addBar([5, 15, 50, 60])

or

var barStyle = new BarStyle()

barStyle.setPos([5, 15, 50, 60])

var bar = dFrame.addBar(barStyle)

or

var bar = dFrame.addBar()

bar.setPos([5, 15, 50, 60])

The last two values can be omitted for objects having a different way to define the dimensions:

§ Bars and Buttons have the setWidth/Height and setAutoWidth/Height methods that allow to define their width and height attributes.

§ Menus have the setWidth and setAutoWidth methods that allow to define their width attributes and have a height that is always the height of their contents.

Examples:

var bar = dFrame.addBar([5, 15])

bar.setWidth(100)

bar.setHeight(200)

or

var barStyle = new BarStyle()

barStyle.setWidth(100)

barStyle.setHeight(200)

var bar = dFrame.addBar(barStyle)

bar.setPos([5, 15])

or

var bar = dFrame.addBar()

bar.setPos([5, 15])

bar.setWidth(100)

bar.setHeight(200)

Caution - 1

Most of time the autoWidth and autoHeight values of BarStyles will be set to 'BUTTON' because it is the default value and the easiest way of drawing fixed Bars (Bars set to 'TOP', 'RIGHT' etc… ). For floating Bars (Bars having an array as position) the 'BUTTON' value has the same meaning as 'CONTENT'. That means that the floating Bars will be resized to their contents. If you want a bar has the exact dimensions set in the position array you must set autoWidth and autoHeight to '' (empty string).

Caution - 2

If a Bar is defined as a floating Bar (i.e. pos defined by an array) the setWidth and setHeight values determine the minimal dimensions of the Bar. Those values have to be set correctly in order to get the right result.
Example: If you define a floating Bar with autoWidth / Height set to 'BUTTON' so that the Bar is not visible as long it does not contain any Button you must also set the width / height values to 0

Caution - 3

The dimensions of DFrames, Bars or Menus having an array as position parameter are computed using the area remaining free after the fixed Bars (Bars having a position parameter set to 'TOP', 'RIGHT, 'LEFT' or 'BOTTOM') are positioned.

Array: Data type

Each of the value of the array can have a different type:

Integer: Percentage relative to the parent of the object.

position = [5, 5, 95, 95]

A object beginning at 5% of the left and top sides of its parent and ending at 95% of the right and bottom sides of its parent.

Note that all the values - including the last two - are positions relative to the parent object and are not dimensions.

String: Dimension in pixels

position = [5, 5, '400', '400']

A DFrame beginning at 5% of the left and top sides of its parent and having a width and a height of 400 pixels.

Note that, if strings, the two last parameters are dimensions and not not positions.

String: Special behavior if '*'

Special syntaxes for the position parameter allow to get a centered or/and auto resize objects as if the setCenter or/and setResize methods of the Style of the object were used.

Those specifications does not (currently) apply to DFrames created with the setURL method but works with DFrames created with the alert / addAlert methods and on all others objects.

'*' for the first two positions indicate a centered object.

Apply only when the DFrame.alert or addAlert methods are used to create a DFrame

position = ['*', '*', 20, 20]: A centered DFrame having a width and a height of 20% of the parent DFrame.

About centered objects see the setCentered method of DFrameStyle

'*' for the two last positions indicate an auto resize Bar.

Only apply to Bars: Buttons and Menus have other method for auto resize and DFrame cannot be resized to their contents.

position = [20, 20, '*', '*']: A auto-resize Bar beginning at 20% of the left and top sides of the parent DFrame.

About auto-resize Bars see the setAutoWidth/Height methods of BarStyle.

About auto-resize Buttons see the setAutoWidth/Height methods of ButtonStyle.

An auto-resize and centered Bar can be created with 4 '*': position = ['*', '*', '*', '*']

array. Only apply to DFrame position

The first two values of an array defining a DFrame position can be an array of 3 parameters:

[dFrame, positionKey, numberOfPixels]

dFrame: Some instantiated but not necessarily created DFrame. The reference DFrame.

positionKey, not case sensitive string. 'TOP', 'RIGHT', 'BOTTON' or 'LEFT'

numberOfPixels: number of pixels between the reference DFrame and the new one.

var dFrame1 = new DFrame(parameters);
var position = [0, 0, 100, 100];
position[0] = [dFrame1, 'Right', 5];

var dFrame2 = new DFrame(position, title, style, dFrame1)

The left side of dFrame2 will be created with 5 pixels of the right side of dFrame1.

Demo

file: newDFrame.html

Run the example
See the source code

file: position.button.html

Run the example
See the source code

file: position.menu.html

Run the example
See the source code