--- title: Common Component Features order: 3 layout: page --- [[components.features]] = Common Component Features The component base classes and interfaces provide a large number of features. Let us look at some of the most commonly needed features. Features not documented here can be found from the Java API Reference. The interface defines a number of properties, which you can retrieve or manipulate with the corresponding setters and getters. [[components.features.caption]] == Caption ((("caption property"))) ((("Component interface", "caption"))) A caption is an explanatory textual label accompanying a user interface component, usually shown above, left of, or inside the component. The contents of a caption are automatically quoted, so no raw HTML can be rendered in a caption. The caption text can usually be given as the first parameter of a constructor of a component or with [methodname]#setCaption()#. [source, java] ---- // New text field with caption "Name" TextField name = new TextField("Name"); layout.addComponent(name); ---- The caption of a component is, by default, managed and displayed by the layout component or component container inside which the component is placed. For example, the [classname]#VerticalLayout# component shows the captions left-aligned above the contained components, while the [classname]#FormLayout# component shows the captions on the left side of the vertically laid components, with the captions and their associated components left-aligned in their own columns. The [classname]#CustomComponent# does not manage the caption of its composition root, so if the root component has a caption, it will not be rendered. [[figure.components.features.caption.layoutmanaged]] .Caption Management by [classname]#VerticalLayout# and [classname]#FormLayout#. image::img/features-caption-layoutmanaged.png[width=50%,scaledwidth=65%] Some components, such as [classname]#Button# and [classname]#Panel#, manage the caption themselves and display it inside the component. Icon (see <>) is closely related to caption and is usually displayed horizontally before or after it, depending on the component and the containing layout. Also the required indicator in field components is usually shown before or after the caption. An alternative way to implement a caption is to use another component as the caption, typically a [classname]#Label#, a [classname]#TextField#, or a [classname]#Panel#. A [classname]#Label#, for example, allows highlighting a shortcut key with HTML markup or to bind the caption to a data source. The [classname]#Panel# provides an easy way to add both a caption and a border around a component. === CSS Style Rules [source, css] ---- .v-caption {} .v-captiontext {} .v-required-field-indicator {} ---- A caption is be rendered inside an HTML element that has the [literal]#++v-caption++# CSS style class. The containing layout may enclose a caption inside other caption-related elements. Some layouts put the caption text in a [literal]#++v-captiontext++# element. An optional required indicator in field components is contained in a separate element with [literal]#++v-required-field-indicator++# style. [[components.features.description]] == Description and Tooltips ((("description property"))) ((("Component interface", "description"))) ((("tooltips"))) All components (that inherit [classname]#AbstractComponent#) have a description separate from their caption. The description is usually shown as a tooltip that appears when the mouse pointer hovers over the component for a short time. You can set the description with [methodname]#setDescription()# and retrieve with [methodname]#getDescription()#. [source, java] ---- Button button = new Button("A Button"); button.setDescription("This is the tooltip"); ---- The tooltip is shown in <>. [[figure.components.tooltip.plain]] .Component Description as a Tooltip image::img/tooltip-plain-withpointer-hi.png[width=30%, scaledwidth=100%] A description is rendered as a tooltip in most components. When a component error has been set with [methodname]#setComponentError()#, the error is usually also displayed in the tooltip, below the description. Components that are in error state will also display the error indicator. See <>. The description is actually not plain text, but you can use HTML tags to format it. Such a rich text description can contain any HTML elements, including images. [source, java] ---- button.setDescription( "

"+ "A richtext tooltip

"+ "
    "+ "
  • Use rich formatting with HTML
    • "+ "
  • Include images from themes
    • "+ "
  • etc.
    • "+ "
