boxes/BoxBag. BoxBag

BoxBag is a class derived from AbstractBox that contains a collection of "boxes"
(objects also derived from AbstractBox). This class implements methods to add, remove
and retrieve boxes, and to manage some of its properties like visibility, status, location and size.

Constructor

new BoxBag(parentopt, containeropt, boxBaseopt)

BoxBag constructor

Parameters:
NameTypeAttributesDescription
parentmodule:boxes/AbstractBox.AbstractBox<optional>

The AbstractBox to which this box bag belongs

containermodule:AWT.Container<optional>

The container where this box bag is placed.

boxBasemodule:boxes/BoxBase.BoxBase<optional>

The object where colors, fonts, border and other graphic properties

Extends

Members

$accessibleElement :external:jQuery

DOM element used to display this cell content in wai-aria contexts

$hostedComponent :external:jQuery

An external JQuery DOM element hosted by this box

accessibleAlwaysActive :boolean

Flag indicating that $accessibleElement should be always active

Type:
  • boolean

accessibleText :string

Text to be used in accessible contexts

Type:
  • string

alternative :boolean

Whether this box must be displayed with alternative or regular color and font settings

Type:
  • boolean

backgroundBox :module:boxes/AbstractBox.AbstractBox

An optional box used as a background by this BoxBag

border :boolean

Whether this box has a border or not

Type:
  • boolean

boxBase :module:boxes/BoxBase.BoxBase

The BoxBase related to this AbstractBox. When null, the parent can provide an
alternative one.

cells :Array.<module:boxes/AbstractBox.AbstractBox>

The array of cells

container :module:AWT.Container

The Container to which this AbstractBox belongs

dim :module:AWT.Dimension

The Dimension of the Rectangle

focused :boolean

Whether this box holds the input focus

Type:
  • boolean

inactive :boolean

Whether this box is active or inactive

Type:
  • boolean

inverted :boolean

Whether this box must be displayed with inverted or regular colors

Type:
  • boolean

marked :boolean

Whether this box is marked (selected) or not

Type:
  • boolean

parent :module:boxes/AbstractBox.AbstractBox

The parent AbstractBox (can be null)

pos :module:AWT.Point

The current position of the shape

preferredBounds :module:AWT.Rectangle

Rectangle containing the preferred bounds of the BoxBag

role :string

Describes the main role of this box on the activity. Useful in wai-aria descriptions.

Type:
  • string

shape :module:AWT.Shape

The shape of this box (the box Rectangle or a special Shape, if set)

specialShape :boolean

Whether this box has a shape that is not a rectangle

Type:
  • boolean

temporaryHidden :boolean

Used to temporary hide a box while other drawing operations are done

Type:
  • boolean

tmpTrans :boolean

Cells with this attribute will be transparent but with painted border

Type:
  • boolean

type :string

Shape type id

Type:
  • string

visible :boolean

Whether this box is visible or not

Type:
  • boolean

Methods

add(shape) → {module:AWT.Rectangle}

Adds the boundaries of another shape to the current one

Parameters:
NameTypeDescription
shapemodule:AWT.Shape

The module:AWT.Shape to be added

Returns:
Type: 
module:AWT.Rectangle

addBox(bx)

Adds an AbstractBox to the collection of cells

Parameters:
NameTypeDescription
bxmodule:boxes/AbstractBox.AbstractBox

The box to add

boxIndex(bx) → {number}

Returns the index of a specific box in the cells array

Parameters:
NameTypeDescription
bxmodule:boxes/AbstractBox.AbstractBox
Returns:
Type: 
number

clip(ctx, fillRuleopt) → {external:CanvasRenderingContext2D}

Creates a clipping region on the specified HTML canvas 2D rendering context

Parameters:
NameTypeAttributesDefaultDescription
ctxexternal:CanvasRenderingContext2D

The rendering context

fillRulestring<optional>
'nonzero'

Can be 'nonzero' (default when not set) or 'evenodd'

Returns:
  • The provided rendering context
Type: 
external:CanvasRenderingContext2D

clone() → {module:AWT.Rectangle}

Clones this Rectangle

Returns:
Type: 
module:AWT.Rectangle

countInactiveCells() → {number}

Count the number of cells of this BoxBag that are in "inactive" state

Returns:
Type: 
number

drawBorder(ctx)

