insertVertex needs a relative option, or an insertRelativeVertex function.

In the example code, when inserting a relative vertex, the code is something like this:

  var label13 = graph.insertVertex(v1, null, '0603', 0.5, 1.0, 0, 0);\n  label13.geometry.relative =true;\n

While tracking though the mxGraph logic, I found that there are some issues with this code. The logic inside of the mxGraph library compares the new vertex x,y, width and height values against the parent container. If they fall outside of the container, they are truncated to be inside of the container. Now, since the values are relative, they are in completely different coordinate system, i.e. a range from 0 to 1, NOT x,y position values. So, essentially, if the intended vertex is to be relative, these initial comparisons are just wrong. They "work" in most cases..but not all, and the 'reasons' they work or don't work are not clear until you dig deep into the logic (like I did).

For example,

  var label13 = graph.insertVertex(v1, null, '0603', 0.5, 1.5, 0, 0);\n  label13.geometry.relative =true;\n

The previous code example "works" because vertex v1 geometry.y + geometry.width is most likely greater than 1.5, even though that comparison is bogus. This allows you to place a relative value below (or to the right) of a parent vertex.

  var label13 = graph.insertVertex(v1, null, '0603', 0.5, -0.5, 0, 0);\n  label13.geometry.relative =true;\n

This code example does NOT work, since, a negative value is outside of the range of the parent. The value is truncated to 0, hence putting the relative cell on the to edge of the parent, not what is intended.

The 'workaround' is something like this:

    var label13 = graph.createVertex(v1, null, '0603', 0.5, -1.0, 0, 0);\n    label13.geometry.relative =true;\n    graph.addCell(label13,v1);\n

This works, because the above checks occur during the addCell call (but, much deeper in the library). The checks are done differently if the geometry is relative. We cannot really use insertVertex, since it does the create, and add together, and always assumes non-relative coordinates. There is no way to specify relative coordinates before the addCell call.

A relative option would be nice, or, a new function that takes relative parameters. At any rate, the examples should not use insertVertex with a subsequent adjustment of the geometry.relative = true, since this isn't (from my analysis) correct.

Cheers.