JSWindows Pos_size Class

© February, 2013, MartinRinehart

Overview

A Pos_size is a container for the CSS position and size values:

Note that in the above list, and in the code, the horizontal dimension is specified first: x, y order.

These are all numbers, interpreted as numbers of pixels.

The size specified includes paddings and borders. Content area size (calculated whenever CSS width and height is needed) is the greater of size less border size(s) less padding or zero.

Constructors

It is seldom useful to define a Pos_size on its own. They are defined from arrays within Wobjs and Wobj-based objects.

The Common Case Within a Wobj

var ps = new jsw.Pos_size( wobj, left,top, width,height, padding );

(We adopt the SVG convention of using whitespace between, but not within, the x,y coordinate pairs.)

padding may be undefined, a single number or an array of four numbers. undefined is the same as zero in the computation of horizontal/vertical padding size. Single numbers indicate padding of that number (of pixels) on all four sides. An array of four numbers specifies [left, top, right, bottom] padding sizes.

Using an Array

The values may be supplied in an array. This is convenient when you define Wobjs and Wobj-based elements of the DOM. (The Wobj's arguments are new jsw.Wobj( ..., Pos_size, ... ). Use an array, within the Wobj constructor, this way:

var elem = new jsw.Wobj( ..., [1,2, 3,4], ... );

Padding may also be included:

var elem = new jsw.Wobj( ..., [1,2, 3,4, 5], ... );

Separate paddings for the different sides may be specified:

var elem = new jsw.Wobj( ..., [1,2, 3,4[, lft, top, rgt, btm]], ... );

A reference to the Wobj and the array is passed to the Pos_size constructor.

The Class Methods

The parse_ps() Method

jsw2.Pos_size.parse_ps( ps_spec );

Converts an alternate position/size spec (string) into an object. (See "Alternate Position/Size Syntax", below.) Returns the equivalent of the alternate string in an array:

... return {
        ratio:  r.rrr,
        offset: nnn,
        type:   L
    }

The ratio is a number between 0.0 and 1.0. The offset is a number of pixels. The type is "B" (borders included) or "C" (content only). If omitted, the default type is "B". If omitted, the default offset is zero.

Note: (caveat coder) The ratio number is returned as specified, even if not within the correct range. Values greater than 1.0 or less than 0.0 may not work tomorrow as they work today.

The resize() Method

var new_size = Pos_size.resize(spec, factor);

This method is used to scale up (or down) a size. In the simple case, spec is a number and it is multiplied by the factor. A factor of two doubles a size. In the non-trivial case, the spec is a specification in the alternate syntax (see below). The ratio is scaled up (or down) by the factor but the offset is not scaled.

The Instance Methods

The compute() Method

Pos_size.compute();

Calls the size() and position() methods and then computes the content area size. Size is computed first as the position, in the alternate syntax, depends on the size.

The get_padding_horizontal() Method

var = hpad = Pos_size.get_padding_horizontal();

Returns the padding, if a single number, or the left and right values (array elements zero and two) from the array.

The get_padding_vertical() Method

var vpad = Pos_size.get_padding_vertical();

Returns the padding, if a single number, or the top and bottom values (array elements one and three) from the array.

The get_styles() Method

var = ps_styles = Pos_size.get_styles();

Returns a styles object for left and top, width and height and padding. For example:

var styles = {
	left: '100px',
	top: '50px',
	width: '300px',
	height: '100px',
	padding: '5px'
}

If width or height is undefined, returns width: '' and/or height: ''. If padding is specified as an array of four values, returns values for paddingLeft, paddingTop, etc.

The position() Method

Pos_size.position();

Calls position_left() and position_top().

The position_xxx() Methods

'xxx' is one of 'left' or 'top'.

var pos_left = Pos_size.position_left();


var pos_top = Pos_size.position_top();

Returns the number specified or converts the alternate syntax to an object (ratio, offset and type, where type is 'B' or 'C') and returns a number for the position computed. Assumes size has been computed first.

The resize() Method

Pos_size.resize(width, height);

Saves new size values and recomputes sizes. Size values may be numbers or strings in the alternate syntax.

The size() Method

Pos_size.size();

Calls size_width() and size_height().

The size_xxx() Methods

'xxx' is one of 'width' or 'height'.

Pos_size.size_width(width);


Pos_size.size_width(height);

Returns the parameter if it is a number. If the parameter is a string in the alternate syntax, parses the string to find ratio, offset and type and returns a number after computing the size.

The toString() Method

Returns Pos_size{wobj, left,top, width,height} (SVG-style, spaces betweeen but not within x,y pairs).

The Alternate Position/Size Syntax

Left and top may be specified with strings. The first component of each is a ratio (decimal fraction), a value from '0.0' through '1.0', that specifies how much of the free space (defined below) to leave to the left (or top) of the Wobj. A value of '0.0' puts the Wobj at the left (or top) border. A value of '1.0' puts the Wobj at the right (or bottom) border.

The second component of the string is an optional offset, specified as a signed integer number of pixels. If you want to place a closing "X" button two pixels inside the top, right corner, you would specify "1.0 -2", "0.0 -2" (all the way to the left, minus two pixels, and at the top, also minus two pixels).

The final component, also optional, specifies whether you want to use the border ("B") as the edge, or the content area ("C"). The border is assumed by default. The above closing button is two pixels from the edge of the border. To put it inside the content area, use "1.0 -2 C", "0.0 -2 C".

The border corner positions are:

The content area corner positions are:

The alternate syntax is intended to be applicable to padding as well, but at present (20130804) this is untested.

Free Space

The "free space" is the distance from the Wobj's border's left (or top) edge to the left (or top) edge of its container's border (default or "B") or the container's content area ("C"). Note that the extreme corner of the container may be (visually, at least) outside the border if there is a border radius.

CSS Right and Bottom

If you want to specify values nn pixels from the right (or bottom) of the content area (as if, for example, you were converting a CSS "right" property), use the alternate syntax. '1 -nn C' is the same location as right: nn; or bottom: nn:.

Invalid Specifications

There is no reasonableness checking. The "free space" may be negative. The ratios may be greater than 1.0. The offsets may be far outside the container. Experiment at your own risk.


Feedback: MartinRinehart at gmail dot com

# # #