Draws the box border

Parameters:
NameTypeDescription
ctxexternal:CanvasRenderingContext2D

The canvas rendering context where the border
will be drawn.

end()

Finisher method

equals(r) → {boolean}

Checks if two shapes are equivalent.

Parameters:
NameTypeDescription
rmodule:AWT.Shape

The Shape to compare against

Returns:
Type: 
boolean

fill(ctx, dirtyRegionopt) → {external:CanvasRenderingContext2D}

Fills the Shape with the current style in the provided HTML canvas context

Parameters:
NameTypeAttributesDescription
ctxexternal:CanvasRenderingContext2D

The canvas 2D rendering context where to fill this shape.

dirtyRegionmodule:AWT.Rectangle<optional>

The context region to be updated. Used as clipping
region when drawing.

Returns:
  • The provided rendering context
Type: 
external:CanvasRenderingContext2D

findBox(p) → {module:boxes/AbstractBox.AbstractBox}

Finds the first visible AbstractBox located under the specified point

Parameters:
NameTypeDescription
pmodule:AWT.Point

getAttributes() → {object}

Gets a object with the basic attributes needed to rebuild this instance excluding functions,
parent references, constants and also attributes retaining the default value.
The resulting object is commonly usued to serialize elements in JSON format.

Returns:
  • The resulting object, with minimal attrributes
Type: 
object

getBackgroundBox() → {module:boxes/AbstractBox.AbstractBox}

Gets the background box

getBorderBounds() → {module:AWT.Rectangle}

Returns the enclosing Rectangle of this box including its border (if any)

Returns:
Type: 
module:AWT.Rectangle

getBounds() → {module:AWT.Rectangle}

Gets the enclosing Rectangle of this Shape.

Returns:
Type: 
module:AWT.Rectangle

getBox(n) → {module:boxes/AbstractBox.AbstractBox}

Returns the box at a specific index in the cells array

Parameters:
NameTypeDescription
nnumber

The index

getBoxBaseResolve() → {module:boxes/BoxBase.BoxBase}

Gets the real BoxBase associated to this box, scanning down parent relationships.

getContainerResolve() → {module:AWT.Container}

Gets the container associated to this box, asking its parents when null.

Returns:
Type: 
module:AWT.Container

getContainerX() → {module:AWT.Container}

Gets the container attribute of this box, without checking its parent

Returns:
Type: 
module:AWT.Container

getCoords() → {string}

Gets a string with the co-ordinates of the upper-left and lower-right vertexs of this rectangle,
(with values rounded to int)

Returns:
Type: 
string

getHostedComponent() → {external:jQuery}

Gets the current $hostedComponent member

Returns:
Type: 
external:jQuery

getMinimumSize() → {module:AWT.Dimension}

Gets the minimum size requested by this BoxBag

Returns:
Type: 
module:AWT.Dimension

getNumCells() → {number}

Returns the number of cells stored in this BoxBag

Returns:
Type: 
number

getOppositeVertex() → {module:AWT.Point}

Gets the module:AWT.Point corresponding to the lower-right vertex of the Rectangle.

Returns:
Type: 
module:AWT.Point

getParent() → {module:boxes/AbstractBox.AbstractBox}

Gets the current parent of this box

getPreferredSize() → {module:AWT.Dimension}

Gets the preferred size of this BoxBag

Returns:
Type: 
module:AWT.Dimension

getScaledSize(scale) → {module:AWT.Dimension}

Scales the current size of this box bag, multiplying all values by a specific factor

Parameters:
NameTypeDescription
scalenumber

The scale factor

Returns:
Type: 
module:AWT.Dimension

getShape() → {module:AWT.Shape}

Gets the current shape used in this box

Returns:
Type: 
module:AWT.Shape

grow(dx, dy) → {module:AWT.Rectangle}

Expands the boundaries of this shape. This affects the current position and dimension.

Parameters:
NameTypeDescription
dxnumber

The amount to grow (or decrease) in horizontal direction

dynumber

The amount to grow (or decrease) in vertical direction

Returns:
Type: 
module:AWT.Rectangle

hasBorder() → {boolean}

Checks if this box has border

Returns:
Type: 
boolean

intersects(_r) → {boolean}

Checks if the provided Rectangle r intersects with this shape.

