assets/samples/Samples/InCanvasControlAPI/CS/README_extracted.txt

Application: InCanvasControlAPI
Revit Platform: All
Revit Version: 2020.0
First Released For: 2020.0
Programming Language: C#
Skill Level: Beginning
Category: Basics, Annotation
Type: ExternalCommand and ExternalApplication

Subject: In-Canvas controls
Summary: 
This sample will demonstrate how to create, keep track of and handle clicks on In-Canvas controls.

Classes:.
Autodesk.Revit.UI.TemporaryGraphicsManager
Autodesk.Revit.UI.InCanvasControlData
Autodesk.Revit.UI.ITemporaryGraphicsHandler
Autodesk.Revit.UI.TemporaryGraphicsCommandData

Project Files: 
Application.cs
 It contains an Application which inherits from interface IExternalApplication. On Revit launch, this external application registers a server which handles clicks on controls, and sets up the update event. This class shows the user how to register a server to handle In-Canvas control clicks.
Command.cs
It contains the class Command which inherits from interface IExternalCommand and implements the Execute method. This command creates an In-Canvas control on the next element picked by the user. 
IssueMarker.cs
        
It contains the class IssueMarker, which contains an index of the In-Canvas control it represents, InCanvasControlData with which it was created, and element id that it tracks. This class shows the user how to create an In-canvas control

IssueMarkerTracking.cs 
It contains the class IssueMarkerTracking, which has GetInstance method, SubscribeControl method, GetMarkerByElementId method, GetMarkerByIndex method, RemoveMarkerByElement method, SetSelected and GetSelected methods, and a set of IssueMarkers. The IssueMarkers are added to the map upon creation (using SubscribeControl method)
IssueMarkerTrackingManager.cs 
        
It contains class IssueMarkerTrackingManager, which has a map of Documents and Trackings, GUIDs and Trackings, methods GetTracking, AddTracking, DeleteTracking, ClearTrackings methods.

IssueMarkerUpdater.cs
        
It contains the class IssueMarkerUpdater. The class has an Execute method. Execute method is invoked by OnDocumentChanged event and updates Issue markers' position to match the modified elements'. This class shows the user how to change In-canvas control's position.

IssueSelectHandler.cs
        
It contains the class IssueSelectHandler which inherits from interface ITemporaryGraphicsHandler and implements it. Its implementation of OnClick method calls to issue marker selector with click data's control index and document the control was on. This class shows the user how to handle clicks on In-Canvas controls
IssueMarkerSelector.cs
        
It contains the class IssueMarkerSelector, which has a method SelectControl. This selector changes the image on controls based on which one is selected. This class shows how to change In-canvas control's image.


Description: 
This sample provides following functionalities.
-       
Let user create controls on the position of a selected element.
-       
Let user generate events by clicking on the controls.
-       
The controls follow the elements on the position of which they were created. The controls will be deleted as well when the element is deleted. 

Instructions: 
Open Revit application and open a document, and execute the command.
1.      
Create controls on element position.
a. Execute the command
        
Alternitavely: Click the button, in the tab Add-Ins, in the panel Issues, called "Create issue marker on an element"
b. Click on an element
Expected result: A button - a control - will appear on top of the selected element.

2.      
Move the control
a.      
Create a control with instructions in 1.
b.      
Move the element on which the control was created
Expected result: The updater in this sample will update the control with the new position - it should move on top of the element's new position.

3.      
Delete the control.
a.      
Create a control with instructions in 1.
b.      
Delete the element on which the control was created
Expected result: The updater in this sample will delete the control - it should disappear.


4. Select the control
a. Create a control with instructions in 1.
b. Click on the control.
Expected result: In this sample, clicking the control switches it's image between the two preset bitmaps. A "selected" control will have a different image than the other controls, which will share the same one.There can only be one selected control.