boxes/TextGrid. TextGrid

This class is a special type of AbstractBox that displays a grid of single
characters.

It's used CrossWord and WordSearch activities.

Constructor

new TextGrid(parent, container, boxBase, x, y, ncw, nch, cellW, cellH, border)

TextGrid constructor

Parameters:
NameTypeDescription
parentmodule:boxes/AbstractBox.AbstractBox

The AbstractBox to which this text grid belongs

containermodule:AWT.Container

The container where this text grid is placed.

boxBasemodule:boxes/BoxBase.BoxBase

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

xnumber

X coordinate of the upper left corner of this grid

ynumber

Y coordinate of the upper left corner of this grid

ncwnumber

Number of columns of the grid

nchnumber

Nomber of rows of the grid

cellWnumber

Width of the cells

cellHnumber

Height of the cells

borderboolean

When true, a border must be drawn between the cells

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

answers :Array.<Array.<string>>

Two-dimension array with the expected characters, used to check user's answers.

Type:
  • Array.<Array.<string>>

attributes :Array.<Array.<number>>

Two-dimension array of bytes used as containers of boolean attributes

Type:
  • Array.<Array.<number>>
See
  • TextGrid.flags

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.

cellHeight :number

The cell height, in pixels

Type:
  • number

cellWidth :number

The cell width, in pixels

Type:
  • number

chars :Array.<Array.<string>>

Two-dimension array of characters

Type:
  • Array.<Array.<string>>

container :module:AWT.Container

The Container to which this AbstractBox belongs

cursor :module:AWT.Point

The current position of the cursor

true when the cursor is "blinking" (cell drawn with BoxBase inverse attributes)

Type:
  • boolean

cursorEnabled :boolean

Whether the blinking cursor is enabled or disabled

Type:
  • boolean

cursorTimer :module:AWT.Timer

Controls the blinking of the cursor

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

nCols :number

Number of columns

Type:
  • number

nRows :number

Number of rows

Type:
  • number

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

The preferred bounds of this grid

randomChars :string

Characters that can be used when randomizing the content of this grid

Type:
  • string
See
  • TextGridContent#randomChars

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

useCursor :boolean

Whether this grid uses a blinking cursor or not

Type:
  • boolean

visible :boolean

Whether this box is visible or not

Type:
  • boolean

wild :string

The character to be used as wildcard

Type:
  • string

wildTransparent :boolean

Whether the wildcard character is transparent or opaque

Type:
  • boolean

(static, constant) defaults :object

TextGrid default values

Type:
  • object

(static, constant) flags :object

Binary flags used to mark status

Type:
  • object

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

Makes the cursor blink, alternating between two states. This method should be called only by
module:boxes/TextGrid.TextGrid#cursorTimer

Parameters:
NameTypeDescription
statusboolean

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

countCharsLike(ch) → {number}

Counts the number of cells of this grid with the specified character

Parameters:
NameTypeDescription
chstring
Returns:
Type: 
number

countCoincidences(checkCase) → {number}

Counts the number of coincidences between the answers array and the current content of this grid

Parameters:
NameTypeDescription
checkCaseboolean

Make comparisions case-sensitive

Returns:
Type: 
number

drawBorder(ctx)

Draws the box border

Parameters:
NameTypeDescription
ctxexternal:CanvasRenderingContext2D

The canvas rendering context where the border
will be drawn.

end()

Stops the cursor timer if not null and active

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

findFreeCell(from, dx, dy) → {module:AWT.Point}

Finds the coordinates of the nearest non-locked cell (non-wildcard) moving on the indicated
'X' and 'Y' directions.

Parameters:
NameTypeDescription
frommodule:AWT.Point

Logical coordinates of the starting point

dxnumber

0 means no movement, 1 go right, -1 go left.

dynumber

0 means no movement, 1 go down, -1 go up.

Returns:
Type: 
module:AWT.Point

findNextCellWithAttr(startX, startY, attr, dx, dy, attrState) → {module:AWT.Point}

Finds the first cell with the specified attributes at the specified state, starting
at specified point.

Parameters:
NameTypeDescription
startXnumber

Starting X coordinate

startYnumber

Starting Y coordinate

attrnumber

Attribute to check. See module:boxes/TextGrid.TextGrid.flags.

dxnumber

0 means no movement, 1 go right, -1 go left.

dynumber

0 means no movement, 1 go down, -1 go up.

attrStateboolean

Desired state (enabled or disabled) of attr

Returns:
Type: 
module: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

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

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

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

getCellAttribute(px, py, attribute) → {boolean}

Gets the specified attribute of a cell

