CPSC 581/599.81
Interaction Design

Documentation for the Groupware Radar Overview

The Radar Overview combines the use of two ActiveX controls. The first control, a drawing canvas, provides information to a second control which is the actual radar overview. The radar overview control can work independant of the drawing canvas, provided it receives enough information from the main collaboration workspace.

Both controls require the use of a Shared Dictionary component provided by the University of Calgary's GroupLab.

Drawing Canvas API

The control consists of a simple picture box which receives the user's actions and notifies a shared dictionary. Most of the API is used in the creation of a user's rectangle within the radar overview.

Properties

Name Description

Picture as String The filename of a picture used to display in the radar overview. The picture should correspond to the person using the drawing canvas. The picture currently must be located in the path of the application. Future versions will allow the use of a picture in any location.

Privacy as Integer A representation for the level of privacy a particular user wants for their current workspace. It maps to the person's space rectangle in the overview.

0=no privacy, transparent overview rectangle
1=somewhat private, diagonal lines in overview rectangle
2=more privacy, crossed lines in overview rectangle
3=completely private, opaque overview rectangle

Notify the shared dictionary with a value of 5.

Colour as Integer The colour of the lines drawn by the user in their workspace and overview, as well as the colour of their telepointer in the overview.

0=red
1=blue
2=green
3=yellow

ViewableHeight as Integer The height of a user's workspace which correlates to the height of a user's rectangle in the overview. Twips are used as the units of measurement.

ViewableWidth as Integer The width of a user's workspace which correlates to the width of a user's rectangle in the overview. Twips are used as the units of measurement.

XLocation as Integer The current X position of the user's workspace (top left corner). This corresponds to the X position of the user's rectangle in the overview. Twips are used as the units of measurement. Notifies the shared dictionary with a value of 4.

YLocation as Integer The current Y position of the user's workspace (top left corner). This corresponds to the Y position of the user's rectangle in the overview. Twips are used as the units of measurement. Notifies the shared dictionary with a value of 4.

BaseKey as String The base key used for a shared dictionary instance. It is not used in the sample program.

DictionaryName as String The name of a shared dictionary to connect to. Default="ShDict"

DictionaryLocation as String The hostname of the machine running the shared dictionary server. Default="localhost"

Methods

Name Description

ConnectToDictionary() As Variant Connects to a shared dictionary named by DictionaryName on a machine specified in DictionaryLocation.

CloseConnection() As Variant Closes a connection to a shared dictionary and removes its entries in the dictionary. Must be called before termination of the main application.

Events

These events occur within the control and are not accessible by the main application.

Name Description

MouseDown(Button As Integer, Shift As Integer, X As Single, Y As Single) Used for drawing of lines. Notifies shared dictionary with value of 2 that a line has been started with the corresponding mouse coordinates.

MouseMove(Button As Integer, Shift As Integer, X As Single, Y As Single) Used for drawing of lines and the changing of a telepointer's position in the overview. Notifies shared dictionary with value of 1 for drawing lines and value of 3 for just mouse movement.

MouseUp(Button As Integer, Shift As Integer, X As Single, Y As Single) Used for drawing of lines. Ends the drawing of a line and removes it from the shared dictionary.

Radar Overview API

The control consists of a simple picture box to represent the entire shared workspace. For each user, a new rectangle is loaded at runtime to show the user's current workspace state and present information about the user. Each rectangle contains an image box to hold the user's picture and a rectangle around the image box to act as a colour representation border. A telepointer shape is also loaded for each new user at runtime.

The radar overview receives information about each drawing canvas from the shared dictionary when it loads. Its subscriptions in a shared dictionary include:

/shdictcanvas/change - which represents a change in the shared workspace such as new lines drawn

/mouse/change - which represents a change in a user's mouse position

/location/change - which represents a change in a user's workspace view

/privacy/change - which represents a change in a user's privacy level

Note: The first instance of a Radar Overview should act as a server and have the ClientORServer parameter set as "Server"

Properties

