diff options
19 files changed, 155 insertions, 59 deletions
diff --git a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFBaseContents.java b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFBaseContents.java index ac4c196029..6a872c4499 100644 --- a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFBaseContents.java +++ b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFBaseContents.java @@ -40,7 +40,9 @@ import com.microsoft.schemas.office.visio.x2012.main.PageContentsType; import com.microsoft.schemas.office.visio.x2012.main.ShapeSheetType; /** - * Container of shapes for a page in a visio document + * Container of shapes for a page in a Visio diagram. Shapes are not + * necessarily literal shapes in the diagram, but is the term that is + * used to describe the basic elements that make up a Visio diagram. */ public class XDGFBaseContents extends XDGFXMLDocumentPart { @@ -105,6 +107,7 @@ public class XDGFBaseContents extends XDGFXMLDocumentPart { // /** + * Draws the contents of a page onto a Graphics2D object * * @param graphics */ @@ -128,8 +131,7 @@ public class XDGFBaseContents extends XDGFXMLDocumentPart { public List<XDGFShape> getTopLevelShapes() { return Collections.unmodifiableList(_toplevelShapes); } - - // get connections + public List<XDGFConnection> getConnections() { return Collections.unmodifiableList(_connections); } diff --git a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFCell.java b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFCell.java index 171b68d4f9..f7f3291844 100644 --- a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFCell.java +++ b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFCell.java @@ -31,6 +31,10 @@ import com.microsoft.schemas.office.visio.x2012.main.CellType; * * The various attributes of a Cell are constrained, and are better defined in * the XSD 1.1 visio schema + * + * Values of a cell are often the result of a formula computation. Luckily for + * you, Visio seems to always write the result to the document file, so unless + * the values change we don't need to recompute the values. */ public class XDGFCell { @@ -97,7 +101,10 @@ public class XDGFCell { } } - // returns a length, converts it to inches? + /** + * @param cell + * @return A value converted to inches + */ public static Double parseVLength(CellType cell) { try { return Double.parseDouble(cell.getV()); @@ -116,7 +123,7 @@ public class XDGFCell { } @Internal - CellType getXmlObject() { + protected CellType getXmlObject() { return _cell; } diff --git a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFConnection.java b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFConnection.java index 94374c55cb..cc24a41fca 100644 --- a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFConnection.java +++ b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFConnection.java @@ -19,6 +19,15 @@ package org.apache.poi.xdgf.usermodel; import com.microsoft.schemas.office.visio.x2012.main.ConnectType; +/** + * Represents connections in a Visio diagram. + * + * Note that just because something appears to be visually connected in a + * document does not mean that the user actually connected the elements. It + * turns out there are a lot of ways that a careless user can neglect to + * properly make connections that will not be recorded in the diagram + * in a machine readable way. + */ public class XDGFConnection { // comments on frompart/topart taken from pkgVisio @@ -126,7 +135,11 @@ public class XDGFConnection { return null; } - // see constants above + /** + * The ToPart property identifies the part of a shape to which another + * shape is glued, such as its begin point or endpoint, one of its edges, + * or a connection point. + */ public Integer getToPart() { if (_connect.isSetToPart()) return _connect.getToPart(); diff --git a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFDocument.java b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFDocument.java index 6f1dcbe1d0..dc42fa192d 100644 --- a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFDocument.java +++ b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFDocument.java @@ -44,7 +44,7 @@ public class XDGFDocument { public XDGFDocument(VisioDocumentType document) { - + _document = document; if (!_document.isSetDocumentSettings()) diff --git a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFMaster.java b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFMaster.java index b238234a7d..68c2c86267 100644 --- a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFMaster.java +++ b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFMaster.java @@ -22,13 +22,14 @@ import org.apache.poi.util.Internal; import com.microsoft.schemas.office.visio.x2012.main.MasterType; /** - * Provides the API to work with an underlying master + * Provides the API to work with an underlying master. Typically, each set of + * stencils used in a Visio diagram are found in a separate master for each. */ public class XDGFMaster { private MasterType _master; - private XDGFMasterContents _content; - XDGFSheet _pageSheet = null; + protected XDGFMasterContents _content; + protected XDGFSheet _pageSheet = null; public XDGFMaster(MasterType master, XDGFMasterContents content, XDGFDocument document) { @@ -41,7 +42,7 @@ public class XDGFMaster { } @Internal - MasterType getXmlObject() { + protected MasterType getXmlObject() { return _master; } diff --git a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFMasterContents.java b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFMasterContents.java index d8054a8b2c..a56d1dd1df 100644 --- a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFMasterContents.java +++ b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFMasterContents.java @@ -27,9 +27,12 @@ import org.apache.xmlbeans.XmlException; import com.microsoft.schemas.office.visio.x2012.main.MasterContentsDocument; +/** + * Contains the actual contents of the master/stencil + */ public class XDGFMasterContents extends XDGFBaseContents { - private XDGFMaster _master; + protected XDGFMaster _master; public XDGFMasterContents(PackagePart part, PackageRelationship rel, XDGFDocument document) { diff --git a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFMasters.java b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFMasters.java index 88c5386ff4..fb576ad843 100644 --- a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFMasters.java +++ b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFMasters.java @@ -36,19 +36,22 @@ import com.microsoft.schemas.office.visio.x2012.main.MasterType; import com.microsoft.schemas.office.visio.x2012.main.MastersDocument; import com.microsoft.schemas.office.visio.x2012.main.MastersType; +/** + * A collection of masters (typically stencils) in a Visio document + */ public class XDGFMasters extends XDGFXMLDocumentPart { MastersType _mastersObject; // key: id of master - Map<Long, XDGFMaster> _masters = new HashMap<Long, XDGFMaster>(); + protected Map<Long, XDGFMaster> _masters = new HashMap<Long, XDGFMaster>(); public XDGFMasters(PackagePart part, PackageRelationship rel, XDGFDocument document) { super(part, rel, document); } @Internal - MastersType getXmlObject() { + protected MastersType getXmlObject() { return _mastersObject; } diff --git a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFPage.java b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFPage.java index 3369187671..3bdbd2e1b5 100644 --- a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFPage.java +++ b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFPage.java @@ -31,10 +31,10 @@ import com.microsoft.schemas.office.visio.x2012.main.PageType; */ public class XDGFPage { - PageType _page; - XDGFPageContents _content; - XDGFPages _pages; - XDGFSheet _pageSheet = null; + private PageType _page; + protected XDGFPageContents _content; + protected XDGFPages _pages; + protected XDGFSheet _pageSheet = null; public XDGFPage(PageType page, XDGFPageContents content, XDGFDocument document, XDGFPages pages) { @@ -48,7 +48,7 @@ public class XDGFPage { } @Internal - PageType getXmlObject() { + protected PageType getXmlObject() { return _page; } @@ -72,7 +72,9 @@ public class XDGFPage { return _pages.getPageList().indexOf(this) + 1; } - // height/width of page + /** + * @return width/height of page + */ public Dimension2dDouble getPageSize() { XDGFCell w = _pageSheet.getCell("PageWidth"); XDGFCell h = _pageSheet.getCell("PageHeight"); @@ -84,7 +86,9 @@ public class XDGFPage { Double.parseDouble(h.getValue())); } - // origin of coordinate system + /** + * @return origin of coordinate system + */ public Point2D.Double getPageOffset() { XDGFCell xoffcell = _pageSheet.getCell("XRulerOrigin"); XDGFCell yoffcell = _pageSheet.getCell("YRulerOrigin"); @@ -101,7 +105,9 @@ public class XDGFPage { return new Point2D.Double(xoffset, yoffset); } - // bounding box of page + /** + * @return bounding box of page + */ public Rectangle2D getBoundingBox() { Dimension2dDouble sz = getPageSize(); Point2D.Double offset = getPageOffset(); diff --git a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFPageContents.java b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFPageContents.java index 9bcc60f1d7..70458a5b5a 100644 --- a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFPageContents.java +++ b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFPageContents.java @@ -32,8 +32,8 @@ import com.microsoft.schemas.office.visio.x2012.main.PageContentsDocument; public class XDGFPageContents extends XDGFBaseContents { - Map<Long, XDGFMaster> _masters = new HashMap<Long, XDGFMaster>(); - XDGFPage _page; + protected Map<Long, XDGFMaster> _masters = new HashMap<Long, XDGFMaster>(); + protected XDGFPage _page; public XDGFPageContents(PackagePart part, PackageRelationship rel, XDGFDocument document) { super(part, rel, document); @@ -71,6 +71,9 @@ public class XDGFPageContents extends XDGFBaseContents { } } + /** + * @return Parent page + */ public XDGFPage getPage() { return _page; } diff --git a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFPages.java b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFPages.java index 16ab96157a..ced70aacfb 100644 --- a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFPages.java +++ b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFPages.java @@ -90,7 +90,9 @@ public class XDGFPages extends XDGFXMLDocumentPart { } } - // ordered by page number + /** + * @return A list of pages ordered by page number + */ public List<XDGFPage> getPageList() { return Collections.unmodifiableList(_pages); } diff --git a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFRelation.java b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFRelation.java index ef3edefdbc..afd4fce7fb 100644 --- a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFRelation.java +++ b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFRelation.java @@ -33,7 +33,7 @@ public class XDGFRelation extends POIXMLRelation { public static final XDGFRelation DOCUMENT = new XDGFRelation( "application/vnd.ms-visio.drawing.main+xml", - "http://schemas.microsoft.com/visio/2010/relationships/document", + PackageRelationshipTypes.VISIO_CORE_DOCUMENT, "/visio/document.xml", null); public static final XDGFRelation MASTERS = new XDGFRelation( diff --git a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFShape.java b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFShape.java index fb85dcc349..8af375f515 100644 --- a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFShape.java +++ b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFShape.java @@ -173,8 +173,6 @@ public class XDGFShape extends XDGFSheet { * Shapes that have a 'Master' attribute refer to a specific master in the * page, whereas shapes with a 'MasterShape' attribute refer to a subshape * of a Master. - * - * */ protected void setupMaster(XDGFPageContents pageContents, XDGFMasterContents master) { @@ -295,7 +293,9 @@ public class XDGFShape extends XDGFSheet { return _geometry.get(idx); } - // only available if this is a shape group + /** + * Only available if this shape is a shape group, may be null + */ // -> May be null public List<XDGFShape> getShapes() { return _shapes; @@ -334,7 +334,9 @@ public class XDGFShape extends XDGFSheet { return _masterShape; } - // returns the parent shape of this shape, if its in a subshape + /** + * @return The parent shape if this is a subshape, null otherwise + */ public XDGFShape getParentShape() { return _parent; } @@ -807,14 +809,20 @@ public class XDGFShape extends XDGFSheet { _masterShape != null ? _masterShape._geometry : null); } - // returns a rectangle in local coordinates + /** + * @return rectangle in local coordinates + */ public Rectangle2D.Double getBounds() { return new Rectangle2D.Double(0, 0, getWidth(), getHeight()); } - - // returns bounds as a path in local coordinates - // -> useful if you need to transform to global coordinates - // -> Don't use for 1d objects, fails for infinite line objects + + /** + * @return returns bounds as a path in local coordinates, which is + * userful if you need to transform to global coordinates + * + * @warning Don't use this for 1d objects, and will fail for + * infinite line objects + */ public Path2D.Double getBoundsAsPath() { Double w = getWidth(); @@ -830,7 +838,9 @@ public class XDGFShape extends XDGFSheet { return bounds; } - // returns the path in local coordinates + /** + * @return The outline of the shape in local coordinates + */ public Path2D.Double getPath() { for (GeometrySection geoSection : getGeometrySections()) { if (geoSection.getNoShow() == true) diff --git a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFSheet.java b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFSheet.java index 9032672833..1cc807fdfb 100644 --- a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFSheet.java +++ b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFSheet.java @@ -92,7 +92,11 @@ public abstract class XDGFSheet { return _document; } - // A cell is really just a setting + /** + * A cell is really just a setting + * + * @param cellName The particular setting you want + */ public XDGFCell getCell(String cellName) { return _cells.get(cellName); } diff --git a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFText.java b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFText.java index b29e6a0b41..8b4c30bc8e 100644 --- a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFText.java +++ b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XDGFText.java @@ -52,10 +52,12 @@ public class XDGFText { // is a mixed type) return ((TextTypeImpl) _text).getStringValue(); } - - // these are in the shape coordinate system - // -> See - // https://msdn.microsoft.com/en-us/library/hh644132(v=office.12).aspx + + /** + * These are in the shape coordinate system + * + * @see https://msdn.microsoft.com/en-us/library/hh644132(v=office.12).aspx + */ public Rectangle2D.Double getTextBounds() { double txtPinX = _parent.getTxtPinX(); @@ -73,8 +75,10 @@ public class XDGFText { return new Rectangle2D.Double(x, y, txtWidth, txtHeight); } - // returns bounds as a path in local coordinates - // -> useful if you need to transform to global coordinates + /** + * @return Text bounds as a path in local coordinates, which is useful + * if you need to transform to global coordinates + */ public Path2D.Double getBoundsAsPath() { Rectangle2D.Double rect = getTextBounds(); @@ -90,14 +94,19 @@ public class XDGFText { return bounds; } - - // center of text in local coordinates + + /** + * @return Center of text in local coordinates + */ public Point2D.Double getTextCenter() { return new Point2D.Double(_parent.getTxtLocPinX(), _parent.getTxtLocPinY()); } - // assumes graphics is set properly to draw in the right style + /** + * When calling this to draw text, it assumes graphics is set properly + * to draw in the right style. + */ public void draw(Graphics2D graphics) { String textContent = getTextContent(); diff --git a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XmlVisioDocument.java b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XmlVisioDocument.java index be5730e948..e5589c7aaa 100644 --- a/src/ooxml/java/org/apache/poi/xdgf/usermodel/XmlVisioDocument.java +++ b/src/ooxml/java/org/apache/poi/xdgf/usermodel/XmlVisioDocument.java @@ -28,22 +28,39 @@ import org.apache.poi.POIXMLException; import org.apache.poi.openxml4j.exceptions.OpenXML4JException; import org.apache.poi.openxml4j.opc.OPCPackage; import org.apache.poi.openxml4j.opc.PackagePart; +import org.apache.poi.openxml4j.opc.PackageRelationshipTypes; import org.apache.poi.util.PackageHelper; import org.apache.xmlbeans.XmlException; import com.microsoft.schemas.office.visio.x2012.main.VisioDocumentDocument1; import com.microsoft.schemas.office.visio.x2012.main.VisioDocumentType; +/** + * This is your high-level starting point for working with Visio XML + * documents (.vsdx). + * + * Currently, only read support has been implemented, and the API is + * not mature and is subject to change. + * + * For more information about the visio XML format (with an XSD 1.0 + * schema), you can find documentation at + * https://msdn.microsoft.com/en-us/library/hh645006(v=office.12).aspx + * + * That document lacks in some areas, but you can find additional + * documentation and an updated XSD 1.1 schema at + * https://msdn.microsoft.com/en-us/library/office/jj684209(v=office.15).aspx + * + * Each provides different details, but the SharePoint reference + * has better documentation and is more useful. + */ public class XmlVisioDocument extends POIXMLDocument { - public static String CORE_DOCUMENT = "http://schemas.microsoft.com/visio/2010/relationships/document"; - - XDGFPages _pages; - XDGFMasters _masters; - XDGFDocument _document; + protected XDGFPages _pages; + protected XDGFMasters _masters; + protected XDGFDocument _document; public XmlVisioDocument(OPCPackage pkg) throws IOException { - super(pkg, CORE_DOCUMENT); + super(pkg, PackageRelationshipTypes.VISIO_CORE_DOCUMENT); VisioDocumentType document; @@ -98,7 +115,7 @@ public class XmlVisioDocument extends POIXMLDocument { // // Useful public API goes here // - + public Collection<XDGFPage> getPages() { return _pages.getPageList(); } diff --git a/src/ooxml/java/org/apache/poi/xdgf/usermodel/section/CombinedIterable.java b/src/ooxml/java/org/apache/poi/xdgf/usermodel/section/CombinedIterable.java index 983ee2db77..c42bc34d59 100644 --- a/src/ooxml/java/org/apache/poi/xdgf/usermodel/section/CombinedIterable.java +++ b/src/ooxml/java/org/apache/poi/xdgf/usermodel/section/CombinedIterable.java @@ -23,7 +23,11 @@ import java.util.Map.Entry; import java.util.NoSuchElementException; import java.util.SortedMap; -// iterates over the base and master +/** + * An iterator used to iterate over the base and master items + * + * @param <T> + */ public class CombinedIterable<T> implements Iterable<T> { final SortedMap<Long, T> _baseItems; diff --git a/src/ooxml/java/org/apache/poi/xdgf/usermodel/shape/ShapeVisitor.java b/src/ooxml/java/org/apache/poi/xdgf/usermodel/shape/ShapeVisitor.java index 8d8e6fc743..2e4d89647d 100644 --- a/src/ooxml/java/org/apache/poi/xdgf/usermodel/shape/ShapeVisitor.java +++ b/src/ooxml/java/org/apache/poi/xdgf/usermodel/shape/ShapeVisitor.java @@ -32,15 +32,17 @@ import org.apache.poi.xdgf.usermodel.XDGFShape; */ public abstract class ShapeVisitor { - ShapeVisitorAcceptor _acceptor; + protected ShapeVisitorAcceptor _acceptor; public ShapeVisitor() { _acceptor = getAcceptor(); } - - // is only called on construction of the visitor, allows - // mixing visitors and acceptors - public ShapeVisitorAcceptor getAcceptor() { + + /** + * Is only called on construction of the visitor, allows + * mixing visitors and acceptors + */ + protected ShapeVisitorAcceptor getAcceptor() { return new ShapeVisitorAcceptor() { @Override public boolean accept(XDGFShape shape) { diff --git a/src/ooxml/java/org/apache/poi/xdgf/util/HierarchyPrinter.java b/src/ooxml/java/org/apache/poi/xdgf/util/HierarchyPrinter.java index 8b7ed09629..6b3a9a5a5f 100644 --- a/src/ooxml/java/org/apache/poi/xdgf/util/HierarchyPrinter.java +++ b/src/ooxml/java/org/apache/poi/xdgf/util/HierarchyPrinter.java @@ -30,6 +30,10 @@ import org.apache.poi.xdgf.usermodel.XDGFShape; import org.apache.poi.xdgf.usermodel.XmlVisioDocument; import org.apache.poi.xdgf.usermodel.shape.ShapeVisitor; +/** + * Debugging tool useful when trying to figure out the hierarchy of the + * shapes in a Visio diagram + */ public class HierarchyPrinter { public static void printHierarchy(XDGFPage page, File outDir) diff --git a/src/ooxml/java/org/apache/poi/xdgf/util/VsdxToPng.java b/src/ooxml/java/org/apache/poi/xdgf/util/VsdxToPng.java index 2b23755e25..9ab71ea8cc 100644 --- a/src/ooxml/java/org/apache/poi/xdgf/util/VsdxToPng.java +++ b/src/ooxml/java/org/apache/poi/xdgf/util/VsdxToPng.java @@ -34,6 +34,12 @@ import org.apache.poi.xdgf.usermodel.XmlVisioDocument; import org.apache.poi.xdgf.usermodel.shape.ShapeDebuggerRenderer; import org.apache.poi.xdgf.usermodel.shape.ShapeRenderer; +/** + * Converts a Visio diagram to a PNG file. + * + * As more elements and styles are added/supported the output will get + * better, but it's very rough right now. + */ public class VsdxToPng { public static void renderToPng(XDGFPage page, String outFilename, |