#134: Legend fill whitespace with SHOW_FLOATING_LEGEND() and Lay_Distance() (instead of SHOW_LEGEND_UP(), ..._DOWN(), ..._LEFT(), ..._RIGHT())

5 years ago · 70e2622d10
parent 9774e06e86
commit 70e2622d10
5 changed files with 105 additions and 84 deletions
--- a/C4.puml
+++ b/C4.puml
@ -70,7 +70,7 @@ skinparam actor {
    style awesome
 }

-' Some boundary skinparam have to be set a package skinparams too (PlantUML uses internal packages)
+' Some boundary skinparams have to be set as package skinparams too (PlantUML uses internal packages)
 skinparam package {
    StereotypeFontSize 6
    StereotypeFontColor $BOUNDARY_BG_COLOR
@ -516,9 +516,9 @@ $showActiveLegendEntries($tagDefaultLegend)
 $showActiveLegendEntries($tagCustomLegend)
 !endprocedure

-!procedure $getLegendArea($hideStereotype) 
+!procedure $getLegendArea($areaAlias, $hideStereotype) 
 $getHideStereotype($hideStereotype)
-rectangle legendArea<<legendArea>> [
+rectangle $areaAlias<<legendArea>> [
 $getLegendTable()
 ]
 !endprocedure
@ -555,25 +555,9 @@ 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)
+' enables that legend can be located in drawing area of the diagram. It has to be last call in diagram followed by Lay_Distance()
+!unquoted procedure SHOW_FLOATING_LEGEND($alias="legend", $hideStereotype="true")
+$getLegendArea($alias, $hideStereotype)
 !endprocedure

 ' Boundaries
@ -711,6 +695,10 @@ $getRel("<<-RIGHT->>", $from, $to, $label, $techn, $descr, $sprite, $tags, $link
 ' Layout Helpers
 ' ##################################

+!function $getHiddenLine($distance)
+  !return '-[hidden]' + %substr('------------', 0, %intval($distance) + 1)
+!endfunction
+
 !unquoted procedure Lay_D($from, $to)
 $from -[hidden]D- $to
 !endprocedure
@ -723,3 +711,10 @@ $from -[hidden]R- $to
 !unquoted procedure Lay_L($from, $to)
 $from -[hidden]L- $to
 !endprocedure
+
+' PlantUML bug: lines which does "not match" with the orientation/direction of the diagram
+' uses the same length therefore the method offers no direction at all.
+' If a direction is required the Lay_...() methods can be used
+!unquoted procedure Lay_Distance($from, $to, $distance="0")
+$from $getHiddenLine($distance) $to
+!endprocedure
--- a/LayoutOptions.md
+++ b/LayoutOptions.md
@ -107,7 +107,7 @@ 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(...) 
+## SHOW_FLOATING_LEGEND(?alias, ?hideStereotype)

 `LAYOUT_WITH_LEGEND()` and SHOW_LEGEND(?hideStereotype)` adds the legend at the bottom right of the picture like below and additional whitespace is created.

@ -115,55 +115,48 @@ SHOW_LEGEND()
@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")
+Person(a, "Person A")
+Container(b, "Container B", "techn")
+System(c, "System C")
+Container(d, "Container D", "techn")
+Container_Ext(e, "Ext. 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")
+Rel_R(a, b, "calls")
+Rel_D(b, c, "uses")
+Rel_D(c, d, "uses")
+Rel_R(d, e, "updates")

 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")
+![Layout With Whitespace Sample](http://www.plantuml.com/plantuml/png/LSwnReCm40RWtK_XCZbI0qkdJca1jGDjew2A4HdxL91iOzbdjNdx7eb4meJlk_y_SOWe0oPhU2FFSqBUJJZoRfmGefSAU2kjDy0U9gTCqi17H1-VYoB8t_o7icb84OAQ7OB3NCssy4QwvU8-eZRJK9HF--D2tnzDOML424HzIGqvEGYvfonZHmXnTa8-ykpwv2_PZgqfCT1YdVXhHYE26Xs5sZCTjK8HNP-yt5JrfbhTLrVkwpyKG1lwvloMhk_Jx0IcFot_E90gQKmaNR0I98emHRWPWTuObGbWCQybNfYrxrzTtzHlzMSbTkm0JYTh_W40 "Layout With Whitespace Sample")

-Therefore calculated legends can be defined relative to an element too that existing whitespace can be reused like below.
+Therefore a floating legends can be added via SHOW_FLOATING_LEGEND() and positioned with Lay_Distance() 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
+- `SHOW_FLOATING_LEGEND(?alias, ?hideStereotype): shows the legend in the drawing area

 ```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)
+Person(a, "Person A")
+Container(b, "Container B", "techn")
+System(c, "System C")
+Container(d, "Container D", "techn")
+Container_Ext(e, "Ext. Container E", "techn")
+
+Rel_R(a, b, "calls")
+Rel_D(b, c, "uses")
+Rel_D(c, d, "uses")
+Rel_R(d, e, "updates")
+
+SHOW_FLOATING_LEGEND()
+Lay_Distance(legend, e, 1)
@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")
+![Compact Legend Layout Sample](http://www.plantuml.com/plantuml/png/LP51Q_im3CNl_XJ-z-J2lmc3dNPgbsJT86jBkx6ZSMtH1cp7s0fRl_ta5TBcPFcdzuHuMYPK4GTdUTMxe3Jo5axW3M_LfH-G7vGB5jY_pcix6E1dn92UoZAgx-BKuNau3WcYxZs2nqBthWnM-JnmaT3OxbXMZujTHf_lRUbKGeY4P4KErNc8HI0jOpk8gVT2_UUpQybNipaRLU98ZV77dsVqHT1dJwB3XOOweGbTIrvDh6PYhU-j8vRD3mgW3hq5lwcRUpNRWvNxl6FUHYjh4z4CQq544wGmReo0cJ0o4u3CWb7uXzdXTVibNzhjwkDjivPjisusjPWpob_M7Lt7Qn0st-HgVPYp9TKKsYy0 "Compact Legend Layout Sample")

 ## LAYOUT_AS_SKETCH()

--- a/README.md
+++ b/README.md
@ -280,10 +280,10 @@ Rel_D(user, user1, "requests", "async message", "if sprite starts with &, it def

 In rare cases, you can force the layout of objects which have no relationships by using:

-* `Lay_U`
-* `Lay_D`
-* `Lay_L`
-* `Lay_R`
+* `Lay_U(from, to)`
+* `Lay_D(from, to)`
+* `Lay_L(from, to)`
+* `Lay_R(from, to)`

 In following sample a person uses different systems, and group of persons which have no relations

@ -318,6 +318,41 @@ Rel_L(x, s4, "uses")

 ![Relation versus Layout](https://www.plantuml.com/plantuml/png/LSt1QeD04CRnkq-HvgJGA55FFQLLeGLBHIEq9rbrQ8HrbTrPshnzPmn5Svl_3_RRaq6XqOxIUHXK9sqFkmlYR9w2G8iV_tl0Yssj0TrD2a6XtqrZC4kX-Ct1O2-7DaZYGy5Kl-V1A0o29ceIUY461TgVUV_rBSsQwfoLsSVvgyXSpt4Aq6PIhdZSxP_ttd-sb2zhTfJ9cZrbkYPGPfHEBgvDpLEjjzmbtztjJldkRtVEDwoV_zB09mrKLuCmkkP8NHqt43A46uWOeWt43361Ku9iQfvSPgm1GyfOBXZUOxfWT8_vWl6A9r2z7UKV "Relation versus Layout")

+(In combination with [SHOW_FLOATING_LEGEND()](LayoutOptions.md#show_floating_legend)) a greater distance between an element and the
+e.g. floating legend could be required that all e.g. corners of the drawing area can be reached.
+
+* `Lay_Distance(from, to, ?distance)`: Sets the distance between `from` and `to` with down alignment. (Lay_Distance(from,to,0) equals Lay_D(from, to))
+
+In following sample the floating legend should be in the left bottom corner of the drawing are.
+(The normal SHOW_LEGEND() call requires no extra Lay_Distance() call and the legend is automatically drawn below the diagram on the right side)
+
+```
+@startuml
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
+
+!define DEVICONS https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/master/devicons
+!define FONTAWESOME https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/master/font-awesome-5
+!include DEVICONS/angular.puml
+!include DEVICONS/java.puml
+!include DEVICONS/msql_server.puml
+!include FONTAWESOME/users.puml
+
+Person(user, "Customer", "People that need products", $sprite="users")
+Container(spa, "SPA", "angular", "The main interface that the customer interacts with", $sprite="angular")
+Container(api, "API", "java", "Handles all business logic", $sprite="java")
+ContainerDb(db, "Database", "Microsoft SQL", "Holds product, order and invoice information", $sprite="msql_server")
+
+Rel(user, spa, "Uses")
+Rel(spa, api, "Uses")
+Rel_R(api, db, "Reads/Writes")
+
+SHOW_FLOATING_LEGEND()
+Lay_Distance(legend, db, 1)
+@enduml
+```
+
+![db below legend, 1 unit distance](http://www.plantuml.com/plantuml/png/hL5DZzem4BtdLtXH3o0jH5NRIwLAYu3THUA30bkEqH0FuCgnKyy4r7_VCGcxKQjAFVHa-ytCUtvl7eWXS5NOvCwut5OQrOcvfCzf6k0oE1e-LVkACEJUCJeUvBv8ImikplI9jJNxTFInluhGotoM5a2CGQ1i91DW78P16VcJEuq7UQhnvDjqj5ni_a68gn9q-F0cQAJQFqX7dyfW6Eccf_4SQ_IgyhXSR8UxoMOvd_nNeIi65oHVOF_JBRKtLocuOsMXCVrd-JkSuM-rWdxOZ32SyVVnbfiq_fsQJ5TozQuReNlL6LN4li3GaViAVMbHyGbOEKIjok1rbJD9yLtjwKldIjNf9Q-hwb89ChnP3ID7OoLUjoTKXRGeunZ30VA6cWNF6zcw1gAXBf9oM-Z6r9Q2qWZnS3MD_36MU3w3qnP9WRLAjYIDHChweydRTB6xpJNUT_LUfiV0i0V2o3GtUV3a3wmsNsTNQcyrtMAuLpve34havDjdRtAKy-130MoyQukrjYAQoHfjatUTrGjXZ332Lo3QQgFPkdPw_U0QGLEwYyInd6oUbxliSROSRgUBfsmsUPeinjrUCeEVsTWGWyknQ_68JjS4xtl9Wpnazxy0 "db below legend, 1 unit distance")
+
 ## Layout Options

 C4-PlantUML also comes with some layout options to make it easy and reusable to create nice and useful diagrams:
--- a/percy/TestFloatingLegend.puml
+++ b/percy/TestFloatingLegend.puml
@ -0,0 +1,22 @@
+@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
+
+Person(a, "Person A")
+Container(b, "Container B", "techn")
+System(c, "System C")
+Container(d, "Container D", "techn")
+Container_Ext(e, "Ext. Container E", "techn")
+
+Rel_R(a, b, "calls")
+Rel_D(b, c, "uses")
+Rel_D(c, d, "uses")
+Rel_R(d, e, "updates")
+
+SHOW_FLOATING_LEGEND()
+Lay_Distance(legend, e, 1)
+@enduml
--- a/percy/TestRelativeLegend.puml
+++ b/percy/TestRelativeLegend.puml
@ -1,24 +0,0 @@
-@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