summaryrefslogtreecommitdiffstats
path: root/src/display/control/README
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--src/display/control/README112
1 files changed, 112 insertions, 0 deletions
diff --git a/src/display/control/README b/src/display/control/README
new file mode 100644
index 0000000..680f0bf
--- /dev/null
+++ b/src/display/control/README
@@ -0,0 +1,112 @@
+
+This directory contains code for handling on-canvas editing objects as
+well as document display.
+
+Historically, the code originates from GnomeCanvas but at this point it
+has been completely rewritten for Inkscape's needs.
+
+One can think of a CanvasItem as a light-weight widget. There is a
+selection mechanism based on an item's position and a method to handle
+events. The selection mechanism is currently very simplistic,
+selecting the top-most item whose bounding box contains the
+cursor. Probably as a result, many items do not use these capabilities
+with external code replacing this functionality (e.g CanvasItemQuad,
+CanvasItemCurve).
+
+Points are stored as document coordinates. They are converted to
+screen coordinates by multiplying by the document to window affine.
+When an object's geometry changes, it must call request_update() to
+flag that its bounds need to be recalculated (_need_update =
+true). This will also cause all ancestors to also be marked and
+finally the Canvas. Before picking or drawing, all bounds must be
+up-to-date. (Changing the Canvas affine will also require bounds to be
+recalculated.) This mechanism ensures that bounds are correct in the
+most efficient manner. If only the style is changed (without geometric
+ramifications) then call canvas->redraw_area() to trigger a redraw.
+
+CanvasItemGroup keeps a list of child items using a Boost intrusive
+list. The pointers between nodes are kept inside the items. This
+allows for quick deletion by avoiding the need to search through the
+list to find the item to delete. This is important when a path
+contains hundress of nodes. However, a Boost intrusive list cannot be
+used with C++ smart pointers. Deleting an item can be done by either
+calling CanvasItemGroup::remove(CanvasItem*) or by directly deleting
+the item. Deleting a CanvasItemGroup will delete it and all of its
+children.
+
+
+Contents (x == pickable):
+
+* CanvasItem: Abstract base class.
+* CanvasItemBPath: x An item representing a Bezier path.
+* CanvasItemCatchall: x An infinite item, for capturing left-over events.
+* CanvasItemCtrl: x An item representing a control point (knot, node, etc.).
+* CanvasItemCurve: A single Bezier curve item (line or cubic). Not pickable!
+* CanvasItemDrawing: x The SVG drawing.
+* CanvasItemGrid: Base class for snapping grids.
+* CanvasItemGroup: x An item that contains other items.
+* CanvasItemGuideline: x A guideline for snapping.
+* CanvasItemQuad: An object defined by four points (only used by Text tool).
+* CanvasItemRect: An axis aligned rectangle item.
+* CanvasItemRotate: x For previewing the rotation of the canvas.
+* CanvasItemText: A text item.
+
+* CanvasItemEnum: All the enums you'll want to use!
+* CanvasItemBuffer: A class that wraps a Cairo buffer for drawing.
+
+Classes here that use CanvasItem's:
+
+* CanvasGridXY: A Cartesian grid for snapping.
+* CanvasGridAxonom An Axonometric grid for snapping.
+* SnapIndicator: A class for showing a snap possibility on canvas.
+* TemporaryItem: A class to manage the lifetime of a temporary CanvasItem.
+* TemporaryItemList: A class to track TemporaryItem's.
+
+
+Notes:
+
+CanvasItemCtrl (a.k.a. "Node", "Knot", "Handle", "Dragger", "Ctrl", "Mouse Grab", "Control Point")
+
+ Used by several groups of classes:
+
+ * Knot
+ ** KnotHolderEntity
+ *** live_effects/...
+ *** KnotHolder: Contains one or more KnotHolderEntity's.
+ Example: an object's fill and stroke gradients could have
+ overlapping knot-entities and are moved together via the knot holder.
+ **** shape-editor-knotholders.cpp
+ Classes derived from KnotHolder which contain classes derived from KnotHolderEntity for
+ editing shapes.
+ **** ShapeEditor contains two KnotHolders, one for shapes, one for LPE's.
+
+ ** ui/tools/tool-base.h
+ ** seltrans.h,.cpp
+ ** display/snap-indicator.h
+ ** gradient-drag.cpp
+ ** vanishing-point.h
+
+
+ * ControlPoint, SelectorPoint, SelectableControlPoint, Handle, Node, CurveDragPoint, TransformHandle, plus
+ auxiliary classes (manipulator...).
+ * drag-anchor
+ * pen-tool
+ * measure-tool
+ * guide-line
+ * snap-indicator
+
+
+TODO:
+
+Move files that use CanvasItem's to more appropriate places.
+
+All files that use CanvasItem's in src directory:
+* Move rubberband.h/.cpp to src/ui
+* Move gradient-drag to src/ui
+* Move selcue* to src/ui
+* Move seltrans* to src/ui
+* Move vanishing-point to src/ui
+* Move snap code to src/ui/snap display/snap-indicator.h/.cpp snap.h etc.
+
+See also src/ui/tool and src/ui/knot.
+