Parameters:
NameTypeDescription
pxnumber

The 'X' coordinate of the cell

pynumber

The 'Y' coordinate of the cell

attributenumber

The binary flag representing this attribute. See module:boxes/TextGrid.TextGrid.flags.

Returns:
  • true if the cell has this attribute, false otherwise.
Type: 
boolean

getCellBorderBounds(px, py) → {module:AWT.Rectangle}

Gets the rectangle enclosing a specific cell, including the border thick.

Parameters:
NameTypeDescription
pxnumber

The 'X' coordinate of the cell

pynumber

The 'Y' coordinate of the cell

Returns:
Type: 
module:AWT.Rectangle

getCellRect(px, py) → {module:AWT.Rectangle}

Gets the rectangle enclosing a specific cell

Parameters:
NameTypeDescription
pxnumber

The 'X' coordinate of the cell

pynumber

The 'Y' coordinate of the cell

Returns:
Type: 
module:AWT.Rectangle

getCharAt(px, py) → {string}

Gets the character of the cell at the specified coordinates

Parameters:
NameTypeDescription
pxnumber

'X' coordinate

pynumber

'Y' coordinate

Returns:
Type: 
string

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

getCursor() → {module:AWT.Point}

Gets the current position of the blinking cursor

Returns:
Type: 
module:AWT.Point

getHostedComponent() → {external:jQuery}

Gets the current $hostedComponent member

Returns:
Type: 
external:jQuery

getItemFor(rx, ry) → {module:AWT.Point}

For a specific cell located at column rx and row ry, finds the number of words delimited
by wildchars located behind its current position and in the same row and column. Used in
CrossWord activities to find the definition for a specific cell.

The result is returned as 'x' and 'y' properties of a logical point.

Parameters:
NameTypeDescription
rxnumber

The 'X' position of the cell

rynumber

The 'Y' position of the cell

Returns:
  • The logical positions of the definition for this cell inside the list
    of current definitions of its row and column. '0' means first definition of its row/column,
    '1' the second one, etc.
Type: 
module:AWT.Point

getLogicalCoords(devicePoint) → {module:AWT.Point}

Gets the logical coordinates (in 'cell' units) of a device point into the grid

Parameters:
NameTypeDescription
devicePointmodule:AWT.Point
Returns:
Type: 
module:AWT.Point

getMinimumSize() → {module:AWT.Dimension}

Gets the minimum size of this grid

Returns:
Type: 
module:AWT.Dimension

getNumCells() → {number}

Gets the number of cells of this grid

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 grid

Returns:
Type: 
module:AWT.Dimension

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

Scales the grid to a new size

Parameters:
NameTypeDescription
scalenumber

The factor used to multiply all coordinates and sizes

Returns:
Type: 
module:AWT.Dimension

getShape() → {module:AWT.Shape}

Gets the current shape used in this box

Returns:
Type: 
module:AWT.Shape

getStringBetween(x0, y0, x1, y1) → {string}

Gets the text formed by the letters between two cells that share a straight line on the grid.
The text can be formed horizontally, vertically and diagonal, both in left-to-right or
right-to-left direction.

Parameters:
NameTypeDescription
x0number

'X' coordinate of the first cell

y0number

'Y' coordinate of the first cell

x1number

'X' coordinate of the second cell

y1number

'Y' coordinate of the second cell

Returns:
Type: 
string

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

isCellOk(px, py, checkCase) → {boolean}

Checks if a specific cell is equivalent to the content of answers at its position

Parameters:
NameTypeDescription
pxnumber

X coordinate

pynumber

Y coordinate

checkCaseboolean

Make comparisions case-sensitive

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

isValidCell(px, py) → {boolean}

Checks if the specified logical coordinates are inside the valid bounds of the grid.

Parameters:
NameTypeDescription
pxnumber

'X' coordinate

pynumber

'Y' coordinate

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

moveCursor(dx, dy, skipLocked)

Moves the cursor in the specified x and y directions.

Parameters:
NameTypeDescription
dxnumber

Amount to move in the 'X' axis

dynumber

Amount to move in the 'Y' axis

skipLockedboolean

Skip locked cells (wildcards in CrossWord)

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

randomize()

Substitutes the current content of all cells with wildcards with a randomly generated char.

See
  • TextGridContent#randomChars

repaintCell(px, py)

Repaints a cell

Parameters:
NameTypeDescription
pxnumber

The 'X' coordinate of the cell

pynumber

The 'Y' coordinate of the cell

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

setAllCellsAttribute(attribute, state)

Sets the specified attribute to all cells.

Parameters:
NameTypeDescription
attributenumber