Parameters:
NameTypeDescription
_rmodule:AWT.Rectangle
Returns:
Type: 
boolean

invalidate(rect)

Invalidates the zone corresponding to this box in the associated module:AWT.Container, if any.

Parameters:
NameTypeDescription
rectmodule:AWT.Rectangle

The rectangle to be invalidated. When null, it's the full
container area.

isAlternative() → {boolean}

Checks if this box is in alternative state.

Returns:
Type: 
boolean

isFocused() → {boolean}

Checks if this box has the input focus

Returns:
Type: 
boolean

isInactive() → {boolean}

Checks if this box is currently inactive.

Returns:
Type: 
boolean

isInverted() → {boolean}

Checks if this box is in inverted state.

Returns:
Type: 
boolean

isMarked() → {boolean}

Checks if this box is marked

Returns:
Type: 
boolean

isRect() → {boolean}

Shorthand method for determining if a Shape is an Rectangle

Returns:
Type: 
boolean

isTemporaryHidden() → {boolean}

Checks if this box is temporary hidden

Returns:
Type: 
boolean

isVisible() → {boolean}

Checks if this box is fully visible

Returns:
Type: 
boolean

moveBy(dx, dy)

Sets a new location to this box. In JClic this method was named translate.

Parameters:
NameTypeDescription
dxnumber

The displacement on the X axis

dynumber

The displacement on the Y axis

moveTo(newPos, yopt)

Sets a new location for this box. In JClic this method was named setLocation

Parameters:
NameTypeAttributesDescription
newPosAWT.Point | number

A point or the x coordinate of a new point.

ynumber<optional>

The y coordinate of a new point.

preparePath(ctx) → {external:CanvasRenderingContext2D}

Prepares an HTML canvas 2D rendering context with a path that can be used to stroke a line,
to fill a surface or to define a clipping region.

Parameters:
NameTypeDescription
ctxexternal:CanvasRenderingContext2D
Returns:
  • The provided rendering context
Type: 
external:CanvasRenderingContext2D

recalcSize()

Recalculates the total size of this BoxBag (useful after direct additions o deletions of
elements in the cells array).
Updates preferredBounds and the current position and size of the box bag.

scaleBy(delta) → {module:AWT.Rectangle}

Multiplies the dimension of the Shape by the specified delta amount.

Parameters:
NameTypeDescription
deltaPoint | Dimension

Object containing the X and Y ratio to be scaled.

Returns:
Type: 
module:AWT.Rectangle

setAlternative(newVal)

Overrides module:boxes/AbstractBox.AbstractBox#setAlternative iterating over all the cells stored in this box bag.

Parameters:
NameTypeDescription
newValboolean

Whether to set or unset the cells in "alternative" mode

setAttributes(data) → {module:AWT.Rectangle}

Reads the properties of this Rectangle from a data object

Parameters:
NameTypeDescription
dataobject

The data object to be parsed

Returns:
Type: 
module:AWT.Rectangle

setBackgroundBox(bx)

Sets the background box

Parameters:
NameTypeDescription
bxmodule:boxes/AbstractBox.AbstractBox

setBorder(newVal)

Overrides module:boxes/AbstractBox.AbstractBox#setBorder iterating over all the cells stored in this box bag.

Parameters:
NameTypeDescription
newValboolean

Whether to set or unset the border

setBoxBase(boxBase)

Sets the BoxBase of this box

Parameters:
NameTypeDescription
boxBasemodule:boxes/BoxBase.BoxBase

The new BoxBase

setCellAttr(key, value)

Sets the specified key - value pair to all cells of this bag.

Parameters:
NameTypeDescription
keystring

The key to be established

valueany

The value, of any type

setContainer(newContainer)

Setter method for container

Parameters:
NameTypeDescription
newContainermodule:AWT.Container

The new Container assigned to this box

setFocused(newVal)

Sets or unsets the input focus to this box.

Parameters:
NameTypeDescription
newValboolean

setHostedComponent($hc)

Sets the $hostedComponent member.

Parameters:
NameTypeDescription
$hcexternal:jQuery

The jQuery DOM component hosted by this box.

setHostedComponentBorder()

Sets the $hostedComponent border, based on the current
BoxBase of this box.

setHostedComponentBounds(_sizeChanged)

Places and resizes $hostedComponent, based on the size
and position of this box.

