Language

Selecting Shapes

Frame (Index), No frame                 version:0.3(latest)  

Summary: Selecting a shape by clicking on the shape or selecting multiple shapes by dragging a large rectangle around the shapes. The reliable and precise way of selecting a shape depends on the method to compute in real time where on the shape the mouse is located. =>Mouse position monitor

Class on this page: SelectionLS (LS: Listener) , SelectionListener , SelectionEvent , UnselectableAreas

The operation of selecting shape is as follow:
∙ Click on a shape's boundary. If the shape's boundary is closed, you can select the shape by clicking inside the shape. If the shape is a line, polyline or cubic curve and it's not closed, you have to click on (or near) the line or the curve.
∙ To select multiple shapes at once, drag a large rectangle around the shape.

: The rules for selecting shapes
∙ Click on a already selected shape, then it will be deselected.
∙ If you click on empty space of the canvas, all the selected shapes will be deselected.
∙ Click on a shape with holding down the Shift or Ctrl key, the already selected shapes will remain selected and the clicked shape will be selected.
∙ Click inside a text box, it will be selected and editable (able to input text or delete text). The editable text box is shown by a green frame inside it.
=> User's guide Text box, Editing text
You can click inside a text box in a group object, then the text box will be editable.

1.2 Display of selected shapes
(1) A basic shape and a closed shape (its boundary line/curve is closed)
∙ The selected shape is displayed with the light gray flame called selection box (Figure 1). The selected shape can be moved by dragging the selection box with the mouse.
∙ The square marks and the circle marks on the selection box are resize handles. The square marks are used for resizing the selected shape horizontally and vertically. The circle marks are used for resizing the selected shape diagonally.

Ellipse

Polyline

Text box

Figure 1.The selection box

The square mark is a kind of resize handle and used for dragging the end point of the shape with the mouse.

Lines

Polyline

Cubic curve

Figure 2.The resize handles at the end points and the selection box

• When the mouse is clicked

MousePositionLS.mousePressed -> SelectionLS.mousePressed -> MousePositionLS mouseReleased -> SelectionLS.mouseReleased
-> MousePositionLS mouseClicked -> SelectionLS.mouseClicked

• When the mouse is dragged

MousePositionLS.mousePressed -> SelectionLS.mousePressed -> MousePositionLS mouseDragged -> SelectionLS.mouseDragged ->....................
-> MousePositionLS mouseDragged -> SelectionLS.mouseDragged -> MousePositionLS mouseReleased -> SelectionLS.mouseReleased

Item	Description
1. Monitoring the mouse position	It is important for the selecting operation to know where on the shape the mouse is located. This information is created by the mouse position monitor (MousePositionLS object). The SelectionLS gets this information by the MousePositionLS.getMousePositionInfoForSelection method in real time and performs the selecting operation.
2. Activating and deactivating SelectionLS	The SelectionLS object resides in this application and it is usually active. However, it may do unnecessary operations in the following cases, at that time it must be deactivated. (a) In the process of creating a shape, the mouse must be clicked or dragged on the canvas. If an existing shape is clicked or enclosed in by the dragged rectangle, then the shape will be selected. This is an unnecessary operation for creating a shape. So the SelectionLS must be deactivated while creating a shape. => CreateShapeLS Control flow of creating a shape object Step4 (b)When you edit the text in a text box, you have to click or drag the mouse inside the text box. If the SelectionLS is active at this time, the text box itself or overlapped shapes will be unexpectedly selected or deselected by the mouse operation (=>The rules for selecting shape). This is inconvenient for editing a text, so the SelectionLS must be deactivated inside an editable text box. To do this, the mouse position (X, Y) is always checked whether it is iside an editable text box or not by the inEditableTextArea method.
3. Moving and resizing commands	The commands are usually issued by clicking a button on the tool bar. However, the moving or resizing command must be issued when the mouse button is pressed on the selection box or the resize handle of a selected shape. To do this, the SelectionLS always gets the mouse position from the MousePositionLS, and if the mouse button is pressed on the selection box or the resize handle, then the SelectionLS issues the moving or resizing command by the prepareMoveResizeCommand method.

