/
annotations.tex
2104 lines (1791 loc) · 98.2 KB
/
annotations.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
\chapter{Annotations}\label{annotations}
Annotations are intended for storing extra information about a model,
such as graphics, documentation or versioning, etc. A Modelica tool is
free to define and use other annotations, in addition to those defined
here, according to \cref{vendor-specific-annotations}. Annotations must be
represented with constructs according to the Modelica grammar (for
replaceable class declarations with a constraining-clause also refer to
\cref{constraining-clause-annotations}). The specification in this document defines the
semantic meaning if a tool implements any of these annotations.
\section{Vendor-Specific Annotations}\label{vendor-specific-annotations}
A vendor may -- anywhere inside an annotation -- add specific, possibly
undocumented, annotations which are not intended to be interpreted by
other tools. The only requirement is that any tool
shall save files with all vendor-specific annotations (and all annotations from this chapter) intact.
Two variants of vendor-specific annotations exist; one
simple and one hierarchical. Double underscore concatenated with a
vendor name as initial characters of the identifier are used to identify
vendor-specific annotations.
\begin{example}
\begin{lstlisting}[language=modelica]
annotation (
Icon(coordinateSystem(extent={{-100,-100}, {100,100}}),
graphics={__NameOfVendor(Circle(center={0,0}, radius=10))}) );
\end{lstlisting}
This introduces a new graphical primitive \lstinline!Circle! using the
hierarchical variant of vendor-specific annotations.
\begin{lstlisting}[language=modelica]
annotation (
Icon(coordinateSystem(extent={{-100,-100}, {100,100}}),
graphics={Rectangle(extent={{-5,-5},{7,7}}, __NameOfVendor_shadow=2)}) );
\end{lstlisting}
This introduces a new attribute \lstinline!__NameOfVendor_shadow!
for the \lstinline!Rectangle! primitive using the simple variant of
vendor-specific annotations.
\end{example}
\section{Annotations for Documentation}\label{annotations-for-documentation}
\begin{lstlisting}[language=grammar]
documentation-annotation:
annotation "(" Documentation "(" "info" "=" STRING
["," "revisions" "=" STRING ] ")" ")"
\end{lstlisting}
The \lstinline!Documentation! annotation can contain the \lstinline!info! annotation
giving a textual description, the \lstinline!revisions! annotation giving a list
of revisions and other annotations defined by a tool.
How the tool interprets the information in \lstinline!Documentation! is
unspecified. If the string starts with the tag
\lstinline!<html>! or \lstinline!<HTML>! the entire string is HTML encoded
(and is assumed to end with \lstinline!</html>! or \lstinline!</HTML>! and shall
be rendered as HTML even if the end-tags are missing),
otherwise the entire string is rendered as is.
The HTML encoded content may contain links. For external
links see \cref{external-resources}. Links to Modelica classes may be defined with
the HTML link command using scheme \lstinline!Modelica!
(using its lower case form in the URI, see \cref{external-resources}), e.g.,
\begin{lstlisting}[language=modelica]
<a href="modelica://MultiBody.Tutorial">MultiBody.Tutorial</a>
\end{lstlisting}
\begin{nonnormative}
The \lstinline!revisions! documentation may be omitted in printed documentation.
\end{nonnormative}
Together with scheme \lstinline!Modelica! the (URI) fragment specifiers
\lstinline!#diagram!, \lstinline!#info!, \lstinline!#text!, \lstinline!#icon! may be used to reference different
layers. User-defined fragment specifiers (anchors) may also be used, and they may be renamed
when generating HTML (in particular to avoid collisions).
Example:
\begin{lstlisting}[language=modelica]
<a href="modelica://MultiBody.Joints.Revolute#info">Revolute</a>
\end{lstlisting}
\begin{lstlisting}[language=grammar]
preferred-view-annotation:
annotation "(" preferredView "=" ("info" | "diagram" | "text") ")"
\end{lstlisting}
The \lstinline!preferredView! annotation defines the default view when selecting the
class. \lstinline!info! means info layer, i.e., the documentation of the class,
\lstinline!diagram! means diagram layer and \lstinline!text! means the Modelica text layer.
\begin{lstlisting}[language=grammar]
documentation-class-annotation:
annotation "(" DocumentationClass "=" true ")"
\end{lstlisting}
Only allowed as class annotation on any kind of class and implies that
this class and all classes within it are treated as having the
annotation \lstinline!preferredView="info"!. If the annotation \lstinline!preferredView! is
explicitly set for a class, it has precedence over a \lstinline!DocumentationClass!
annotation.
\begin{nonnormative}
A tool may display such classes in special ways. For example, the description texts of the classes might be displayed instead
of the class names, and if no icon is defined, a special information default icon may be displayed in the package browser.
\end{nonnormative}
\section{Annotations for Code Generation}\label{annotations-for-code-generation}
The annotations listed below, appearing directly inside \lstinline!annotation($\ldots$)!, can influence the code generation.
\begin{center}
\begin{tabular}{l|l l}
\hline
\tablehead{Annotation} & \tablehead{Description} & \tablehead{Details}\\
\hline
\hline
\lstinline!Evaluate! & Use parameter value for symbolic processing & \Cref{modelica:Evaluate}\\
\lstinline!HideResult! & Don't show component's simulator result & \Cref{modelica:HideResult}\\
\lstinline!Inline! & Inline function & \Cref{modelica:Inline}\\
\lstinline!LateInline! & Inline after all symbolic transformations & \Cref{modelica:LateInline}\\
\lstinline!InlineAfterIndexReduction! & Inline after index reduction & \Cref{modelica:InlineAfterIndexReduction}\\
\lstinline!GenerateEvents! & Generate events for zero crossings in function & \Cref{modelica:GenerateEvents}\\
\lstinline!smoothOrder! & Function smoothness guarantee & \Cref{modelica:smoothOrder}\\
\hline
\end{tabular}
\end{center}
\begin{annotationdefinition}[Evaluate]
\begin{synopsis}[grammar]\begin{lstlisting}
"Evaluate" "=" ( false | true )
\end{lstlisting}\end{synopsis}
\begin{semantics}
The annotation \lstinline!Evaluate! can occur in the component declaration, its type declaration, or a base-class of the type-declaration. In the case of multiple conflicting annotations it is handled similarly to modifiers (e.g., an \lstinline!Evaluate! annotation on the component declaration takes precedence). The annotation \lstinline!Evaluate! only has effect for a component declared with the prefix \lstinline!parameter!.
If \lstinline!Evaluate = true!, the model developer proposes to utilize the value for the symbolic processing. In that case, it is not possible to change the parameter value after symbolic pre-processing.
If \lstinline!Evaluate = false!, the model developer proposes to not utilize the value of the corresponding parameter for the symbolic processing.
\begin{nonnormative}
\lstinline!Evaluate! is for example used for axis of rotation parameters in the \lstinline!Modelica.Mechanics.MultiBody! library in order to improve the efficiency of the generated code.
\end{nonnormative}
\end{semantics}
\end{annotationdefinition}
\begin{annotationdefinition}[HideResult]
\begin{synopsis}[grammar]\begin{lstlisting}
"HideResult" "=" ( false | true )
\end{lstlisting}\end{synopsis}
\begin{semantics}
\lstinline!HideResult = true! defines that the model developer proposes to not show the simulator results of the corresponding component.
\lstinline!HideResult = false! defines that the developer proposes to show the corresponding component.
\begin{nonnormative}
For example, a tool is not expected to provide means to plot a variable with \lstinline!HideResult = true!. If a variable is declared in a protected section, a tool might not include it in a simulation result. By setting \lstinline!HideResult = false!, the modeler would like to have the variable in the simulation result, even if in the protected section.
\lstinline!HideResult! is for example used in the connectors of the \lstinline!Modelica.StateGraph! library to not show variables to the modeler that are of no interest to him and would confuse him.
\end{nonnormative}
\end{semantics}
\end{annotationdefinition}
\begin{annotationdefinition}[Inline]
\begin{synopsis}[grammar]\begin{lstlisting}
"Inline" "=" ( false | true )
\end{lstlisting}\end{synopsis}
\begin{semantics}
Has only an effect within a function declaration.
If \lstinline!Inline = true!, the model developer proposes to inline the function. This means, that the body of the function is included at all places where the function is called.
If \lstinline!Inline = true!, the model developer proposes to not inline the function.
\begin{nonnormative}
\lstinline!Inline = true! is for example used in \lstinline!Modelica.Mechanics.MultiBody.Frames! and in functions of \lstinline!Modelica.Media! to have no overhead for function calls such as resolving a vector in a different coordinate system and at the same time the function can be analytically differentiated, e.g., for index reduction needed for mechanical systems.
\end{nonnormative}
\end{semantics}
\end{annotationdefinition}
\begin{annotationdefinition}[LateInline]
\begin{synopsis}[grammar]\begin{lstlisting}
"LateInline" "=" ( false | true )
\end{lstlisting}\end{synopsis}
\begin{semantics}
Has only an effect within a function declaration.
If \lstinline!LateInline = true!, the model developer proposes to inline the function after all symbolic transformations have been performed.
\begin{nonnormative}
Late inlining is especially useful for differentiation and inversion of functions; for efficiency reasons it is then useful to replace all function calls with identical input arguments by one function call, before the inlining.
\end{nonnormative}
If \lstinline!LateInline = false!, the model developer proposes to not inline the function after symbolic transformations have been performed.
\lstinline!Inline = true, LateInline = false! is identical to \lstinline!Inline = true!.
\lstinline!Inline = true, LateInline = true! is identical to \lstinline!LateInline = true!.
\lstinline!Inline = false, LateInline = true! is identical to \lstinline!LateInline = true!.
\begin{nonnormative}
This annotation is for example used in \lstinline!Modelica.Media.Water.IF97_Utilities.T_props_ph! to provide in combination with common subexpression elimination the automatic caching of function calls. Furthermore, it is used in order that a tool is able to propagate specific enthalpy over connectors in the \lstinline!Modelica.Fluid! library.
\end{nonnormative}
\end{semantics}
\end{annotationdefinition}
\begin{annotationdefinition}[InlineAfterIndexReduction]
\begin{synopsis}[grammar]\begin{lstlisting}
"InlineAfterIndexReduction" "=" ( false | true )
\end{lstlisting}\end{synopsis}
\begin{semantics}
Has only an effect within a function declaration.
If \lstinline!true!, the model developer proposes to inline the function after the function is differentiated for index reduction, and before any other symbolic transformations are performed. This annotation cannot be combined with annotations \lstinline!Inline! and \lstinline!LateInline!.
\end{semantics}
\end{annotationdefinition}
\begin{annotationdefinition}[GenerateEvents]
\begin{synopsis}[grammar]\begin{lstlisting}
"GenerateEvents" "=" ( false | true )
\end{lstlisting}\end{synopsis}
\begin{semantics}
Has only an effect within a function declaration
If \lstinline!GenerateEvents = true!, the model developer proposes that crossing functions in the function should generate events (one possibility of doing this is to inline the function and generate events for the inlined function).
\begin{nonnormative}
This annotation is for example used in \lstinline!Modelica.Media.Water.IF97_Utilities.phase_dT! to indicate that the output should generate an event when it changes.
\end{nonnormative}
\end{semantics}
\end{annotationdefinition}
\begin{annotationdefinition}[smoothOrder]
\begin{synopsis}[grammar]\begin{lstlisting}
"smoothOrder" "=" UNSIGNED-NUMBER ")"
"smoothOrder" "(" "normallyConstant" "=" IDENT
{ "," "normallyConstant" "=" IDENT } ")" "=" UNSIGNED-NUMBER ")"
\end{lstlisting}\end{synopsis}
\begin{semantics}
This annotation has only an effect within a function declaration.
\lstinline!smoothOrder! defines the number of differentiations of the function, in order that all of the differentiated outputs are continuous provided all input arguments and their derivatives up to order \lstinline!smoothOrder! are continuous.
\begin{nonnormative}
This means that the function is at least C\textsuperscript{smoothOrder}. \lstinline!smoothOrder = 1! means that the function can be differentiated at least once in order that all output arguments are still continuous, provided the input arguments are continuous. If a tool needs the derivative of a function, e.g.\ for index reduction or to compute an analytic Jacobian, the function can be differentiated analytically at least \lstinline!smoothOrder! times.
\end{nonnormative}
The optional argument \lstinline!normallyConstant! of \lstinline!smoothOrder! defines that the function argument \lstinline!IDENT! is usually constant.
\begin{nonnormative}
A tool might check whether the actual argument to \lstinline!IDENT! is a parameter expression at the place where the function is called. If this is the case, the derivative of the function might be constructed under the assumption that the corresponding argument is constant, to enhance efficiency. Typically, a tool would generate at most two different derivative functions of a function: One, under the assumption that all \lstinline!normallyConstant! arguments are actually constant. And one, under the assumption that all input arguments are time varying. Based on the actual arguments of the function call either of the two derivative functions is used.
This annotation is used by many functions of the \lstinline!Modelica.Fluid! library, such as\linebreak[4] \lstinline!Modelica.Fluid.Dissipation.PressureLoss.StraightPipe.dp_laminar_DP!, since geometric arguments to these functions are usually constant.
\end{nonnormative}
\end{semantics}
\end{annotationdefinition}
\section{Annotations for Simulation Experiments}\label{annotations-for-simulation-experiments}
\begin{lstlisting}[language=grammar]
experiment-annotation:
annotation "(" "experiment" [ "(" [experimentOption
{"," experimentOption}] ")" ] ")"
experimentOption:
"StartTime" "=" [ "+" | "-" ] UNSIGNED-NUMBER |
"StopTime" "=" [ "+" | "-"] UNSIGNED-NUMBER |
"Interval" "=" UNSIGNED-NUMBER |
"Tolerance" "=" UNSIGNED-NUMBER
\end{lstlisting}
The \lstinline!experiment! annotation defines the default start time (\lstinline!StartTime!) in {[}s{]}, the default stop time (\lstinline!StopTime!) in {[}s{]}, the suitable time resolution for the result grid (\lstinline!Interval!) in {[}s{]}, and the default relative integration tolerance (\lstinline!Tolerance!) for simulation experiments to be carried out with the model or block at hand. If \lstinline!StartTime! is not specified it is assumed to be \lstinline!0.0!.
\section{Annotation for single use of class}\label{annotation-for-single-use-of-class}
For state machines it is useful to have single instances of local
classes. This can be done using:
\begin{lstlisting}[language=modelica]
annotation(singleInstance=true)
\end{lstlisting}
The annotation \lstinline!singleInstance! in a class indicates that there should
only be one component instance of the class, and it should be in the
same scope as the class is defined. The intent is to remove the class
when the component is removed and to prevent duplication of the
component.
\section{Annotations for Graphical Objects}\label{annotations-for-graphical-objects}
A graphical representation of a class consists of two abstraction
layers, icon layer and diagram layer showing graphical objects,
component icons, connectors and connection lines. The icon
representation typically visualizes the component by hiding hierarchical
details. The hierarchical decomposition is described in the diagram
layer showing icons of subcomponents and connections between these.
Graphical annotations described in this chapter ties into the Modelica
grammar as follows.
\begin{lstlisting}[language=grammar]
graphical-annotations :
annotation "(" [ layer-annotations ] ")"
layer-annotations :
( icon_layer | diagram_layer ) [ "," layer-annotations ]
\end{lstlisting}
Layer descriptions (start of syntactic description):
\begin{lstlisting}[language=grammar]
icon-layer :
"Icon" "(" [ coordsys-specification "," ] graphics ")"
diagram-layer :
"Diagram" "(" [ coordsys-specification "," ] graphics ")"
\end{lstlisting}
\begin{example}
\begin{lstlisting}[language=modelica]
annotation(
Icon(coordinateSystem(extent = {{-100, -100}, {100, 100}}),
graphics = {Rectangle(extent = {{-100, -100}, {100, 100}}),
Text(extent = {{-100, -100}, {100, 100}}, textString = "Icon")}));
\end{lstlisting}
\end{example}
The graphics is specified as an ordered sequence of graphical
primitives, which are described below. First base-class contents is
drawn according to the order of the extends-clauses, and then graphical
primitives are drawn according to the order such that later objects can
cover earlier ones.
\begin{nonnormative}
Note that the ordered sequence is syntactically a valid Modelica annotation, although there
is no mechanism for defining an array of heterogeneous objects in Modelica.
\end{nonnormative}
These Icon, Diagram, and Documentation annotations are only allowed
directly in classes (e.g.\ not on components or connections). The allowed
annotations for a short class definition is the union of the allowed
annotations in classes and on extends-clauses.
\subsection{Common Definitions}\label{common-definitions}
The following common definitions are used to define graphical
annotations in the later sections.
\begin{lstlisting}[language=modelica]
type DrawingUnit = Real(final unit="mm");
type Point = DrawingUnit[2] "{x, y}";
type Extent = Point[2] "Defines a rectangular area {{x1, y1}, {x2, y2}}";
\end{lstlisting}
The interpretation of \lstinline!unit! is with respect to printer output in
natural size (not zoomed).
All graphical entities have a visible attribute which indicates if the
entity should be shown.
\begin{lstlisting}[language=modelica]
partial record GraphicItem
Boolean visible = true;
Point origin = {0, 0};
Real rotation(quantity="angle", unit="deg")=0;
end GraphicItem;
\end{lstlisting}
The \lstinline!origin! attribute specifies the origin of the graphical item in the
coordinate system of the layer in which it is defined. The origin is
used to define the geometric information of the item and for all
transformations applied to the item. All geometric information is given
relative the \lstinline!origin! attribute, which by default is \{0, 0\}.
The \lstinline!rotation! attribute specifies the rotation of the graphical item
counter-clockwise around the point defined by the \lstinline!origin! attribute.
\subsubsection{Coordinate Systems}\label{coordinate-systems}
Each of the layers has its own coordinate system. A coordinate system is
defined by the coordinates of two points, the left (x1) lower (y1)
corner and the right (x2) upper (y2) corner, where the coordinates of
the first point shall be less than the coordinates of the second point.
The attribute \lstinline!preserveAspectRatio! specifies a hint for the shape of
components of the class, but does not actually influence the rendering of the component.
If \lstinline!preserveAspectRatio! is true, changing the
extent of components should preserve the current aspect ratio of the coordinate
system of the class.
The attribute \lstinline!initialScale! specifies the default component size as
\lstinline!initialScale! times the size of the coordinate system of the class. An
application may use a different default value of \lstinline!initialScale!.
The attribute \lstinline!grid! specifies the spacing between grid points which can
be used by tools for alignment of points in the coordinate system, e.g.\ ``snap-to-grid''.
Its use and default value is tool-dependent.
\begin{lstlisting}[language=modelica]
record CoordinateSystem
Extent extent;
Boolean preserveAspectRatio=true;
Real initialScale = 0.1;
DrawingUnit grid[2];
end CoordinateSystem;
\end{lstlisting}
\begin{example}
A coordinate system for an icon could for example be defined as:
\begin{lstlisting}[language=modelica]
CoordinateSystem(extent = {{-10, -10}, {10, 10}});
\end{lstlisting}
i.e.\ a coordinate system with width 20 units and height 20 units.
\end{example}
The coordinate systems for the icon and diagram layers are by default
defined as follows; where the array of \lstinline!GraphicsItem! represents an
ordered list of graphical primitives.
\begin{lstlisting}[language=modelica]
record Icon "Representation of the icon layer"
CoordinateSystem coordinateSystem(extent = {{-100, -100}, {100, 100}});
GraphicItem[:] graphics;
end Icon;
record Diagram "Representation of the diagram layer"
CoordinateSystem coordinateSystem(extent = {{-100, -100}, {100, 100}});
GraphicItem[:] graphics;
end Diagram;
\end{lstlisting}
The coordinate system (including \lstinline!preserveAspectRatio!) of a class is defined by the following priority:
\begin{enumerate}
\item
The coordinate system annotation given in the class (if specified).
\item
The coordinate systems of the first base-class where the extent on the
extends-clause specifies a null-region (if any). Note that null-region
is the default for base-classes, see \cref{extends-clause}.
\item
The default coordinate system \lstinline!CoordinateSystem(extent = {{-100, -100}, {100, 100}})!.
\end{enumerate}
\subsubsection{Graphical Properties}\label{graphical-properties}
Properties of graphical objects and connection lines are described using
the following attribute types.
\begin{lstlisting}[language=modelica]
type Color = Integer[3](min=0, max=255) "RGB representation";
constant Color Black = zeros(3);
type LinePattern = enumeration(None, Solid, Dash, Dot, DashDot, DashDotDot);
type FillPattern = enumeration(None, Solid, Horizontal, Vertical,
Cross, Forward, Backward, CrossDiag, HorizontalCylinder, VerticalCylinder, Sphere);
type BorderPattern = enumeration(None, Raised, Sunken, Engraved);
type Smooth = enumeration(None, Bezier);
type EllipseClosure = enumeration(None, Chord, Radial);
\end{lstlisting}
The \lstinline!LinePattern! attribute \lstinline!Solid! indicates a normal line, \lstinline!None! an
invisible line, and the other attributes various forms of dashed/dotted
lines.
The \lstinline!FillPattern! attributes \lstinline!Horizontal!, \lstinline!Vertical!, \lstinline!Cross!, \lstinline!Forward!, \lstinline!Backward! and \lstinline!CrossDiag! specify fill patterns drawn with the line color over the fill color.
The attributes \lstinline!HorizontalCylinder!, \lstinline!VerticalCylinder! and \lstinline!Sphere! specify
gradients that represent a horizontal cylinder, a vertical cylinder and
a sphere, respectively. The gradient goes from line color to fill color.
The border pattern attributes \lstinline!Raised!, \lstinline!Sunken! and \lstinline!Engraved! represent frames which are rendered in a tool-dependent way --- inside the extent of the filled shape.
\begin{figure}[H]
\begin{center}
\includegraphics{bezierpoints}
\end{center}
\caption{Line with \lstinline!smooth = Bezier!. The four line points $P_{1}$, \ldots{}, $P_{4}$ result in two quadratic splines and two straight line segments.}\label{fig:smooth-bezier}
\end{figure}
The \lstinline!smooth! attribute specifies that a line can be drawn as straight line
segments (\lstinline!None!) or using a spline (\lstinline!Bezier!), where the line's points
specify control points of a quadratic Bezier curve, see \cref{fig:smooth-bezier}.
For lines with only two points, the \lstinline!smooth! attribute has no effect.
For lines with three or more points ($P_{1}$, $P_{2}$, \ldots{}, $P_{n}$), the middle point of each line segment ($P_{12}$, $P_{23}$, \ldots{}, $P_{(n-1)n}$) becomes the starting point and ending
points of each quadratic Bezier curve. For each quadratic Bezier curve, the common point of the two line segment becomes the control point. For instance, point $P_{2}$ becomes the control point for
the Bezier curve starting at $P_{12}$ and ending at $P_{23}$. A straight line is drawn between the starting point of the line and the starting point of the first quadratic Bezier curve, as well as
between the ending point of the line and the ending point of the last quadratic Bezier curve.
In the illustration above, the square points ($P_{1}$, $P_{2}$, $P_{3}$, and $P_{4}$) represent the points that define the line, and the circle points ($P_{12}$, $P_{23}$, and $P_{34}$) are the
calculated middle points of each line segment. Points $P_{12}$, $P_{2}$, and $P_{23}$ define the first quadratic Bezier curve, and the points $P_{23}$, $P_{3}$, and $P_{34}$ define the second
quadratic Bezier curve. Finally a straight line is drawn between points $P_{1}$ and $P_{12}$ as well as between $P_{34}$ and $P_{4}$.
The values of the \lstinline!EllipseClosure! enumeration specify if and how the
endpoints of an elliptical arc are to be joined (see \cref{ellipse}).
\begin{lstlisting}[language=modelica]
type Arrow = enumeration(None, Open, Filled, Half);
type TextStyle = enumeration(Bold, Italic, UnderLine);
type TextAlignment = enumeration(Left, Center, Right);
\end{lstlisting}
Filled shapes have the following attributes for the border and interior.
\begin{lstlisting}[language=modelica]
record FilledShape "Style attributes for filled shapes"
Color lineColor = Black "Color of border line";
Color fillColor = Black "Interior fill color";
LinePattern pattern = LinePattern.Solid "Border line pattern";
FillPattern fillPattern = FillPattern.None "Interior fill pattern";
DrawingUnit lineThickness = 0.25 "Line thickness";
end FilledShape;
\end{lstlisting}
The extent/points of the filled shape describe the theoretical
zero-thickness filled shape, and the actual rendered border is then half
inside and half outside the extent.
\subsection{Component Instance}\label{component-instance}
A component instance can be placed within a diagram or icon layer. It
has an annotation with a \lstinline!Placement! modifier to describe the placement.
Placements are defined in term of coordinate systems transformations:
\begin{lstlisting}[language=modelica]
record Transformation
Point origin = {0, 0};
Extent extent;
Real rotation(quantity="angle", unit="deg")=0;
end Transformation;
\end{lstlisting}
The origin attribute defines the position of the component in the
coordinate system of the enclosing class. The \lstinline!extent! defines the
position, size and flipping of the component, relative to the \lstinline!origin!
attribute. The \lstinline!extent! is defined relative to the \lstinline!origin! attribute of the
component instance. Given an extent \{\{x1, y1\}, \{x2, y2\}\},
x2\textless{}x1 defines horizontal flipping and y2\textless{}y1 defines
vertical flipping around the center of the object.
The \lstinline!rotation! attribute specifies rotation of the extent around the point
defined by the \lstinline!origin! attribute.
The graphical operations are applied in the order: scaling, flipping and
rotation.
\begin{lstlisting}[language=modelica]
record Placement
Boolean visible = true;
Transformation transformation "Placement in the diagram layer";
Boolean iconVisible "Visible in icon layer; for public connector";
Transformation iconTransformation "Placement in the icon layer; for public connector";
end Placement;
\end{lstlisting}
If no \lstinline!iconTransformation! is given the \lstinline!transformation! is also used for
placement in the icon layer. If no \lstinline!iconVisible! is given for a public connector the
\lstinline!visible! is also used for visibility in the icon layer.
\begin{nonnormative}
A connector can be shown in both an icon layer and a diagram
layer of a class. Since the coordinate systems typically are different,
placement information needs to be given using two different coordinate
systems. More flexibility than just using scaling and translation is
needed since the abstraction views might need different visual placement
of the connectors. The attribute \lstinline!transformation! gives the placement in
the diagram layer and \lstinline!iconTransformation! gives the placement in the icon
layer. When a connector is shown in a diagram layer, its diagram layer
is shown to facilitate opening up a hierarchical connector to allow
connections to its internal subconnectors.
\end{nonnormative}
For connectors, the icon layer is used to represent a connector when it
is shown in the icon layer of the enclosing model. The diagram layer of
the connector is used to represent it when shown in the diagram layer of
the enclosing model. Protected connectors are only shown in the diagram
layer. Public connectors are shown in both the diagram layer and the
icon layer. Non-connector components are only shown in the diagram
layer.
\subsection{Extends clause}\label{extends-clause}
Each extends-clause (and short-class-definition, as stated in \cref{annotations-for-graphical-objects})
may have layer specific annotations which describe
the rendering of the base class' icon and diagram layers in the
subclass.
\begin{lstlisting}[language=modelica]
record IconMap
Extent extent = {{0, 0}, {0, 0}};
Boolean primitivesVisible = true;
end IconMap;
record DiagramMap
Extent extent = {{0, 0}, {0, 0}};
Boolean primitivesVisible = true;
end DiagramMap;
\end{lstlisting}
All graphical objects are by default inherited from a base class. If the
\lstinline!primitivesVisible! attribute is false, components and connections are
visible but graphical primitives are not.
\begin{itemize}
\item
If the extent of the extends-clause defines a null region (the default), the base class contents is mapped to the same coordinates in the derived class, and the coordinate system (including \lstinline!preserveAspectRatio!) can be inherited as described in \cref{coordinate-systems}.
\item
If the extent of the extends-clause defines a non-null region, the base class coordinate system is mapped to the region specified by the attribute extent, if \lstinline!preserveAspectRatio! is true for the base class the mapping shall preserve the aspect ratio. The base class coordinate system (and \lstinline!preserveAspectRatio!) is not inherited.
\end{itemize}
\begin{example}
\begin{lstlisting}[language=modelica]
model A
extends B annotation(
IconMap(extent={{-100,-100}, {100,100}},primitivesVisible=false),
DiagramMap(extent={{-50,-50}, {0,0}},primitivesVisible=true)
);
end A;
model B
extends C annotation(DiagramMap(primitivesVisible=false));
...
end B;
\end{lstlisting}
In this example the diagram of \lstinline!A! contains the graphical primitives
from \lstinline!A! and \lstinline!B! (but not from \lstinline!C! since they were hidden in \lstinline!B!) -- the ones
from \lstinline!B! are rescaled, and the icon of \lstinline!A! contains the graphical primitives
from \lstinline!A! (but neither from \lstinline!B! nor from \lstinline!C!).
\end{example}
\subsection{Connections}\label{connections1}
A connection is specified with an annotation containing a \lstinline!Line! primitive and optionally a \lstinline!Text! primitive, as specified below.
\begin{example}
\begin{lstlisting}[language=modelica]
connect(a.x, b.x)
annotation(Line(points={{-25,30}, {10,30}, {10, -20}, {40,-20}}));
\end{lstlisting}
\end{example}
The optional \lstinline!Text! primitive defines a text that will be written on the connection line. It has the following definition (\emph{it is not equal to the \lstinline!Text! primitive as part of graphics -- the differences are marked as bold lines}):
% NOTE: Technically just the names -- not the entire lines are marked in bold
\begin{lstlisting}[language=modelica]
record Text
extends GraphicItem;
extends FilledShape;
Extent extent;
String string;
Real fontSize = 0 "unit pt";
String fontName;
TextStyle textStyle[:];
Color textColor=lineColor;
TextAlignment horizontalAlignment = if index<0 then TextAlignment.Right else TextAligment.Left;
Integer index;
end Text;
\end{lstlisting}
The \lstinline!index! is one of the points of Line (numbered 1, 2, 3, \ldots{} where
negative numbers count from the end, thus -1 indicate the last one). The \lstinline!string!
may use the special
symbols \lstinline!"\%first"! and \lstinline!"\%second"! to indicate the connectors in the
connect-equation.
The \lstinline!extent! and \lstinline!rotation! are relative to the \lstinline!origin! (default \lstinline!{0,0}!)
and the \lstinline!origin! is relative to the point on the Line.
The textColor attribute defines the color of the text. The text is drawn
with transparent background and no border around the text (and without
outline). The contents inherited from FilledShape is deprecated, but kept for compatibility reasons.
The default value for \lstinline!horizontalAlignment! is deprecated.
Having a zero size for the extent is deprecated and is handled as if upper part is moved up an appropriate amount.
\begin{example}
\begin{lstlisting}[language=modelica]
connect(controlBus.axisControlBus1, axis1.axisControlBus) annotation (
Text(string="%first", index=-1, extent=[-6,3; -6,7]),
Line(points={{-80,-10},{-80,-14.5},{-79,-14.5},{-79,-17},{-65,-17},{-65,-65},{-25,-65}}));
\end{lstlisting}
Draws a connection line and adds the text \emph{axisControlBus1}
ending at \{-6, 3\}+\{-25, -65\} and 4 vertical units of space for the text.
Using a height of zero, such as \lstinline!extent=[-6,3; -6,3]! is deprecated, but gives similar result.
\end{example}
\subsection{Graphical primitives}\label{graphical-primitives}
This section describes the graphical primitives that can be used to
define the graphical objects in an annotation.
\subsubsection{Line}\label{line}
A line is specified as follows:
\begin{lstlisting}[language=modelica]
record Line
extends GraphicItem;
Point points[:];
Color color = Black;
LinePattern pattern = LinePattern.Solid;
DrawingUnit thickness = 0.25;
Arrow arrow[2] = {Arrow.None, Arrow.None} "{start arrow, end arrow}";
DrawingUnit arrowSize=3;
Smooth smooth = Smooth.None "Spline";
end Line;
\end{lstlisting}
Note that the \lstinline!Line! primitive is also used to specify the graphical
representation of a connection.
For arrows:
\begin{itemize}
\item
The arrow is drawn with an aspect ratio of 1/3 for each arrow half, i.e.,
if the arrow-head is 3~mm long an arrow with Half will extend 1~mm from the
mid-line and with Open or Filled extend 1~mm to each side, in total making the base 2~mm wide.
\item
The arrowSize gives the width of the arrow (including the imagined
other half for Half) so that lineThickness=10 and arrowSize=10 will
touch at the outer parts.
\item
All arrow variants overlap for overlapping lines.
\item
The lines for the Open and Half variants are drawn with lineThickness.
\end{itemize}
\subsubsection{Polygon}\label{polygon}
A polygon is specified as follows:
\begin{lstlisting}[language=modelica]
record Polygon
extends GraphicItem;
extends FilledShape;
Point points[:];
Smooth smooth = Smooth.None "Spline outline";
end Polygon;
\end{lstlisting}
The polygon is automatically closed, if the first and the last points
are not identical.
\subsubsection{Rectangle}\label{rectangle}
A rectangle is specified as follows:
\begin{lstlisting}[language=modelica]
record Rectangle
extends GraphicItem;
extends FilledShape;
BorderPattern borderPattern = BorderPattern.None;
Extent extent;
DrawingUnit radius = 0 "Corner radius";
end Rectangle;
\end{lstlisting}
The \lstinline!extent! attribute specifies the bounding box of the rectangle. If the
\lstinline!radius! attribute is specified, the rectangle is drawn with rounded
corners of the given radius.
\subsubsection{Ellipse}\label{ellipse}
An ellipse is specified as follows:
\begin{lstlisting}[language=modelica]
record Ellipse
extends GraphicItem;
extends FilledShape;
Extent extent;
Real startAngle(quantity="angle", unit="deg")=0;
Real endAngle(quantity="angle", unit="deg")=360;
EllipseClosure closure = if startAngle == 0 and endAngle == 360
then EllipseClosure.Chord
else EllipseClosure.Radial;
end Ellipse;
\end{lstlisting}
The \lstinline!extent! attribute specifies the bounding box of the ellipse.
Partial ellipses can be drawn using the \lstinline!startAngle! and \lstinline!endAngle!
attributes. These specify the endpoints of the arc prior to the stretch
and rotate operations. The arc is drawn counter-clockwise from
\lstinline!startAngle! to \lstinline!endAngle!, where startAngle and endAngle are defined
counter-clockwise from 3 o'clock (the positive x-axis).
The closure attribute specifies whether the endpoints specified by
\lstinline!startAngle! and \lstinline!endAngle! are to be joined by lines to the centre of the
extent (\lstinline!closure=EllipseClosure.Radial!), joined by a single straight line
between the end points (\lstinline!closure=EllipseClosure.Chord!), or left
unconnected (\lstinline!closure=EllipseClosure.None!). In the latter case, the
ellipse is treated as an open curve instead of a closed shape, and the
\lstinline!fillPattern! and \lstinline!fillColor! are not applied (if present, they are
ignored).
The default closure is \lstinline!EllipseClosure.Chord! when \lstinline!startAngle! is 0 and
\lstinline!endAngle! is 360, or \lstinline!EllipseClosure.Radial! otherwise.
\begin{nonnormative}
The default for a closed ellipse is not \lstinline!EllipseClosure.None!, since that would result in \lstinline!fillColor!
and \lstinline!fillPattern! being ignored, making it impossible to draw a filled ellipse. \lstinline!EllipseClosure.Chord!
is equivalent in this case, since the chord will be of zero length.
\end{nonnormative}
\subsubsection{Text}\label{text}
A text string is specified as follows:
\begin{lstlisting}[language=modelica]
record Text
extends GraphicItem;
extends FilledShape;
Extent extent;
String textString;
Real fontSize = 0 "unit pt";
String fontName;
TextStyle textStyle[:];
Color textColor=lineColor;
TextAlignment horizontalAlignment = TextAlignment.Center;
end Text;
\end{lstlisting}
The \lstinline!textColor! attribute defines the color of the text. The text is drawn
with transparent background and no border around the text (and without
outline). The contents inherited from \lstinline!FilledShape! is deprecated, but kept for compatibility reasons.
There are a number of common macros that can be used in the text, and
they should be replaced when displaying the text as follows (in order such that the earliest ones have precedence,
and using the longest sequence of identifier characters - alphanumeric and underscore):
\begin{itemize}
\item
\%\% replaced by \%
\item
\%name replaced by the name of the component (i.e., the identifier for
it in the enclosing class).
\item
\%class replaced by the name of the class (only the last part of the hierarchical name).
\item
\%\emph{par} and \%\{\emph{par\}} replaced by the value of the
parameter \lstinline!par!.
If the value is numeric, tools shall display the value with \lstinline!displayUnit!, formatted according to bipm-specification.
E.g., for
\begin{lstlisting}[language=modelica]
parameter Real t(unit="s", displayUnit="ms") = 0.1
\end{lstlisting}
tools shall display \emph{100 ms}.
The intent is that the text is easily readable,
thus if \lstinline!par! is of an enumeration type, replace \lstinline!%par! by the item name,
not by the full name.
\begin{example}
If \lstinline!par = "Modelica.Blocks.Types.Enumeration.Periodic"!, then \lstinline!%par! should be displayed as \emph{Periodic}.
\end{example}
The form \%\{\emph{par\}} allows component-references and is required for quoted identifiers, and can be directly
followed by a letter. Thus \lstinline!%{w}x%{h}! gives the value of \lstinline!w!
directly followed by \emph{x} and the value of \lstinline!h!, while \lstinline!%wxh! gives the value of the
parameter \lstinline!wxh!. If the parameter does not exist it is an error.
\end{itemize}
The style attribute \lstinline!fontSize! specifies the font size. If the \lstinline!fontSize!
attribute is 0 the text is scaled to fit its extent. Otherwise, the size
specifies the absolute size. The text is vertically centered in the extent.
If the \lstinline!extent! specifies a box with zero width and positive height the
height is used as height for the text (unless \lstinline!fontSize! attribute is
non-zero -- which specifies the absolute size), and the text is not
truncated (the \lstinline!horizontalAlignment! is still used in this case).
\begin{nonnormative}
A zero-width \lstinline!extent! is convenient for handling texts where the width is unknown.
\end{nonnormative}
If the string \lstinline!fontName! is empty, the tool may choose a font. The font names \lstinline!"serif"!, \lstinline!"sans-serif"!, and \lstinline!"monospace"! shall be recognized. If possible
the correct font should be used -- otherwise a reasonable match, or treat as if \lstinline!fontName! was empty.
The style attribute \lstinline!textStyle! specifies variations of the font.
\subsubsection{Bitmap}\label{bitmap}
A bitmap image is specified as follows:
\begin{lstlisting}[language=modelica]
record Bitmap
extends GraphicItem;
Extent extent;
String fileName "Name of bitmap file";
String imageSource "Base64 representation of bitmap";
end Bitmap;
\end{lstlisting}
The \lstinline!Bitmap! primitive renders a graphical bitmap image. The data of the
image can either be stored on an external file or in the annotation
itself. The image is scaled to fit the extent. Given an extent \{\{x1,
y1\}, \{x2, y2\}\}, x2\textless{}x1 defines horizontal flipping and
y2\textless{}y1 defines vertical flipping around the center of the
object.
The graphical operations are applied in the order: scaling, flipping and
rotation.
When the attribute \lstinline!fileName! is specified, the string refers to an
external file containing image data. The mapping from the string to the
file is specified for some URIs in \cref{external-resources}. The supported file
formats include \lstinline!PNG!, \lstinline!BMP!, \lstinline!JPEG!,
and \lstinline!SVG!.
When the attribute \lstinline!imageSource! is specified, the string contains the
image data, and the image format is determined based on the contents.
The image is represented as a Base64 encoding of the image file format
(see RFC~4648, \url{http://tools.ietf.org/html/rfc4648}).
The image is uniformly scaled (preserving the aspect ratio) so it exactly fits within the extent (touching the
extent along one axis). The center of the image is positioned at the center of the extent.
\subsection{Variable Graphics and Schematic Animation}\label{variable-graphics-and-schematic-animation}
Any value (coordinates, color, text, etc.) in graphical annotations can
be dependent on class variables using the \lstinline!DynamicSelect! expression.
\lstinline!DynamicSelect! has the syntax of a function call with two arguments,
where the first argument specifies the value of the editing state and
the second argument the value of the non-editing state. The first
argument must be a literal expression. The second argument may contain
references to variables to enable a dynamic behavior.
\begin{example}
The level of a tank could be animated by a
rectangle expanding in vertical direction and its color depending on a
variable overflow:
\begin{lstlisting}[language=modelica]
annotation (
Icon(graphics={Rectangle(
extent=DynamicSelect({{0,0},{20,20}},{{0,0},{20,level}}),
fillColor=DynamicSelect({0,0,255},
if overflow then {255,0,0} else {0,0,255}))})
);
\end{lstlisting}
\end{example}
\subsection{User input}\label{user-input}
It is possible to interactively modify variables during a simulation.
The variables may either be parameters, discrete-time variables or states.
New numeric values can be given, a mouse click can change a Boolean
variable or a mouse movement can change a Real variable. Input fields
may be associated with a \lstinline!GraphicItem! or a component as an array named
\lstinline!interaction!. The \lstinline!interaction! array may occur as an attribute of a
graphic primitive, an attribute of a component annotation or as an
attribute of the layer annotation of a class.
\subsubsection{Mouse input}\label{mouse-input}
A Boolean variable can be changed when the cursor is held over a
graphical item or component and the selection button is pressed if the
interaction annotation contains \lstinline!OnMouseDownSetBoolean!:
\begin{lstlisting}[language=modelica]
record OnMouseDownSetBoolean
Boolean variable "Name of variable to change when mouse button pressed";
Boolean value "Assigned value";
end OnMouseDownSetBoolean;
\end{lstlisting}
\begin{example}
A button can be represented by a rectangle changing color depending on a \lstinline!Boolean! variable \lstinline!on! and toggles the
variable when the rectangle is clicked on:
\begin{lstlisting}[language=modelica]
annotation (Icon(
graphics={Rectangle(
extent=[0,0; 20,20],
fillColor=if on then {255,0,0} else {0,0,255})},
interaction={OnMouseDownSetBoolean (on, not on)}));
\end{lstlisting}
\end{example}
In a similar way, a variable can be changed when the mouse button is
\emph{released}:
\begin{lstlisting}[language=modelica]
record OnMouseUpSetBoolean
Boolean variable "Name of variable to change when mouse button released";
Boolean value "Assigned value";
end OnMouseUpSetBoolean;
\end{lstlisting}
Note that several interaction objects can be associated with the same
graphical item or component.
\begin{example}
\begin{lstlisting}[language=modelica]
interaction={ OnMouseDownSetBoolean(on, true), OnMouseUpSetBoolean(on, false)};
\end{lstlisting}
\end{example}
The \lstinline!OnMouseMoveXSetReal! interaction object sets the variable to the
position of the cursor in X direction in the local coordinate system
mapped to the interval defined by the \lstinline!minValue! and \lstinline!maxValue! attributes.
\begin{lstlisting}[language=modelica]
record OnMouseMoveXSetReal
Real xVariable "Name of variable to change when cursor moved in x direction";
Real minValue;
Real maxValue;
end OnMouseMoveXSetReal;
\end{lstlisting}
The \lstinline!OnMouseMoveYSetReal! interaction object works in a corresponding way
as the \lstinline!OnMouseMoveXSetReal! object but in the Y direction.
\begin{lstlisting}[language=modelica]
record OnMouseMoveYSetReal
Real yVariable "Name of variable to change when cursor moved in y direction";
Real minValue;
Real maxValue;
end OnMouseMoveYSetReal;
\end{lstlisting}
\subsubsection{Edit input}\label{edit-input}
The \lstinline!OnMouseDownEditInteger! interaction object presents an input field
when the graphical item or component is clicked on. The field shows the
actual value of the variable and allows changing the value. If a too
small or too large value according to the \lstinline!min! and \lstinline!max! parameter values
of the variable is given, the input is rejected.
\begin{lstlisting}[language=modelica]
record OnMouseDownEditInteger
Integer variable "Name of variable to change";
end OnMouseDownEditInteger;
\end{lstlisting}
The \lstinline!OnMouseDownEditReal! interaction object presents an input field when
the graphical item or component is clicked on. The field shows the
actual value of the variable and allows changing the value. If a too
small or too large value according to the \lstinline!min! and \lstinline!max! parameter values
of the variable is given, the input is rejected.
\begin{lstlisting}[language=modelica]
record OnMouseDownEditReal
Real variable "Name of variable to change";
end OnMouseDownEditReal;
\end{lstlisting}
The \lstinline!OnMouseDownEditString! interaction object presents an input field