Parameters:
NameTypeDescription
_sizeChangedboolean

true when this ActiveBox has changed its size

setHostedComponentColors()

Sets $hostedComponent colors and other css properties
based on the current BoxBase of this box.

setHostedComponentVisible()

Makes module:boxes/AbstractBox.AbstractBox#$hostedComponent visible or invisible, based on the value of
the AbstractBox visible flag.

setInactive(newVal)

Makes this box active (false) or inactive (true)

Parameters:
NameTypeDescription
newValboolean

setInverted(newVal)

Puts this box in inverted mode or restores its original state.

Parameters:
NameTypeDescription
newValboolean

setMarked(newVal)

Sets this box in marked mode, or restores its original state.

Parameters:
NameTypeDescription
newValboolean

setParent(parent)

Setter method for parent

Parameters:
NameTypeDescription
parentmodule:boxes/AbstractBox.AbstractBox

The new parent of this box

setShape(sh)

Sets the shape used to draw the content of this box

Parameters:
NameTypeDescription
shmodule:AWT.Shape

The shape to be set

setSize(width, height)

Changes the size of this box

Parameters:
NameTypeDescription
widthnumber
heightnumber

setTemporaryHidden(newVal)

Makes this box temporary hidden (newVal true) or resets its original state (newVal false)

Parameters:
NameTypeDescription
newValboolean

setVisible(newVal)

Overrides module:boxes/AbstractBox.AbstractBox#setVisible iterating over all the cells stored in this box bag.

Parameters:
NameTypeDescription
newValboolean

Whether to set the cells visible or not

stroke(ctx) → {external:CanvasRenderingContext2D}

Draws this shape in the provided HTML canvas 2D rendering context.

Parameters:
NameTypeDescription
ctxexternal:CanvasRenderingContext2D

The canvas 2D rendering context where to draw the shape.

Returns:
  • The provided rendering context
Type: 
external:CanvasRenderingContext2D

toString() → {string}

Overwrites the original 'Object.toString' method with a more descriptive text

Returns:
Type: 
string

update(ctx, dirtyRegionopt)

Performs graphics operations for each cell.
Overrides module:boxes/AbstractBox.AbstractBox#update

Parameters:
NameTypeAttributesDescription
ctxexternal:CanvasRenderingContext2D

The canvas rendering context used to draw the
box contents.

dirtyRegionmodule:AWT.Rectangle<optional>

The area that must be repainted. null refers to the whole box.

updateContent(_ctx, _dirtyRegionopt)

Here is where classes derived from AbstractBox should implement the drawing of its
content. Background and border are already painted in module:boxes/AbstractBox.AbstractBox#update.

Parameters:
NameTypeAttributesDescription
_ctxexternal:CanvasRenderingContext2D

The canvas rendering context used to draw the
box content.

_dirtyRegionmodule:AWT.Rectangle<optional>

The area that must be repainted. null refers to the whole box.

(static) layoutDouble(desiredMaxSize, rsA, rsB, boxGridPos, margin) → {module:AWT.Dimension}

Static method that sets the position and dimension of two Resizable objects based on a
preferred maximum size, a layout schema and a margin.

Parameters:
NameTypeDescription
desiredMaxSizemodule:AWT.Dimension

The preferred maximum size

rsAResizable

First resizable object implementing the methods described in the
Resizable
interface of JClic. Currently a BoxBag or TextGrid.

rsBResizable

Second resizable object

boxGridPosstring

The layout schema. Possible values are:

  • "AB" (A at left, B at right)
  • "BA" (B at left, A at right)
  • "AUB" (A above B)
  • "BUA" (A below B).
marginnumber

The margin between the available area and the BoxBag

Returns:
  • The resulting size of the container
Type: 
module:AWT.Dimension

(static) layoutSingle(preferredMaxSize, rs, margin) → {module:AWT.Dimension}

Static method that sets the position and dimension of a Resizable object based on a
preferred maximum dimension and a margin.

Parameters:
NameTypeDescription
preferredMaxSizemodule:AWT.Dimension

The preferred maximum size

rsResizable

A resizable object implementing the methods described in the
Resizable
interface of JClic. Currently a BoxBag or TextGrid.

marginnumber

The margin between the available area and the BoxBag

Returns:
  • The resulting size of the container
Type: 
module:AWT.Dimension