From f03d2b699000b7c71ea26631ab6c4c1373486bb1 Mon Sep 17 00:00:00 2001
From: Mattriks <Mattriks@users.noreply.github.com>
Date: Sat, 5 Oct 2019 11:23:52 +1000
Subject: [PATCH] clip example

---
 docs/src/gallery/properties.md | 18 ++++++++++++++++++
 src/Compose.jl                 |  4 ++--
 src/form.jl                    |  6 ++++++
 src/property.jl                | 12 ++++++++++++
 4 files changed, 38 insertions(+), 2 deletions(-)

diff --git a/docs/src/gallery/properties.md b/docs/src/gallery/properties.md
index f42b485e..0ef64b79 100644
--- a/docs/src/gallery/properties.md
+++ b/docs/src/gallery/properties.md
@@ -21,6 +21,24 @@ img = compose(context(), arrow(), stroke("black"), fill(nothing),
 )
 ```
 
+## [`clip`](@ref)
+
+```@example
+using Colors, Compose
+set_default_graphic_size(14cm,7cm)
+X = rand(10,2)
+colv = HSVA.(range(0,stop=180,length=10), 1, 1, 0.5)
+img = compose(context(units=UnitBox(0,0,2,1)), stroke("black"),
+    (context(), rectangle(), fill(nothing)),
+  (context(), ngon([0.5,1.5],[0.5], [0.4], [10]), fill(nothing), stroke("lightgray")),
+    (context(), xgon(X[:,1],X[:,2],[0.2],[4]), fill(colv)),
+    (context(), xgon(X[:,1].+1,X[:,2],[0.2],[4]), fill(colv),
+        clip(points(ngon(1.5,0.5, 0.4, 10))) )
+)
+```
+
+
+
 ## [`fill`](@ref), [`fillopacity`](@ref)
  
 ```@example
diff --git a/src/Compose.jl b/src/Compose.jl
index 254d8e9b..4deb4fa7 100644
--- a/src/Compose.jl
+++ b/src/Compose.jl
@@ -20,8 +20,8 @@ export compose, compose!, Context, UnitBox, AbsoluteBoundingBox,
        ParentDrawContext, context, ctxpromise, table, set_units!, minwidth, minheight,
        text_extents, max_text_extents, polygon, ngon, star, xgon,
        line, rectangle, circle, arc, sector, ellipse, text, curve, bitmap, 
-       stroke, fill, strokedash, strokelinecap, arrow,
-       strokelinejoin, linewidth, visible, fillopacity, strokeopacity, clip,
+       stroke, fill, strokedash, strokelinecap, arrow, strokelinejoin,
+       linewidth, visible, fillopacity, strokeopacity, clip, points,
        font, fontsize, svgid, svgclass, svgattribute, jsinclude, jscall, Measure,
        inch, mm, cm, pt, px, cx, cy, w, h, hleft, hcenter, hright, vtop, vcenter,
        vbottom, SVG, SVGJS, PGF, PNG, PS, PDF, draw, pad, pad_inner, pad_outer,
diff --git a/src/form.jl b/src/form.jl
index 23102a72..e1cadcc0 100644
--- a/src/form.jl
+++ b/src/form.jl
@@ -790,6 +790,12 @@ function xgon(xs::AbstractVector, ys::AbstractVector, rs::AbstractVector, ns::Ab
     return Form{PrimType}(polyprims, tag)
 end
 
+"""
+    points(x::Compose.Form)
+
+Extract points from a Compose.Form
+"""
+points(x::Compose.Form) = x.primitives[1].points
 
 
 
diff --git a/src/property.jl b/src/property.jl
index 19c46a68..092b8932 100644
--- a/src/property.jl
+++ b/src/property.jl
@@ -259,6 +259,12 @@ const Clip = Property{ClipPrimitive}
 
 clip() = Clip([ClipPrimitive(Array{Vec}(undef, 0))])
 
+
+"""
+    clip(points::AbstractArray)
+
+`clip()` is a property.  Only forms inside the clip shape will be visible.
+"""
 function clip(points::AbstractArray{T}) where T <: XYTupleOrVec
     XM, YM = narrow_polygon_point_types(Vector[points])
     if XM == Any
@@ -273,6 +279,12 @@ function clip(points::AbstractArray{T}) where T <: XYTupleOrVec
     return Clip(typeof(prim)[prim])
 end
 
+
+"""
+    clip(point_arrays::AbstractArray...)
+
+Arguments can be passed in arrays in order to perform multiple clipping operations at once.
+"""
 function clip(point_arrays::AbstractArray...)
     XM, YM = narrow_polygon_point_types(point_arrays)
     VecType = XM == YM == Any ? Vec : Vec{XM, YM}