Field	Description
listenerList	protected EventListenerList listenerList = new EventListenerList(); A list storing the SelectionListeners.
popupTrigger (static)	public static boolean popupTrigger This field stores the return value of the isPopupTrigger method of java.awt.event.MouseEvent. =>Getting PopupTrigger If the this field is true, the SelectionLS launches the popup menu after selecting a shape. =>Popup Menu Triggers popup menu
clicked	boolean clicked This field is referred by the mouseEventCompleted method of this class. When a mouse event occurs and the methods - the mousePressed, mouseReleased, and mouseClicked - have finished, true is set to this field.
clickedPoint	public Point2D clickedPoint This field stores the mouse clicked position. This field is referred in the execSelection method and set to the parameter of the sendResult method.
draggedRectangle	Rectangle2D draggedRectangle The dragged rectangle. This field is passed to the execSelection method as the parameter and referred in the drawDraggedRectangle method to draw the border of the dragged rectangle dynamically.
startPoint	Point2D startPoint This field stores the start point of mouse dragging.
endPoint	Point2D endPoint This field stores the current or end point of mouse dragging.
ctrl	private int ctrl ctrl=2: the mouse button 2 was pressed. ctrl=3: the mouse button 3 was pressed. This field is referred in the execSelection method.

Method	Description
start	public void start() Calls the activateListener method of this class to register the SelectionLS to the ListenerPanel as a MouseListener and MouseMotionListener.
end	public void end() ∙ Calls the activateListener method with the parameter as false to remove the SelectionLS from ListenerPanel. ∙ Clears the following fields: this.draggedRectangle=null; this.startPoint=null; this.endPoint=null; this.clickedPoint=null;
isMouseListener	boolean isMouseListener(MouseListener listener) Inquires whether this object is registered to the ListenerPanel or not.
isMouseMotionListener	public boolean isMouseMotionListener(MouseMotionListener listener) Inquires whether this object is registered to the ListenerPanel or not.
activateListener	private void activateListener(boolean activate) If the activate parameter is true, this method registers this object to the ListenerPanel as a MouseListener and MouseMotionListener. If the activate parameter is false, this method removes this object from the ListenerPanel.
addSelectionListener	public void addSelectionListener(SelectionListener listener) Adds the specified SelectionListener object to the listenerList for receiving a SelectionEvent from the SelectionLS when shapes are selected in the SelectionLS.
removeSelectionListener	public void removeSelectionListener(SelectionListener listener) Remove a SelectionListener object from the listenerList.
removeSelectionListener	public void removeSelectionListener() Remove all the SelectionListener object from the listenerList.
fireEvent	public void fireEvent(SelectionEvent event) Reports a SelectionEvent to the objects registered in the listenerList when shapes are selected in the SelectionLS.
mousePressed	public void mousePressed(MouseEvent e) ∙ Stores the return value of the isPopupTrigger method of the e (MouseEvent ) to the static field popupTrigger. =>Getting PopupTrigger ∙ If the mouse right button was pressed, then 2 or 3 is set to the ctrl. ∙ If the mouse button was pressed on a selection box or a resize handle, then calls the prepareMoveResizeCommand method. =>Important items Moving and resizing commands
mouseDragged	public void mouseDragged(MouseEvent e) Creates the current dragged rectangle and stores it to the draggedRectangle. The current dragged rectangle will be drawn with a dotted line by the drawDraggedRectangle method.
mouseReleased	public void mouseReleased(MouseEvent e) ∙ Stores the return value of the isPopupTrigger method of the e (MouseEvent) to the static field popupTrigger. =>Getting PopupTrigger ∙ The dragged rectangle is determined finally, then calls the execSelection method as follow. if(this.draggedRectangle!=null) execSelection(ctrl, this.draggedRectangle);
mouseClicked	public void mouseClicked(MouseEvent e) ∙ Checks whether the Shift/Ctrl key was held down at the mouse click ornot . ∙ Calls prepareClickedPointCommand method of this class. ∙ Calls execSelection method of this class to select shapes. ∙ Launching a popup menu If the static field popupTrigger and the static field MousePositionLS.popupTrigger are both true, then calls the ExecPopupMenu.show method to launch a popup menu. => Popup Menu Triggering popup menu
mouseEntered	public void mouseEntered(MouseEvent e) Nothing is done.
mouseExited	public void mouseExited(MouseEvent e) Nothing is done.
mouseMoved	public void mouseMoved(MouseEvent e) Nothing is done.
inEditableTextArea	private boolean inEditableTextArea(double X, double Y) It is judged whether the point (X, Y) is located in an editable text box. If so, no shape can be selected by the clicked point (X, Y). The editable text box can be retrieved by the ContainerManager.getEditableTextBox method.
drawDraggedRectangle	public void drawDraggedRectangle(Graphics g) This method is called from the DrawPanel.paint method for drawing the dragged rectangle (given by the field of the draggedRectangle) with dotted line.
execSelection	public void execSelection(int ctrl, Rectangle2D draggedRectangle) Parameters: ctrl - If ctrl>0, this method selects a shape without deselecting the already selected shapes. If the mouse was clicked or dragged with holding down Shift/Ctrl key, 1 or 2 is set to ctrl. draggedRectangle - The dragged rectangle which encloses the selected shapes. If the selecting a shape is done by the mouse click, the draggedRectangle is null. Processing: This method is called from the mouseClicked and mouseReleased methods and it selects a shape or shapes according to the rules (=>Operation) (1) Opens the Shape tab (User's Guide Shape tab) by calling the setSelectedIndex method of the javax.swing.JTabbedPane. (2) The case that the draggedRectangle parameter isn't null. Calls the selectInDraggedArea method and retrieves the selected shapes from its returned array of the MousePositionInfo objects. : To select or deselect the shape, calls the ShapeContainer.setSelected method. shapeContainer.setSelected(true/false); (3) The case that the draggedRectangle parameter is null. Calls the getMousePositionInfoForSelection method of the MousePositionLS and retrieves the selected shape from the returned MousePositionInfo object . (4)Calls the PaintStyle.setPaintStyleToMenu static method at the end of this method. The PaintStyle object represents the attributes of the selected shapes such as color, line width, line stroke. The above static method changes the appearance of the corresponding menu components on the tool bar. (5)Calls the FontStyle.setFontStyleToMenu static method at the end of this method. The FontStyle object represents the attributes of the selected styled characterts such as font family, font size, bold, italic, underline, suprtscript/subscript and color. The above static method changes the appearance of the corresponding menu components on the tool bar.
execSelectionByDrag	public void execSelectionByDrag(int ctrl, Rectangle2D draggedArea) Parameters: ctrl - If ctrl>0, this method selects a shape without deselecting the already selected shapes. If the mouse was dragged with holding down Shift/Ctrl key, 1 or 2 is set to ctrl. draggedRectangle - The dragged rectangle which encloses the selected shapes. If the selecting a shape is done by the mouse click, the draggedRectangle is null. Processing: This method is called from the mouseReleased methods. (1) Calls the selectInDraggedArea method and gets the array of the MousePositionInfo objects. (2) According to the selection rules (Operation), this method performs the selection procedure for the shapes in the MousePositionInfo objects.
selectInDraggedArea	private MousePositionInfo[] selectInDraggedArea(Rectangle2D draggedRectangle) Returns: The array of the MousePositionInfo objects which represent the selected shapes. Processing: This method is called from the above execSelectionByDrag method. Select the shape objects which lies inside the draggedRectangle and return the MousePositionInfo array which represent the selected shape objects.
execSelectionByClick	public void execSelectionByClick(int ctrl) Parameters: ctrl - If ctrl>0, this method selects a shape without deselecting the already selected shapes. If the mouse was clicked with holding down Shift/Ctrl key, the ctrl is 1 or 2. Processing: This method is called from the mouseClicked method and it selects a shape or shapes according to the rules (=> Operation) (1) Gets the MousePositionInfo objects by the MousePositionLS.getMousePositionInfoForSelection method. If no MousePositionInfo object exists, then deselects all the selected shapes. In general the returned MousePositionInfo objects are multiple and they are stored in the array in the order of high priority. (2) Selects the MousePositionInfo object of the highest priority and performs the selection procedure for the shape retrieved from the MousePositionInfo object. If the clicked point is inside a text box, then makes the text box editable by calling the selectTextBox method. (3) Creates a SelectionEvent and sends the event to the objects implementing the SelectionListener interface by the fireEvent method.
selectTextBox	private void selectTextBox(ShapeContainer selectedContainer, MousePositionInfo info, int ctrl) This method is called by the execSelection method. Parameters: selectedContainer - The ShapeContainer of the selected shape object which has a text box. info - Used for getting the clicked point from the parameter info (MousePositionInfo) and passes it to the ShapeContainer.makeTextBoxEditable method to set the cursor(caret) position in the text box. ctrl - If the mouse was clicked with holding down Shift/Ctrl key, the ctrl is 1/2.
selectAll	public void selectAll(boolean select) Selects/deselect all the shape objects on the canvas. This method is called by the ExecCommand.
prepareMoveResize Command	public void prepareMoveResizeCommand(MousePositionInfo mouseInfo, MouseEvent e) This method is called from the mousePressed method, when the mouse button was pressed on a selection box or a resize handle. This method generates a MOVE or RESIZE command and calls the ExecCommand.exec method for command dispatch.
prepareClickedPoint Command	public void prepareClickedPointCommand(Point2D point) This method is called by the mouseClicked method. This method generates the CLICKEDPOINT command and calls the exec method of the ExecCommand for command dispatch. : The clicked point is stored to the clickedPoint field of the ExecCommand. Currently the clickedPoint is referred to specify the paste position of selected objects before pasting them.
mouseEventCompleted	public boolean mouseEventCompleted() Inquires whether or not the methods of this class - mousePressed, mouseDragged, mouseReleased and mouseClicked - have all finished. This method is called from this class and MousePositionLS class.
allMouseEventCompleted	public boolean allMouseEventCompleted() Returns: True if the mouseEventCompleted method of this class and the same method of the MousePositionLS both returns true. => Popup Menu Triggers popup menu

The note about the isPopupTrigger method of java.awt.event.MouseEvent is described in the Java Platform Standard Ed. 6 as follow:

Popup menus are triggered differently on different systems. Therefore, isPopupTrigger should be checked in both mousePressed and mouseReleased for proper cross-platform functionality.

So, the following two lines are needed in the mousePressed and mouseReleased methods. Here the popupTrigger is the static field of the SelectionLS.

This class was abolished because the unselectable area is limited to the text area inside an editable text box, so it can be substituted by a simple method such as inEditableTextArea.

Method	Description
covers	public boolean covers(double X, double Y) If (X,Y)-point is inside the unselectable areas, then return true.
covers	public boolean covers(double X, double Y, String message) If (X,Y)-point is inside the unselectable areas, then return true.
getShapes	public Shape[] getShapes() Get all unselectable areas from the areaList and return them as the objects of Shape class.
setUnselectableAreas	public void setUnselectableAreas() Registers unselectable areas to the typeList and areaList. Currently the unselectable area is an area inside an active(editable) text box. So get the unselectable area by the ContainerManager.getEditableTextBox method. : This method is called from the SelectionLS.execSelection, because whether an editable text box exists or not is decided in the process of selecting a text box.
clearUnselectableAreas	public void clearUnselectableAreas() Clear the typeList and areaList. : This method is called from the SelectionLS.resetSelectionLS and the resetSelectionLS method is called from PageManager.
toString	public String toString() Return the string representing this object.