//*************************************************************************
// Method: ImportGraph()
//
/// <summary>
/// Imports edges and vertices from a graph to the edge and vertex
/// worksheets.
/// </summary>
///
/// <param name="sourceGraph">
/// Graph to import the edges and vertices from.
/// </param>
///
/// <param name="edgeAttributes">
/// Array of edge attribute names that have been added to the metadata of
/// the graph's vertices. Can be null.
/// </param>
///
/// <param name="vertexAttributes">
/// Array of vertex attribute names that have been added to the metadata of
/// the graph's vertices. Can be null.
/// </param>
///
/// <param name="clearTablesFirst">
/// true if the NodeXL tables in <paramref
/// name="destinationNodeXLWorkbook" /> should be cleared first.
/// </param>
///
/// <param name="destinationNodeXLWorkbook">
/// NodeXL workbook the edges and vertices will be imported to.
/// </param>
///
/// <remarks>
/// This method creates a row in the edge worksheet for each edge in
/// <paramref name="sourceGraph" />, and a row in the vertex worksheet for
/// each edge.
///
/// <para>
/// For each attribute name in <paramref name="edgeAttributes" /> (if
/// <paramref name="edgeAttributes" /> is not null), a column is added to
/// the edge worksheet if the column doesn't already exist, and the
/// corresponding attribute values stored on the edges are use to fill the
/// column. The same is done for <paramref name="vertexAttributes" /> and
/// the vertex worksheet.
/// </para>
///
/// </remarks>
//*************************************************************************
public void ImportGraph(
IGraph sourceGraph,
String [] edgeAttributes,
String [] vertexAttributes,
Boolean clearTablesFirst,
Microsoft.Office.Interop.Excel.Workbook destinationNodeXLWorkbook
)
{
Debug.Assert(sourceGraph != null);
Debug.Assert(destinationNodeXLWorkbook != null);
AssertValid();
if (clearTablesFirst)
{
NodeXLWorkbookUtil.ClearAllNodeXLTables(destinationNodeXLWorkbook);
}
// Get the required table that contains edge data. GetEdgeTable()
// throws an exception if the table is missing.
EdgeWorksheetReader oEdgeWorksheetReader = new EdgeWorksheetReader();
ListObject oEdgeTable =
oEdgeWorksheetReader.GetEdgeTable(destinationNodeXLWorkbook);
// Get the required columns.
Range oVertex1NameColumnData = null;
Range oVertex2NameColumnData = null;
if (
!ExcelUtil.TryGetTableColumnData(oEdgeTable,
EdgeTableColumnNames.Vertex1Name, out oVertex1NameColumnData)
||
!ExcelUtil.TryGetTableColumnData(oEdgeTable,
EdgeTableColumnNames.Vertex2Name, out oVertex2NameColumnData)
)
{
ErrorUtil.OnMissingColumn();
}
// Import the edges and their attributes into the workbook.
ImportEdges(sourceGraph, edgeAttributes, oEdgeTable,
oVertex1NameColumnData, oVertex2NameColumnData, !clearTablesFirst);
// Populate the vertex worksheet with the name of each unique vertex in
// the edge worksheet.
( new VertexWorksheetPopulator() ).PopulateVertexWorksheet(
destinationNodeXLWorkbook, false);
// Get the table that contains vertex data.
ListObject oVertexTable;
Range oVertexNameColumnData = null;
Range oVisibilityColumnData = null;
if (
!ExcelUtil.TryGetTable(destinationNodeXLWorkbook,
WorksheetNames.Vertices, TableNames.Vertices, out oVertexTable)
||
!ExcelUtil.TryGetTableColumnData(oVertexTable,
VertexTableColumnNames.VertexName, out oVertexNameColumnData)
||
!ExcelUtil.TryGetTableColumnData(oVertexTable,
CommonTableColumnNames.Visibility, out oVisibilityColumnData)
)
{
ErrorUtil.OnMissingColumn();
}
// Import isolated vertices and the attributes for all the graph's
// vertices.
ImportVertices(sourceGraph, vertexAttributes, oVertexTable,
oVertexNameColumnData, oVisibilityColumnData);
}
//*************************************************************************
// Method: GetRequiredTables()
//
/// <summary>
/// Gets the tables required for populating the vertex worksheet.
/// </summary>
///
/// <param name="oWorkbook">
/// Workbook containing the graph data.
/// </param>
///
/// <param name="oEdgeTable">
/// Where the edge table gets stored.
/// </param>
///
/// <param name="oVertexTable">
/// Where the vertex table gets stored.
/// </param>
///
/// <remarks>
/// This method checks for tables and table columns that are required for
/// vertex worksheet population.
///
/// <para>
/// If there is a problem with the workbook, a <see
/// cref="WorkbookFormatException" /> is thrown.
/// </para>
///
/// </remarks>
//*************************************************************************
protected void GetRequiredTables(
Microsoft.Office.Interop.Excel.Workbook oWorkbook,
out ListObject oEdgeTable,
out ListObject oVertexTable
)
{
Debug.Assert(oWorkbook != null);
AssertValid();
// Get the required table that contains edge data. GetEdgeTable()
// checks for the required vertex name columns.
EdgeWorksheetReader oEdgeWorksheetReader = new EdgeWorksheetReader();
oEdgeTable = oEdgeWorksheetReader.GetEdgeTable(oWorkbook);
// Normally, the vertex table isn't required, but to avoid having to
// create the table in code if it's missing, require it here.
if ( ExcelUtil.TryGetTable(oWorkbook, WorksheetNames.Vertices,
TableNames.Vertices, out oVertexTable) )
{
// Make sure the vertex name column exists.
ListColumn oColumn;
if ( !ExcelUtil.TryGetTableColumn(oVertexTable,
VertexTableColumnNames.VertexName, out oColumn) )
{
oVertexTable = null;
}
}
else
{
oVertexTable = null;
}
if (oVertexTable == null)
{
throw new WorkbookFormatException(String.Format(
"To use this feature, there must be a worksheet named \"{0}\""
+ " that contains a table named \"{1}\", and that table must"
+ " contain a column named \"{2}\"."
+ "\r\n\r\n"
+ "{3}"
,
WorksheetNames.Vertices,
TableNames.Vertices,
VertexTableColumnNames.VertexName,
ErrorUtil.GetTemplateMessage()
) );
}
}
//*************************************************************************
// Method: ReadWorkbookInternal()
//
/// <summary>
/// Creates a NodeXL graph from the contents of an Excel workbook.
/// </summary>
///
/// <param name="workbook">
/// Workbook containing the graph data.
/// </param>
///
/// <param name="readWorkbookContext">
/// Provides access to objects needed for converting an Excel workbook to a
/// NodeXL graph.
/// </param>
///
/// <returns>
/// A new graph.
/// </returns>
///
/// <remarks>
/// If <paramref name="workbook" /> contains valid graph data, a new <see
/// cref="IGraph" /> is created from the workbook contents and returned.
/// Otherwise, a <see cref="WorkbookFormatException" /> is thrown.
/// </remarks>
//*************************************************************************
protected IGraph ReadWorkbookInternal(
Microsoft.Office.Interop.Excel.Workbook workbook,
ReadWorkbookContext readWorkbookContext
)
{
Debug.Assert(readWorkbookContext != null);
Debug.Assert(workbook != null);
AssertValid();
if (readWorkbookContext.PopulateVertexWorksheet)
{
// Create and use the object that fills in the vertex worksheet.
VertexWorksheetPopulator oVertexWorksheetPopulator =
new VertexWorksheetPopulator();
try
{
oVertexWorksheetPopulator.PopulateVertexWorksheet(
workbook, false);
}
catch (WorkbookFormatException)
{
// Ignore this type of error, which occurs when the vertex
// worksheet is missing, for example.
}
}
// Create a graph with the appropriate directedness.
PerWorkbookSettings oPerWorkbookSettings =
new PerWorkbookSettings(workbook);
IGraph oGraph = new Graph(oPerWorkbookSettings.GraphDirectedness);
// Read the edge worksheet. This adds data to oGraph,
// ReadWorkbookContext.VertexNameDictionary, and
// ReadWorkbookContext.EdgeIDDictionary.
EdgeWorksheetReader oEdgeWorksheetReader = new EdgeWorksheetReader();
oEdgeWorksheetReader.ReadWorksheet(workbook, readWorkbookContext,
oGraph);
oEdgeWorksheetReader = null;
// Read the vertex worksheet. This adds metadata to the vertices in
// oGraph; adds any isolated vertices to oGraph and
// ReadWorkbookContext.VertexNameDictionary; and removes any skipped
// vertices (and their incident edges) from
// ReadWorkbookContext.VertexNameDictionary,
// ReadWorkbookContext.EdgeIDDictionary, and oGraph.
VertexWorksheetReader oVertexWorksheetReader =
new VertexWorksheetReader();
oVertexWorksheetReader.ReadWorksheet(workbook, readWorkbookContext,
oGraph);
oVertexWorksheetReader = null;
if (readWorkbookContext.ReadAllEdgeAndVertexColumns)
{
// The other worksheets should be ignored.
return (oGraph);
}
if (readWorkbookContext.ReadGroups)
{
// Read the group worksheets. This adds metadata to the vertices
// in oGraph and to oGraph itself.
GroupWorksheetReader oGroupWorksheetReader =
new GroupWorksheetReader();
oGroupWorksheetReader.ReadWorksheet(workbook,
readWorkbookContext, oGraph);
oGroupWorksheetReader = null;
}
// Read the per-workbook settings that are stored directly on the
// graph.
oPerWorkbookSettings.ReadWorksheet(workbook, readWorkbookContext,
oGraph);
return (oGraph);
}
//*************************************************************************
// Method: OnLoad()
//
/// <summary>
/// Handles the Load event.
/// </summary>
///
/// <param name="e">
/// Standard event argument.
/// </param>
//*************************************************************************
protected override void OnLoad(
EventArgs e
)
{
AssertValid();
base.OnLoad(e);
// Get the required edge table before the user does anything in the
// dialog.
EdgeWorksheetReader oEdgeWorksheetReader = new EdgeWorksheetReader();
try
{
m_oEdgeTable = oEdgeWorksheetReader.GetEdgeTable(m_oWorkbook);
}
catch (Exception oException)
{
// The edge table couldn't be found. Tell the user and close the
// dialog.
ErrorUtil.OnException(oException);
this.Close();
return;
}
}
//*************************************************************************
// Method: GetDestinationEdgeTable()
//
/// <summary>
/// Gets the edge table in the destination NodeXL workbook.
/// </summary>
///
/// <param name="oDestinationNodeXLWorkbook">
/// NodeXL Workbook containing the edge table.
/// </param>
///
/// <returns>
/// The edge table.
/// </returns>
//*************************************************************************
protected ListObject GetDestinationEdgeTable(
Microsoft.Office.Interop.Excel.Workbook oDestinationNodeXLWorkbook
)
{
Debug.Assert(oDestinationNodeXLWorkbook != null);
EdgeWorksheetReader oEdgeWorksheetReader = new EdgeWorksheetReader();
return ( oEdgeWorksheetReader.GetEdgeTable(
oDestinationNodeXLWorkbook) );
}