Name	Description
ClientORServer as String	Whether or not the overview should act as a client or server. If this property = "Client" then it connects to a shared dictionary specified by DictionaryName on the machine specified by DictionaryLocation. If this property = "Server" then it creates a new shared dictionary named by DictionaryName.
ScaleX as Integer	The ratio of the width of a user's workspace to the width of the overview. Used for scaling mouse movements and other actions from each user's workspace.
ScaleY as Integer	The ratio of the height of a user's workspace to the height of the overview. Used for scaling mouse movements and other actions from each user's workspace.
BaseKey as String	The base key used for a shared dictionary instance. It is not used in the sample program.
DictionaryName as String	The name of a shared dictionary to connect to. Default="ShDict"
DictionaryLocation as String	The hostname of the machine running the shared dictionary server. Default="localhost"

Methods

Name	Description
ConnectToDictionary() As Variant	Connects to a shared dictionary named by DictionaryName on a machine specified in DictionaryLocation. It notifies all drawing canvases with the value of 7 that it has been loaded. Each drawing canvas must then notify it with the value of 6 so that it may create rectangles for all users.
CloseConnection() As Variant	Closes a connection to a shared dictionary. Must be called before termination of the main application.

Shared Dictionary Notifications (Received)

Value	Description
6	New drawing canvas (new user). Creates rectangle for new user and loads picture and telepointer.
5	Change in privacy level. Adjusts the fill style of a user's rectangle to reflect the privacy.
4	Change in location of a user's view. Adjusts position of a user's rectangle.
3	Movement of a user's telepointer. Adjusts the position of a user's telepointer.
2 and 1	Line drawn by user. Creates a scaled line in the overview.

Name	Description
Picture as String	The filename of a picture used to display in the radar overview. The picture should correspond to the person using the drawing canvas. The picture currently must be located in the path of the application. Future versions will allow the use of a picture in any location.
Privacy as Integer	A representation for the level of privacy a particular user wants for their current workspace. It maps to the person's space rectangle in the overview. 0=no privacy, transparent overview rectangle 1=somewhat private, diagonal lines in overview rectangle 2=more privacy, crossed lines in overview rectangle 3=completely private, opaque overview rectangle Notify the shared dictionary with a value of 5.
Colour as Integer	The colour of the lines drawn by the user in their workspace and overview, as well as the colour of their telepointer in the overview. 0=red 1=blue 2=green 3=yellow
ViewableHeight as Integer	The height of a user's workspace which correlates to the height of a user's rectangle in the overview. Twips are used as the units of measurement.
ViewableWidth as Integer	The width of a user's workspace which correlates to the width of a user's rectangle in the overview. Twips are used as the units of measurement.
XLocation as Integer	The current X position of the user's workspace (top left corner). This corresponds to the X position of the user's rectangle in the overview. Twips are used as the units of measurement. Notifies the shared dictionary with a value of 4.
YLocation as Integer	The current Y position of the user's workspace (top left corner). This corresponds to the Y position of the user's rectangle in the overview. Twips are used as the units of measurement. Notifies the shared dictionary with a value of 4.
BaseKey as String	The base key used for a shared dictionary instance. It is not used in the sample program.
DictionaryName as String	The name of a shared dictionary to connect to. Default="ShDict"
DictionaryLocation as String	The hostname of the machine running the shared dictionary server. Default="localhost"

Name	Description
MouseDown(Button As Integer, Shift As Integer, X As Single, Y As Single)	Used for drawing of lines. Notifies shared dictionary with value of 2 that a line has been started with the corresponding mouse coordinates.
MouseMove(Button As Integer, Shift As Integer, X As Single, Y As Single)	Used for drawing of lines and the changing of a telepointer's position in the overview. Notifies shared dictionary with value of 1 for drawing lines and value of 3 for just mouse movement.
MouseUp(Button As Integer, Shift As Integer, X As Single, Y As Single)	Used for drawing of lines. Ends the drawing of a line and removes it from the shared dictionary.