"); ---- The result is shown in <>. [[figure.components.tooltip.richtext]] .A Rich Text Tooltip image::img/tooltip-richtext-withpointer-hi.png[width=40%, scaledwidth=75%] [[components.features.enabled]] == Enabled ((("enabled property"))) ((("Component interface", "enabled"))) The __enabled__ property controls whether the user can actually use the component. A disabled component is visible, but grayed to indicate the disabled state. Components are always enabled by default. You can disable a component with [methodname]#setEnabled(false)#. [source, java] ---- Button enabled = new Button("Enabled"); enabled.setEnabled(true); // The default layout.addComponent(enabled); Button disabled = new Button("Disabled"); disabled.setEnabled(false); layout.addComponent(disabled); ---- <> shows the enabled and disabled buttons. [[figure.components.features.enabled.simple]] .An Enabled and Disabled [classname]#Button# image::img/features-enabled-simple.png[width=30%, scaledwidth=50%] A disabled component is automatically put in read-only like state. No client interaction with a disabled component is sent to the server and, as an important security feature, the server-side components do not receive state updates from the client in the disabled state. This feature exists in all built-in components in the Framework meaning all client to server RPC calls are ignored for disabled components. === CSS Style Rules Disabled components have the [literal]#++v-disabled++# CSS style in addition to the component-specific style. To match a component with both the styles, you have to join the style class names with a dot as done in the example below. [source, css] ---- .v-textfield.v-disabled { border: dotted; } ---- This would make the border of all disabled text fields dotted. In the Valo theme, the opacity of disabled components is specified with the `$v-disabled-opacity` parameter. [[components.features.icon]] == Icon ((("icon property"))) ((("Component interface", "icon"))) An icon is an explanatory graphical label accompanying a user interface component, usually shown above, left of, or inside the component. Icon is closely related to caption (see <>) and is usually displayed horizontally before or after it, depending on the component and the containing layout. The icon of a component can be set with the [methodname]#setIcon()# method. The image is provided as a resource, perhaps most typically a [classname]#ThemeResource#. [source, java] ---- // Component with an icon from a custom theme TextField name = new TextField("Name"); name.setIcon(new ThemeResource("icons/user.png")); layout.addComponent(name); // Component with an icon from another theme ('runo') Button ok = new Button("OK"); ok.setIcon(new ThemeResource("../runo/icons/16/ok.png")); layout.addComponent(ok); ---- The icon of a component is, by default, managed and displayed by the layout component or component container in which the component is placed. For example, the [classname]#VerticalLayout# component shows the icons left-aligned above the contained components, while the [classname]#FormLayout# component shows the icons on the left side of the vertically laid components, with the icons and their associated components left-aligned in their own columns. The [classname]#CustomComponent# does not manage the icon of its composition root, so if the root component has an icon, it will not be rendered. [[figure.components.features.icon]] .Displaying an Icon from a Theme Resource. image::img/features-icon.png[width=40%, scaledwidth=60%] Some components, such as [classname]#Button# and [classname]#Panel#, manage the icon themselves and display it inside the component. In addition to image resources, you can use __font icons__, which are icons included in special fonts, but which are handled as special resources. See <> for more details. === CSS Style Rules An icon will be rendered inside an HTML element that has the [literal]#++v-icon++# CSS style class. The containing layout may enclose an icon and a caption inside elements related to the caption, such as [literal]#++v-caption++#. [[components.features.locale]] == Locale ((("locale property", "in [classname]#Component#"))) ((("Component interface", "locale"))) The locale property defines the country and language used in a component. You can use the locale information in conjunction with an internationalization scheme to acquire localized resources. Some components, such as [classname]#DateField#, use the locale for component localization. You can set the locale of a component (or the application) with [methodname]#setLocale()# as follows: [source, java] ---- // Component for which the locale is meaningful InlineDateField date = new InlineDateField("Datum"); // German language specified with ISO 639-1 language // code and ISO 3166-1 alpha-2 country code. date.setLocale(new Locale("de", "DE")); date.setResolution(Resolution.DAY); layout.addComponent(date); ---- The resulting date field is shown in <>. [[figure.components.features.locale.simple]] .Set locale for [classname]#InlineDateField# image::img/features-locale-simple.png[width=40%, scaledwidth=60%] [[components.features.locale.get]] === Getting the Locale ((("[methodname]#getLocale()#"))) You can get the locale of a component with [methodname]#getLocale()#. If the locale is undefined for a component, that is, not explicitly set, the locale of the parent component is used. If none of the parent components have a locale set, the locale of the UI is used, and if that is not set, the default system locale is set, as given by [methodname]#Locale.getDefault()#. The [methodname]#getLocale()# returns null if the component is not yet attached to the UI, which is usually the case in most constructors, so it is a bit awkward to use it for internationalization. You can get the locale in [methodname]#attach()#, as shown in the following example: [source, java] ---- Button cancel = new Button() { @Override public void attach() { super.attach(); ResourceBundle bundle = ResourceBundle.getBundle( MyAppCaptions.class.getName(), getLocale()); setCaption(bundle.getString(MyAppCaptions.CancelKey)); } }; layout.addComponent(cancel); ---- However, it is normally a better practice to use the locale of the current UI to get the localized resource right when the component is created. [source, java] ---- // Captions are stored in MyAppCaptions resource bundle // and the UI object is known in this context. ResourceBundle bundle = ResourceBundle.getBundle(MyAppCaptions.class.getName(), UI.getCurrent().getLocale()); // Get a localized resource from the bundle Button cancel = new Button(bundle.getString(MyAppCaptions.CancelKey)); layout.addComponent(cancel); ---- [[component.features.locale.selecting]] === Selecting a Locale A common task in many applications is selecting a locale. The locale can be set for the [classname]#UI# or single [classname]#Component#. By default each component uses the locale from the [classname]#UI# it has been attached to. Setting a locale to a [classname]#Component# only applies the locale to that component and its children. Note, that updating the locale for a component does not update its children, thus any child component that uses the locale should be updated manually. [[components.features.readonly]] == Read-Only ((("read-only property"))) ((("Component interface", "read-only"))) The property defines whether the value of a component can be changed. The property is only applicable to components implementing the [interfacename]#HasValue# interface. [source, java] ---- TextField readwrite = new TextField("Read-Write"); readwrite.setValue("You can change this"); readwrite.setReadOnly(false); // The default TextField readonly = new TextField("Read-Only"); readonly.setValue("You can't touch this!"); readonly.setReadOnly(true); ---- The resulting read-only text field is shown in <>. [[figure.components.features.readonly.simple]] .A read-only component image::img/features-readonly-simple.png[width=50%, scaledwidth=80%] Notice that the value of a selection component is the selection, not its items. A read-only selection component doesn't therefore allow its selection to be changed, but other changes are possible. For example, if you have a [classname]#Grid# with a read-only selection model in editable mode, its contained fields and the underlying data model can still be edited, and the user could sort it or reorder the columns. Client-side state modifications will not be communicated to the server-side and, more importantly, server-side field components will not accept changes to the value of a read-only [classname]#HasValue# component. The latter is an important security feature, because a malicious user can not fabricate state changes in a read-only field. Also notice that while the read-only status applies automatically to the value of a field, it does not apply to other component variables. A read-only component can accept some other state changes from the client-side and some of such changes could be acceptable, such as change in the scroll bar position of a [classname]#ListSelect#. Custom components should check the read-only state for variables bound to business data. === CSS Style Rules Setting a normally editable component to read-only state can change its appearance to disallow editing the value. In addition to CSS styling, also the HTML structure can change. For example, [classname]#TextField# loses the edit box and appears much like a [classname]#Label#. A read-only component will have the [literal]#++v-readonly++# style. The following CSS rule would make the text in all read-only [classname]#TextField# components appear in italic. [source, css] ---- .v-textfield.v-readonly { font-style: italic; } ---- [[components.features.stylename]] == Style Name ((("style name property"))) ((("Component interface", "style name"))) The __style name__ property defines one or more custom CSS style class names for the component. The [methodname]#getStyleName()# returns the current style names as a space-separated list. The [methodname]#setStyleName()# replaces all the styles with the given style name or a space-separated list of style names. You can also add and remove individual style names with [methodname]#addStylename()# and [methodname]#removeStyleName()#. A style name must be a valid CSS style name. [source, java] ---- Label label = new Label("This text has a lot of style"); label.addStyleName("mystyle"); layout.addComponent(label); ---- The style name will appear in the component's HTML element in two forms: literally as given and prefixed with the component-specific style name. For example, if you add a style name [literal]#++mystyle++# to a [classname]#Button#, the component would get both [literal]#++mystyle++# and [literal]#++v-button-mystyle++# styles. Neither form may conflict with built-in style names of Vaadin. For example, [literal]#++focus++# style would conflict with a built-in style of the same name, and an [literal]#++content++# style for a [classname]#Panel# component would conflict with the built-in [literal]#++v-panel-content++# style. The following CSS rule would apply the style to any component that has the [literal]#++mystyle++# style. [source, css] ---- .mystyle { font-family: fantasy; font-style: italic; font-size: 25px; font-weight: bolder; line-height: 30px; } ---- The resulting styled component is shown in <> [[figure.components.features.stylename]] .Component with a custom style image::img/features-stylename-simple.png[width=50%, scaledwidth=75%] [[components.features.visible]] == Visible ((("visible property"))) ((("Component interface", "visible"))) Components can be hidden by setting the __visible__ property to __false__. Also the caption, icon and any other component features are made hidden. Hidden components are not just invisible, but their content is not communicated to the browser at all. That is, they are not made invisible cosmetically with only CSS rules. This feature is important for security if you have components that contain security-critical information that must only be shown in specific application states. [source, java] ---- TextField invisible = new TextField("No-see-um"); invisible.setValue("You can't see this!"); invisible.setVisible(false); layout.addComponent(invisible); ---- If you need to make a component only cosmetically invisible, you should use a custom theme to set it [literal]#++display: none++# style. This is mainly useful for some special components that have effects even when made invisible in CSS. If the hidden component has undefined size and is enclosed in a layout that also has undefined size, the containing layout will collapse when the component disappears. If you want to have the component keep its size, you have to make it invisible by setting all its font and other attributes to be transparent. In such cases, the invisible content of the component can be made visible easily in the browser. [[components.features.sizeable]] == Sizing Components ((("[classname]#Sizeable# interface"))) Vaadin components are sizeable; not in the sense that they were fairly large or that the number of the components and their features are sizeable, but in the sense that you can make them fairly large on the screen if you like, or small or whatever size. The [classname]#Sizeable# interface, shared by all components, provides a number of manipulation methods and constants for setting the height and width of a component in absolute or relative units, or for leaving the size undefined. The size of a component can be set with [methodname]#setWidth()# and [methodname]#setHeight()# methods. The methods take the size as a floating-point value. You need to give the unit of the measure as the second parameter for the above methods. [source, java] ---- mycomponent.setWidth(100, Unit.PERCENTAGE); mycomponent.setWidth(400, Unit.PIXELS); ---- Alternatively, you can specify the size as a string. The format of such a string must follow the HTML/CSS standards for specifying measures. [source, java] ---- mycomponent.setWidth("100%"); mycomponent.setHeight("400px"); ---- The "[literal]#++100%++#" percentage value makes the component take all available size in the particular direction. You can also use the shorthand method [methodname]#setSizeFull()# to set the size to 100% in both directions. The size can be __undefined__ in either or both dimensions, which means that the component will take the minimum necessary space. Most components have undefined size by default, but some layouts have full size in horizontal direction. You can set the height, width, or both as undefined with the methods [methodname]#setWidthUndefined()#, [methodname]#setHeightUndefined()#, and [methodname]#setSizeUndefined()#, respectively. Always keep in mind that _a layout with undefined size may not contain components with defined relative size_, such as "full size", except in some special cases. See <> for details. If a component inside [classname]#HorizontalLayout# or [classname]#VerticalLayout# has full size in the namesake direction of the layout, the component will expand to take all available space not needed by the other components. See <> for details. == Managing Input Focus When the user clicks on a component, the component gets the __input focus__, which is indicated by highlighting according to style definitions. If the component allows inputting text, the focus and insertion point are indicated by a cursor. Pressing the Tab key moves the focus to the component next in the __focus order__. Focusing is supported by all [classname]#AbstractField# and [classname]#AbstractListing# components and also by components such as [classname]#Button#, [classname]#Upload#, and [classname]#TabSheet#. The focus order or __tab index__ of a component is defined as a positive integer value, which you can set with [methodname]#setTabIndex()# and get with [methodname]#getTabIndex()#. The tab index is managed in the context of the page in which the components are contained. The focus order can therefore jump between two any lower-level component containers, such as sub-windows or panels. The default focus order is determined by the natural hierarchical order of components in the order in which they were added under their parents. The default tab index is 0 (zero). Giving a negative integer as the tab index removes the component from the focus order entirely. === CSS Style Rules The component having the focus will have an additional style class with the [literal]#++-focus++# suffix. For example, a [classname]#TextField#, which normally has the [literal]#++v-textfield++# style, would additionally have the [literal]#++v-textfield-focus++# style. For example, the following would make a text field blue when it has focus. [source, css] ---- .v-textfield-focus { background: lightblue; } ---- 5/stable29'>backport/47425/stable29 Nextcloud server, a safe home for all your data: https://github.com/nextcloud/serverwww-data
aboutsummaryrefslogtreecommitdiffstats
path: root/lib/private/helper.php
blob: 1aab2f296e1f10766e49bd5167291a2fff12acf8 (plain) 
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