The binary flag representing this attribute. See module:boxes/TextGrid.TextGrid.flags.

stateboolean

Whether to set or unset the attribute.

setAlternative(newVal)

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

Parameters:
NameTypeDescription
newValboolean

setAttribute(px, py, attribute, state)

Sets or unsets a specifi attrobut to a cell.

Parameters:
NameTypeDescription
pxnumber

The 'X' coordinate of the cell

pynumber

The 'Y' coordinate of the cell

attributenumber

The binary flag representing this attribute. See module:boxes/TextGrid.TextGrid.flags.

stateboolean

Whether to set or unset the attribute.

setAttributeBetween(x0, y0, x1, y1, attribute, value)

Sets a specific attribute to all cells forming a straight line between two cells on the grid.

Parameters:
NameTypeDescription
x0number

'X' coordinate of the first cell

y0number

'Y' coordinate of the first cell

x1number

'X' coordinate of the second cell

y1number

'Y' coordinate of the second cell

attributenumber

The binary flag representing this attribute. See module:boxes/TextGrid.TextGrid.flags.

valueboolean

Whether to set or unset the attribute.

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

setBorder(newVal)

Sets/unsets a border to this box

Parameters:
NameTypeDescription
newValboolean

true to set a border.

setBoxBase(boxBase)

Sets the BoxBase of this box

Parameters:
NameTypeDescription
boxBasemodule:boxes/BoxBase.BoxBase

The new BoxBase

setCellAttributes(lockWild, clearChars)

Clears or sets global attributes to all cells

Parameters:
NameTypeDescription
lockWildboolean

When true, the wildcard cells will be marked with special
attributes (used in CrossWords to mark black cells)

clearCharsboolean

When true, the current content of cells will be erased.

setCellLocked(px, py, locked)

Sets or unsets the locked properties (black cell) to a specific cell.

Parameters:
NameTypeDescription
pxnumber

The logical 'X' coordinate of the cell

pynumber

The logical 'Y' coordinate of the cell

lockedboolean

When true, the locked attribute will be on.

setCharAt(px, py, ch)

Sets the specified character as a content of the cell at specified coordinates

Parameters:
NameTypeDescription
pxnumber

'X' coordinate

pynumber

'Y' coordinate

chstring

The character to set.

setChars(text)

Sets the characters to be placed in the cells of this TextGrid

Parameters:
NameTypeDescription
textstring

setContainer(newContainer)

Setter method for container

Parameters:
NameTypeDescription
newContainermodule:AWT.Container

The new Container assigned to this box

setCursorAt(px, py, skipLocked)

Sets the blinking cursor at a specific point

Parameters:
NameTypeDescription
pxnumber

X coordinate

pynumber

Y coordinate

skipLockedboolean

Skip locked (wildcard) cells

setCursorEnabled(status)

Whether the blinking cursor must be enabled or disabled.

Parameters:
NameTypeDescription
statusboolean

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

setUseCursor(value)

Sets the useCursor property of this text grid

Parameters:
NameTypeDescription
valueboolean

setVisible(newVal)

Sets this box visible or invisible

Parameters:
NameTypeDescription
newValboolean

true for visible

Starts the module:AWT.Timer that makes the cursor blink.

Stops the module:AWT.Timer that makes the cursor blink.

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)

Draws the content of this box on an HTML canvas element. At this level, only background
and border are painted/stroked. Derived classes should implement specific drawing tasks in
module:boxes/AbstractBox.AbstractBox#updateContent.

Parameters:
NameTypeAttributesDefaultDescription
ctxexternal:CanvasRenderingContext2D

The canvas rendering context used to draw the
box content.

dirtyRegionmodule:AWT.Rectangle<optional>
null

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

updateContent(ctx, dirtyRegionopt)

Parameters:
NameTypeAttributesDescription
ctxexternal:CanvasRenderingContext2D

The canvas rendering context used to draw the
grid.

dirtyRegionmodule:AWT.Rectangle<optional>

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

(static) createEmptyGrid(parent, container, x, y, tgc, wildTransparent) → {module:boxes/TextGrid.TextGrid}

Factory constructor that creates an empty grid based on a TextGridContent

Parameters:
NameTypeDescription
parentmodule:boxes/AbstractBox.AbstractBox

The AbstractBox to which the text grid belongs

containermodule:AWT.Container

The container where the text grid will be placed.

xnumber

X coordinate of the upper left corner of the grid

ynumber

Y coordinate of the upper left corner of the grid

tgcmodule:boxes/TextGridContent.TextGridContent

Object with the content and other settings of the grid

wildTransparentboolean

When true, the wildcard character will be transparent