Merge pull request #3483 from henrikt-ma/curve-z-order

Define order within legend and plotting order

chapters/annotations.tex

@@ -236,6 +236,7 @@ \subsubsection{Plot Curves}\label{plot-curves}
   expression x = time "X coordinate values";
   expression y "Y coordinate values";
   String legend "Legend";
+  Integer zOrder = 0 "Drawing order control";
 end Curve;
 \end{lstlisting}
 
@@ -254,6 +255,10 @@ \subsubsection{Plot Curves}\label{plot-curves}
 When \lstinline!legend! is not provided, the tool produces a default based on \lstinline!x! and/or \lstinline!y!.
 Providing the empty string as \lstinline!legend! means that the curve shall be omitted from the plot legend.
 Variable replacements, as described in \cref{variable-replacements}, can be used in \lstinline!legend!.
+The order of presentation within the plot legend corresponds to order of appearance in the \lstinline!curves! of a \lstinline!Plot!.
+
+The \lstinline!zOrder! gives control over drawing order, with higher values corresponding to closer to front.
+Ties are resolved using order of appearance in the \lstinline!curves! of a \lstinline!Plot!, with later appearance corresponding to closer to front.
 
 \subsubsection{Escape Sequences}\label{text-markup-escape-sequences}
 
@@ -648,8 +653,8 @@ \section{Graphical Objects}\label{annotations-for-graphical-objects}\label{graph
 \end{lstlisting}
 \end{example}
 
-The graphics is specified as an ordered sequence of graphical primitives, which are described below.
-First, base class contents are drawn according to the order of the \lstinline!extends!-clauses, and then graphical primitives are drawn according to the order such that later objects can cover earlier ones.
+The graphics is specified as an ordered sequence of graphical primitives described below.
+Base class contents are drawn behind the graphical primitives of the current class, with base classes ordered from back to front according to the order of the \lstinline!extends!-clauses, and graphical primitives according to order of appearance in the annotation.
 
 \begin{nonnormative}
 Note that the ordered sequence is syntactically a valid Modelica annotation, although there