#134: Legend fill whitespace with SHOW_LEGEND_UP(), ..._DOWN(), ..._LEFT(), ..._RIGHT()

C4.puml

@@ -36,6 +36,13 @@ skinparam LegendBorderColor transparent
 skinparam LegendBackgroundColor transparent
 skinparam LegendFontColor $LEGEND_FONT_COLOR
 
+skinparam shadowing<<legendArea>> false
+' #00000000 is transparent
+skinparam rectangle<<legendArea>> {
+    backgroundcolor #00000000
+    bordercolor #00000000
+}
+
 skinparam rectangle {
     StereotypeFontSize 12
     shadowing false
@@ -497,6 +504,25 @@ SetPropertyHeader("Property","Value")
 ' Layout
 ' ##################################
 
+!procedure $getHideStereotype($hideStereotype) 
+!if ($hideStereotype=="true")
+hide stereotype
+!endif
+!endprocedure
+
+!procedure $getLegendTable() 
+<#00000000,#00000000>|<color:$LEGEND_TITLE_COLOR>**Legend**</color> |
+$showActiveLegendEntries($tagDefaultLegend)
+$showActiveLegendEntries($tagCustomLegend)
+!endprocedure
+
+!procedure $getLegendArea($hideStereotype) 
+$getHideStereotype($hideStereotype)
+rectangle legendArea<<legendArea>> [
+$getLegendTable()
+]
+!endprocedure
+
 !procedure HIDE_STEREOTYPE()
 hide stereotype
 !endprocedure
@@ -518,13 +544,9 @@ left to right direction
 
 ' has to be last call in diagram
 !unquoted procedure SHOW_LEGEND($hideStereotype="true")
-!if ($hideStereotype=="true")
-hide stereotype
-!endif
+$getHideStereotype($hideStereotype)
 legend right
-|<color:$LEGEND_TITLE_COLOR>**Legend**</color> |
-$showActiveLegendEntries($tagDefaultLegend)
-$showActiveLegendEntries($tagCustomLegend)
+$getLegendTable()
 endlegend
 !endprocedure
 
@@ -533,6 +555,27 @@ endlegend
 SHOW_LEGEND($hideStereotype)
 !endprocedure
 
+' enables that legend can be located in diagram, has to be last call in diagram
+!unquoted procedure SHOW_LEGEND_LEFT($alias, $hideStereotype="true")
+$getLegendArea($hideStereotype)
+Lay_L($alias, legendArea)
+!endprocedure
+
+!unquoted procedure SHOW_LEGEND_RIGHT($alias, $hideStereotype="true")
+$getLegendArea($hideStereotype)
+Lay_R($alias, legendArea)
+!endprocedure
+
+!unquoted procedure SHOW_LEGEND_UP($alias, $hideStereotype="true")
+$getLegendArea($hideStereotype)
+Lay_U($alias, legendArea)
+!endprocedure
+
+!unquoted procedure SHOW_LEGEND_DOWN($alias, $hideStereotype="true")
+$getLegendArea($hideStereotype)
+Lay_D($alias, legendArea)
+!endprocedure
+
 ' Boundaries
 ' ##################################
 

LayoutOptions.md

@@ -107,6 +107,64 @@ SHOW_LEGEND()
 
 ![SHOW_LEGEND Sample](https://www.plantuml.com/plantuml/png/JL5Dgzf05DtFhxYr2oDeWgMhhfgceWkreObr6IR9RHsOZs7cXY3b_VTtWpurcqlEn-4Svdia6MWm6ghThtEptsmtnvzGIUCrYa_ATdhe4Iv4FdxBiY37z9-Yoz0E4KFdBA6bj7CcyrhQAMOLgTUgpOglgtA2JeTzPcGa30mr1JkaiXXIpreXIWpHsKJsHjabpFBfgaX1aWkpXQYkR3JD3pVONePhqgsNCBzrco_Wlm3-7f79Y6qZlUUSCxQGUwzL9qavEsEe-Bo4l2hJuwPcIq3uagxXyAUOk5nhDqQO9aKW1xp7IvQOGPFo6g4U5H4686LGAukHkxtTsoLq8pddBcDI_4RziUfPwnJPoNTNrsN5gadqO9ynMwJ8lpYTly6PLujuUQLa8Tu1 "SHOW_LEGEND Sample")
 
+## SHOW_LEGEND_UP(alias, ?hideStereotype), SHOW_LEGEND_DOWN(...), SHOW_LEGEND_LEFT(...) or SHOW_LEGEND_RIGHT(...) 
+
+`LAYOUT_WITH_LEGEND()` and SHOW_LEGEND(?hideStereotype)` adds the legend at the bottom right of the picture like below and additional whitespace is created.
+
+```csharp
+@startuml Layout With Whitespace Sample
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
+
+Container_Ext(A, "Ext. Container A", "techn")
+Person(B, "Person B")
+System(C, "System C")
+Container(D, "Container D", "techn")
+Container(E, "Container E", "techn")
+
+Rel_R(A,B,"uses")
+Rel_R(A,C,"uses")
+Rel_D(B,C,"uses")
+Rel_R(C,D,"uses")
+Rel_D(B,D,"uses")
+Rel_D(C,E,"uses")
+
+SHOW_LEGEND()
+@enduml
+```
+
+![Layout With Whitespace Sample](https://www.plantuml.com/plantuml/png/NSwnReCm40RWtK_XCZbI0akdJWbWjGDj8r35Y1mu5IJR8FkiDc_VYw9QWOcxZz-_xkXHEGn6yqfTvu2ydN3axJWX-4Nrm1jb5WtiQRAz3WFm4N7nBrdcr4_wJTbm2HvSFri4Ysa_cspHojuQ3nu7FLsoulbmlj7NUvKPvH4SKLVG2pLPSEb2MSRYtibV5ASzJ-YRyiZyb90XzADDTkmCpizMv4JtaUUapPNQZIX8xoClI6E5AEb7t7WP2rSXkGh9nn2hGNSr7PVla-314_rBiP9Iv1kfwQfoczaAPMGKrhnzjbqbN-L7ANRi27O8Hly1 "Layout With Whitespace Sample")
+
+Therefore calculated legends can be defined relative to an element too that existing whitespace can be reused like below.
+
+- **SHOW_LEGEND_UP(alias, ?hideStereotype)**: shows the legend above the alias element  
+- **SHOW_LEGEND_DOWN(alias, ?hideStereotype)**: shows the legend below the alias element  
+- **SHOW_LEGEND_LEFT(alias, ?hideStereotype)**: shows the legend left of the alias element
+- **SHOW_LEGEND_RIGHT(alias, ?hideStereotype)**: shows the legend right of the alias element
+
+```csharp
+@startuml Compact Legend Layout Sample
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
+
+Container_Ext(A, "Ext. Container A", "techn")
+Person(B, "Person B")
+System(C, "System C")
+Container(D, "Container D", "techn")
+Container(E, "Container E", "techn")
+
+Rel_R(A,B,"uses")
+Rel_R(A,C,"uses")
+Rel_D(B,C,"uses")
+Rel_R(C,D,"uses")
+Rel_D(B,D,"uses")
+Rel_D(C,E,"uses")
+
+' legend fills whitespace to the right of container E
+SHOW_LEGEND_RIGHT(E)
+@enduml
+```
+
+![Compact Legend Layout Sample](https://www.plantuml.com/plantuml/png/NT51Ru8m50VmUp_56vTXed3PQIS56bt2DeDRTYGLdzAajAHznFdjzumPcvneV_pvvz4k0obFGsSWTrsl6e8IJsWFKAgB6mXsgkiDYWTj6pCS45gYFZodgLVdvAIf7VP3GDyuIsWfQLoNzaRPQ-4YqC7eVPe_BRPN-dmjqqu5GizKv_o5qXPzqdDMY75Vos-ALtE8-9d0oB2As0YRraOpiKKVd8qpfjiICjRTXTkxE6UzBI5d7IlYWb-CEoZ6mhkGl0l9_o5HeQah7YwRH_pNWUbNyZifucmY5KzLJ3DJuOmSHJo2kTt4KHiJuDngmi0tX40Eg4Nm-jGIk2CqV-EAtURzgoxbMhuLTVMotdp4SYQMNCEd_0C0 "Compact Legend Layout Sample")
+
 ## LAYOUT_AS_SKETCH()
 
 C4-PlantUML can be especially helpful during up-front design sessions.

README.md

@@ -323,7 +323,8 @@ Rel_L(x, s4, "uses")
 C4-PlantUML also comes with some layout options to make it easy and reusable to create nice and useful diagrams:
 
 * [LAYOUT_TOP_DOWN() or LAYOUT_LEFT_RIGHT()](LayoutOptions.md#layout_top_down-or-layout_left_right)
-* [LAYOUT_WITH_LEGEND() or SHOW_LEGEND(?hideStereotype)](LayoutOptions.md#layout_with_legend-or-SHOW_LEGEND)
+* [LAYOUT_WITH_LEGEND() or SHOW_LEGEND(?hideStereotype)](LayoutOptions.md#layout_with_legend-or-show_legend)
+* [SHOW_LEGEND_UP(alias, ?hideStereotype), SHOW_LEGEND_DOWN(...), SHOW_LEGEND_LEFT(...), SHOW_LEGEND_RIGHT(...)](LayoutOptions.md#show_legend_up-show_legend_down-show_legend_left-show_legend_right)
 * [LAYOUT_AS_SKETCH()](LayoutOptions.md#layout_as_sketch)
 * [HIDE_STEREOTYPE()](LayoutOptions.md#hide_stereotype)
 

percy/TestRelativeLegend.puml

@@ -0,0 +1,24 @@
+@startuml
+' convert it with additional command line argument -DRELATIVE_INCLUDE="." to use locally
+!if %variable_exists("RELATIVE_INCLUDE")
+  !include ./../C4_Container.puml
+!else
+  !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
+!endif
+
+Container_Ext(A, "Ext. Container A", "techn")
+Person(B, "Person B")
+System(C, "System C")
+Container(D, "Container D", "techn")
+Container(E, "Container E", "techn")
+
+Rel_R(A,B,"uses")
+Rel_R(A,C,"uses")
+Rel_D(B,C,"uses")
+Rel_R(C,D,"uses")
+Rel_D(B,D,"uses")
+Rel_D(C,E,"uses")
+
+' legend fills whitespace to the right of container E
+SHOW_LEGEND_RIGHT(E)
+@enduml