JavaScript Graphics Library (JSGL.org) Draw and move interactive vector graphics easily in Javascript!

Group Element (jsgl.elements.GroupElement)

This page documents the group element, a meta-element that allows to aggregate multiple base elements and treat them as a single element.

The class inherits from jsgl.elements.AbstractElement, using the Composite OOP design pattern.

Grouping of elements is especially useful for:

  • moving multiple elements: the group has its own, inner coordinate system, allowing translation of all the elements at once within the parent system,
  • working with z-indices: allows hierarchical composition of z-index ordering. All the elements in the group share the same z-index within the parent system, but can further be ordered within the group,
  • working with mouse events: if mouse event listener is registered to the group, interaction with any of the group's elements will trigger the event.

Creation

To create a group, use the .createGroup() method of a jsgl.Panel object, and add it to its viewport:

var myGroup = myPanel.createGroup();
myPanel.addElement(myGroup);

Method Summary

Collection of Elements

Name Description
addElement(element: jsgl.elements.AbstractElement) Adds an elements to the group.
clear() Removes all the elements from the group.
containsElement(element: jsgl.elements.AbstractElement) : Boolean Tests whether the given element is contained within the group.
getElementAt(index: Number) : jsgl.elements.AbstractElement Gets an element from the list of elements contained within the group at given index.
getElementsCount() : Number Gets the number of elements that are currently contained within the group.
removeElement(element: jsgl.elements.AbstractElement) Removes the given element from the group.

Location (Coordinate Space Translation)

Setters
setX(newX: Number) Sets the new X-axis translation of the group's inner coordspace within the coordspace of a parent container.
setY(newY: Number) Sets the new Y-axis translation of the group's inner coordspace within the coordspace of a parent container.
setLocationXY(newX: Number, newY: Number) Sets the translation of the inner coordspace of the group within the coordspace of a parent container. The translation is given as couple of coordinates.
setLocation(newLocation: jsgl.Vector2D) Sets the translation of the inner coordspace of the group within the coordspace of a parent container. The translation is given as a jsgl.Vector2D object.
Getters
getX() : Number Gets the current X-axis translation of the group's inner coordspace within the coordspace of a parent container.
getY() : Number Gets the current Y-axis translation of the group's inner coordspace within the coordspace of a parent container.
getLocation() : jsgl.Vector2D Gets the current translation of the inner coordpace of the group within the coordspace of a parent container.

Method Detail

addElement(element: jsgl.elements.AbstractElement)

Adds an elements to the group. The element is appended at the end of the list of group's elements.

Parameters

Name Type Description
element jsgl.elements.AbstractElement The element to be added.

Example

Create a sample group and add some elements in it:

var myGroup = myPanel.createGroup();
myPanel.addElement(myGroup);
 
// create shared stroke and fill objects
var stroke = new jsgl.stroke.SolidStroke();
stroke.setColor('#036');
stroke.setWeight(5);
var fill = new jsgl.fill.SolidFill();
fill.setColor('#cdf');
 
// create a circle for head
var headCircle = myPanel.createCircle();
headCircle.setCenterLocationXY(0, -30);
headCircle.setRadius(15);
headCircle.setStroke(stroke);
headCircle.setFill(fill);
myGroup.addElement(headCircle);
 
// create a rectangle for body
var bodyRect = myPanel.createRectangle();
bodyRect.setHorizontalAnchor(jsgl.HorizontalAnchor.CENTER);
bodyRect.setVerticalAnchor(jsgl.VerticalAnchor.TOP);
bodyRect.setLocationXY(0, -10);
bodyRect.setSizeWH(50, 50);
bodyRect.setStroke(stroke);
bodyRect.setFill(fill);
myGroup.addElement(bodyRect);
 
// create a line for hands
var handsLine = myPanel.createLine();
handsLine.setStartPointXY(-50, 0);
handsLine.setEndPointXY(50, 0);
handsLine.setStroke(stroke);
handsLine.setZIndex(-1);
myGroup.addElement(handsLine);
 
// create a polyline for legs
var legsPolyline = myPanel.createPolyline();
legsPolyline.addPointXY(-20, 70);
legsPolyline.addPointXY(-20, 55);
legsPolyline.addPointXY(0, 0);
legsPolyline.addPointXY(20, 55);
legsPolyline.addPointXY(20, 70);
legsPolyline.setStroke(stroke);
legsPolyline.setZIndex(-1);
myGroup.addElement(legsPolyline);
 
