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.

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);

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

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 = groupPanel.createCircle();
headCircle.setCenterLocationXY(0, -30);
headCircle.setRadius(15);
headCircle.setStroke(stroke);
headCircle.setFill(fill);
myGroup.addElement(headCircle);
 
// create a rectangle for body
var bodyRect = groupPanel.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 = groupPanel.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 = groupPanel.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:

version 1.0

Removes all the elements from the group.

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.

version 2.0

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

Boolean

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

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"

version 1.0

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.

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

version 1.0

Number

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"

version 1.0

Removes the given element from the group.

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

Remove myLine from the group:

myGroup.removeElement(myLine);

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);
  removeGroup.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.

version 1.0

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

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

myGroup.setX(20);

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.

version 1.0

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

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

myGroup.setX(70);

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.

version 1.0

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.

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

myGroup.setLocationXY(20,70);

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.

version 1.0

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.

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

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

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.

version 1.0

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

Number ā€“ The current X-coordinate of the translation in pixels.

Shift the group 20 pixels right:

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

version 1.0

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

Number ā€“ The current Y-coordinate of the translation in pixels.

Shift the group 10 pixels up:

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

version 1.0

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.

jsgl.Vector2D

version 1.0

jsgl.elements.AbstractElement