Shopping List Sync Application


Table of contents

Programming with semantic pointing

The shopping list application source code includes the “pointing” package that can be used to implement semantic pointing in other Sync application. The pointing package manages storing information identifying collaborators and the objects collaborators point at. A developer still has to implement how pointing is realized in the interface, such as coloring the objects pointed at.

The package does not need to be modified. To apply semantic pointing, integrate pointing object and control in a Sync shared model. 


// PointListModel.java

	private Pointer pointer = new Pointer(); // must have init value for Sync

	public pointing.Pointer getPointer() {
		return pointer;
	}

	public void setPointer(pointing.Pointer pt) {
		// Nothing for Sync
	}

Furthermore, there are three components to semantic pointing.

1. Identify collaborators

Identifying collaborators is important to distinguish who is pointing at which items. Each collaborator is identified by a unique ID. The pointing system stores an object for each collaborator. The object data is used to store the characteristics used in the interface to identify a collaborator. In the Shopping List application the collaborator’s data is stored in the UserPoint Data class and it stores the color used to highlight objects pointed at.

A user’s pointing data are created when the user’s interface and unique ID are created.

// PointListGui.java

	public void init(PointListModel m){
		model = m;
		model.addPropertyChangeListener(mcl);
		model.addPointerListner(this);
		
		viewID = "viewID_"+ PointListModel.generateGlobalID();
		user = model.regUserPoint(viewID); // Related to pointing
		
	}


The following API is used to access information about collaborators’ user data:

Method, see PointListModel.java
 Description
 
public String[] pointUserIDs()
 Get all user IDs
 
public void unRegUserPoint(String viewID)
 Remove user
 
public UserPointData userData(String viewID)
 Get user's data


2. Pointing at items

There are 3 steps for a collaborator to point at items in the shared model. The collaborator selects the items to point at and issues the pointing command. The developer then
1.    Issues the command to clear the last selection. (Could be used independently to clear items pointed at)
2.    Mark the items pointed at. The mark can be arbitrarily set to enable pointing for different purposes. The default is to use the POINTING type.
3.    Trigger the signal to notify other collaborators that a new set of items is pointed at. 

// PointListTreeView.java 

	public void pointSelection(){
		
		model.pointAction(viewID, Pointer.POINT_POINTING, Pointer.POINT_ACTION_CLEAR); // step 1
		
		TreeItem[] items = tree.getSelection();
		for(int i=0; i<items.length; i++) {
			String uniqueID = (String) items[i].getData();
			model.pointAddItem(viewID, uniqueID, Pointer.POINT_POINTING); // step 2
		}
		
		model.pointAction(viewID, Pointer.POINT_POINTING, Pointer.POINT_ACTION_MARK); // step 3
	}


3. Notifying clients

When a collaborator points at items, other collaborators’ interfaces are notified and can highlight the items pointed at (see pointAt method). Notification is through the PointerListener interface. The GUI, PointListGUI class, implements the interface and listens for the notification. The notification includes the unique ID of the user pointing and the type of pointing. If the type of pointing is to clear the selection, the PointListGUI class has to remember the highlighted items to clear them later. 

// PointListGui.java implements PointerListener interface

	// Pointing action hanppened 
	public void triggeredAction(String viewID, int pointType, int pointAction) {
		// Update the interface, call pointAt in PointListTreeView.java 	
	}

// PointListTreeView.java 

	public void pointAt(String viewID, int pointType, int pointAction) {

		if (pointAction == Pointer.POINT_ACTION_CLEAR) {
			clearPointSelection(viewID);
		} else { // Pointer.POINT_ACTION_MARK

			Object[] listItemIDs = model.pointMarkers(viewID, pointType);

			currentPointers.put(viewID, listItemIDs); // store items so items can be cleared later
			markPointSelection(viewID, listItemIDs);
		}
	}

Dorian Miller Aug 27, 2006