// move the entire group to the panel's center
myGroup.setLocationXY(125,65);

The above code will produce the following result:

Since

version 1.0

clear()

Removes all the elements from the group.

Example

Remove all the lines from the group whenever any of them is clicked:

/* Init the shared stroke object*/
var stroke = new jsgl.stroke.SolidStroke();
stroke.setColor('#f33');
stroke.setWeight(5);
 
/* Create 20 random lines and add them to the group */
for(var i=0; i<20; i++) {
  var line = clearPanel.createLine();
  myGroup.addElement(line);
  line.setStartPointXY(20+210*Math.random(), 20+110*Math.random());
  line.setEndPointXY(20+210*Math.random(), 20+110*Math.random());
  line.setStroke(stroke);
}
 
/* Set the cursor and add appropriate click listener */
myGroup.setCursor(jsgl.Cursor.POINTER);
myGroup.addClickListener(function(eventArgs) {
    myGroup.clear();
  });

See mouse events to get more info on adding interactivity.

Since

version 2.0

containsElement(element: jsgl.elements.AbstractElement) : Boolean

Tests whether the given element is currently present in the group.

Parameters

Name Type Description
element jsgl.elements.AbstractElement The element to be tested for presence.

Returns

Boolean

  • true if the element is currently contained within the group,
  • false if not

Example

var myLine = myPanel.createLine();
window.alert(myGroup.containsElement(myLine));  // shows "false"
 
myGroup.addElement(myLine);
window.alert(myGroup.containsElement(myLine));  // shows "true"
 
myGroup.removeElement(myLine);
window.alert(myGroup.containsElement(myLine));  // shows "false"

Since

version 1.0

getElementAt(index: Number)

Gets an element from the list of elements contained within the group at given index.

The elements in the group are sorted according to the order in which they have been added.

Parameters

Name Type Description
index Number Index of the element to be retrieved.

Example

var myCircle = myPanel.createCircle();
myGroup.addElement(myCircle);
 
var myEllipse = myPanel.createEllipse();
myGroup.addElement(myEllipse);
 
var myRect = myPanel.createRectangle();
myGroup.addElement(myRect);
 
myGroup.removeElement(myPanel.getElementAt(1));  // remove the ellipse

Since

version 1.0

getElementsCount() : Number

Returns

Number

Example

var myGroup = myPanel.createGroup();
window.alert(myGroup.getElementsCount());  // shows "0"
 
var myCircle = myPanel.createCircle();
myGroup.addElement(myCircle);
window.alert(myGroup.getElementsCount());  // shows "1"
 
var myCurve = myPanel.createCurve();
myGroup.addElement(myCurve);
window.alert(myGroup.getElementsCount());  // shows "2"
 
myGroup.clear();
window.alert(myGroup.getElementsCount());  // shows "0"

Since

version 1.0

removeElement(element: jsgl.elements.AbstractElement)

Removes the given element from the group.

If the elements is not contained within the group, calling the method has no effect.

Parameters

Name Type Description
element jsgl.elements.AbstractElement The element to be removed.

Example 1

Remove myLine from the group:

myGroup.removeElement(myLine);

Example 2

Remove an ellipse from the group when it is clicked:

/* Instantiate the group, add it to the Panel's viewport */
var myGroup = myPanel.createGroup();
myPanel.addElement(myGroup);
 
/* Create shared stroke and fill objects */
var stroke = new jsgl.stroke.SolidStroke();
stroke.setColor('rgb(127,31,63)');
stroke.setWeight(3);
var fill = new jsgl.fill.SolidFill();
fill.setColor('rgb(191,191,255)');
 
/* Create some random ellipses */
for(var i=0; i<20; i++) {
  var ellipse = myPanel.createEllipse();
  ellipse.setCenterLocationXY(20+260*Math.random(), 20+160*Math.random());
  ellipse.setSizeWH(15+35*Math.random(), 15+35*Math.random());
  ellipse.setRotation(180*Math.random());
  ellipse.setFill(fill);
  ellipse.setStroke(stroke);
  ellipse.setCursor(jsgl.Cursor.POINTER);
  myGroup.addElement(ellipse);
}
 
/* Provide a source-element-removing click listener
   for the whole group */
myGroup.addClickListener(function(eventArgs) {
    myGroup.removeElement(eventArgs.getSourceElement());
  });

The above code produced the following result. Click an ellipse to remove it:

See mouse events to get more info on adding interactivity.

Since

version 1.0

setX(newX: Number)

Sets the new X-axis translation of the group's inner coordspace within the coordspace of a parent container.

Parameters

Name Type Description
newX Number Real number representing the new X-coordinate of group's inner (0,0) point within the coordspace of the parent container. Measured in pixels.

Example 1

Move the X-axis coordinate of the group to [x=20]:

myGroup.setX(20);

Example 2

Move the X-axis coordinate of the group when the panel is clicked:

myPanel.addClickListener(function(eventArgs) {
    myGroup.setX(eventArgs.getX());
  });
myPanel.setCursor(jsgl.Cursor.W_RESIZE);

The above code may be used to produce the following result. Click the move the group horizontally:

Please refer here to see how to create the group from this example.

See mouse events to get more info on adding interactivity.

Since

version 1.0

setY(newY: Number)

Sets the new Y-axis translation of the group's inner coordspace within the coordspace of a parent container.

Parameters

Name Type Description
newY Number Real number representing the new Y-coordinate of group's inner (0,0) point within the coordspace of the parent container. Measured in pixels.

Example 1

Move the Y-axis coordinate of the group to [x=70]:

myGroup.setX(70);

Example 2

Move the Y-axis coordinate of the group when the panel is clicked:

myPanel.addClickListener(function(eventArgs) {
    myGroup.setY(eventArgs.getY());
  });
myPanel.setCursor(jsgl.Cursor.N_RESIZE);

The above code may be used to produce the following result. Click the move the group vertically:

Please refer here to see how to create the group from this example.

See mouse events to get more info on adding interactivity.

Since

version 1.0

setLocationXY(newX: Number, newY: Number)

Sets the translation of the inner coordspace of the group within the coordspace of a parent container. The translation is given as couple of coordinates.

Parameters

Name Type Description
newX Number Real number representing the X-coordinate of group's inner (0,0) point within the coordspace of the parent container.
newY Number Real number representing the Y-coordinate of group's inner (0,0) point within the coordsoace of the parent container.

Example 1

Set the location of the group to [x=20,y=70]:

myGroup.setLocationXY(20,70);

Example 2

Move the entire group to the point when the panel is clicked:

myPanel.addClickListener(function(eventArgs) {
    myGroup.setLocationXY(eventArgs.getX(), eventArgs.getY());
  });
myPanel.setCursor(jsgl.Cursor.CROSSHAIR);

The above code may be used to produce the following result:

Please refer here to see how to create the group from this example.

See mouse events to get more info on adding interactivity.

Since

version 1.0

setLocation(newLocation: jsgl.Vector2D)

Sets the translation of the inner coordspace of the group within the coordspace of a parent container. The translation is given as a jsgl.Vector2D object.

The object given as parameter is copied, hence further changes in it will not affect the group.

Parameters

Name Type Description
newLocation jsgl.Vector2D The new location of group's inner (0,0) point within the coordspace of the parent container.

Set the location of the group to [x=20,y=70]:

myGroup.setLocationXY(new jsgl.Vector2D(20,70));

Example 2

Move the entire group to the point when the panel is clicked:

myPanel.addClickListener(function(eventArgs) {
    myGroup.setLocation(eventArgs.getLocation());
  });
myPanel.setCursor(jsgl.Cursor.CROSSHAIR);

The above code may be used to produce the following result:

Please refer here to see how to create the group from this example.

See mouse events to get more info on adding interactivity.

Since

version 1.0

getX() : Number

Gets the current X-coordinate of the translation of inner coordspace of the group within the coordspace of a parent container.

Returns

Number – The current X-coordinate of the translation in pixels.

Example

Shift the group 20 pixels right:

myGroup.setX(myGroup.getX()+20);

Since

version 1.0

getY() : Number

Gets the current X-axis translation of the group's inner coordspace within the coordspace of a parent container.

Returns

Number – The current Y-coordinate of the translation in pixels.

Example

Shift the group 10 pixels up:

myGroup.setY(myGroup.getY()-10);

Since

version 1.0

getLocation() : jsgl.Vector2D

Gets the current translation of the inner coordpace of the group within the coordspace of a parent container.

The resulting object is a copy of the Group's internal representation, hence future changes in it will not affect the group.

Returns

Since

version 1.0

See Also

 
group-element.txt · Last modified: 2016/04/08 18:45 by Tomas Rehorek
 
Except where otherwise noted, content on this wiki is licensed under the following license: GNU Free Documentation License 1.3
Driven by DokuWiki Powered by PHP Valid XHTML 1.0 Valid CSS