diff options
Diffstat (limited to 'documentation')
18 files changed, 167 insertions, 2862 deletions
diff --git a/documentation/components/chapter-components.asciidoc b/documentation/components/chapter-components.asciidoc index f54db8ac74..f92a132e98 100644 --- a/documentation/components/chapter-components.asciidoc +++ b/documentation/components/chapter-components.asciidoc @@ -46,12 +46,6 @@ include::components-twincolselect.asciidoc[leveloffset=+2] include::components-grid.asciidoc[leveloffset=+2] -include::components-table.asciidoc[leveloffset=+2] - -include::components-tree.asciidoc[leveloffset=+2] - -include::components-treetable.asciidoc[leveloffset=+2] - include::components-menubar.asciidoc[leveloffset=+2] include::components-upload.asciidoc[leveloffset=+2] @@ -62,8 +56,6 @@ include::components-slider.asciidoc[leveloffset=+2] include::components-popupview.asciidoc[leveloffset=+2] -include::components-calendar.asciidoc[leveloffset=+2] - include::components-customcomponent.asciidoc[leveloffset=+2] include::components-customfield.asciidoc[leveloffset=+2] diff --git a/documentation/components/components-calendar.asciidoc b/documentation/components/components-calendar.asciidoc deleted file mode 100644 index 79b077348b..0000000000 --- a/documentation/components/components-calendar.asciidoc +++ /dev/null @@ -1,1187 +0,0 @@ ---- -title: Calendar -order: 30 -layout: page ---- - -[[components.calendar]] -= [classname]#Calendar# - -*_This section has not yet been updated for Vaadin Framework 8._* - -ifdef::web[] -[.sampler] -image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/data-input/dates/dates-calendar"] -endif::web[] - -The [classname]#Calendar# component allows organizing and displaying calendar -events. The main features of the calendar include: - -* Monthly, weekly, and daily views -* Two types of events: all-day events and events with a time range -* Add events directly or with an event provider -* Control the range of the visible dates -* Selecting and editing date or time range by dragging -* Drag and drop events to calendar -* Support for localization and timezones - -User interaction with the calendar elements, such as date and week captions as -well as events, is handled with event listeners. Also date/time range -selections, event dragging, and event resizing can be listened by the server. -The weekly view has navigation buttons to navigate forward and backward in time. -These actions are also listened by the server. Custom navigation can be -implemented using event -ifdef::web[handlers, as described in <<components.calendar.customizing>>.] -ifndef::web[handlers.] - -The data source of a calendar can be practically anything, as its events are -queried dynamically by the component. You can bind the calendar to any data source by implementing an __event provider__. - -The [classname]#Calendar# has undefined size by default and you usually want to -give it a fixed or relative size, for example as follows. - - -[source, java] ----- -Calendar cal = new Calendar("My Calendar"); -cal.setWidth("600px"); -cal.setHeight("300px"); ----- - -After creating the calendar, you need to set a time range for it, which also -controls the view mode, and set up the data source for calendar events. - -[[components.calendar.daterange]] -== Date Range and View Mode - -The Vaadin Calendar has two types of views that are shown depending on the date -range of the calendar. The __weekly view__ displays a week by default. It can -show anything between one to seven days a week, and is also used as a single-day -view. The view mode is determined from the __date range__ of the calendar, -defined by a start and an end date. Calendar will be shown in a __monthly view__ -when the date range is over than one week (seven days) long. The date range is -always calculated in an accuracy of one millisecond. - -[[figure.components.calendar.daterange.monthly]] -.Monthly view with All-Day and Normal Events -image::img/calendar-monthly.png[width=60%, scaledwidth=100%] - -The monthly view, shown in <<figure.components.calendar.daterange.monthly>>, can -easily be used to control all types of events, but it is best suited for events -that last for one or more days. You can drag the events to move them. In the -figure, you can see two longer events that are highlighted with a blue and green -background color. Other markings are shorter day events that last less than a 24 -hours. These events can not be moved by dragging in the monthly view. - -[[figure.components.calendar.daterange.weekly]] -.Weekly View -image::img/calendar-weekly.png[width=60%, scaledwidth=100%] - -In <<figure.components.calendar.daterange.weekly>>, you can see four normal day -events and also all-day events at the top of the time line grid. - -In the following, we set the calendar to show only one day, which is the current -day. - - -[source, java] ----- -cal.setStartDate(new Date()); -cal.setEndDate(new Date()); ----- - -Notice that although the range we set above is actually zero time long, the -calendar still renders the time from 00:00 to 23:59. This is normal, as the -Vaadin Calendar is guaranteed to render at least the date range provided, but -may expand it. This behaviour is important to notice when we implement our own -event providers. - - -[[components.calendar.events]] -== Calendar Events - -All occurrences in a calendar are represented as __events__. You have three ways -to manage the calendar events: - -* Add events directly to the [classname]#Calendar# object using the [methodname]#addEvent()# -* Use the __event provider__ mechanism - -You can add events with [methodname]#addEvent()# and remove them with the -[methodname]#removeEvent()#. These methods will use the underlying event -provider to write the modifications to the data source. - -[[components.calendar.events.types]] -=== Event Interfaces and Providers - -Events are handled though the [interfacename]#CalendarEvent# interface. The -concrete class of the event depends on the specific -[classname]#CalendarEventProvider# used in the calendar. - -By default, [classname]#Calendar# uses a [classname]#BasicEventProvider# to -provide events, which uses [classname]#BasicEvent# instances. - -Calendar does not depend on any particular data source implementation. Events -are queried by the [classname]#Calendar# from the provider that just has to -implement the [interfacename]#CalendarEventProvider# interface. It is up to the -event provider that [classname]#Calendar# gets the correct events. - -ifdef::vaadin7[] -You can bind any Vaadin [classname]#Container# to a calendar, in which case a -[classname]#ContainerEventProvider# is used transparently. The container must be -ordered by start date and time of the events. See -<<dummy/../../../framework/datamodel/datamodel-container#datamodel.container,"Collecting -Items in Containers">> for basic information about containers. -endif::vaadin7[] - -[[components.calendar.events.details]] -=== Event Types - -A calendar event requires a start time and an end time. These are the only -mandatory properties. In addition, an event can also be set as an all-day event -by setting the [literal]#++all-day++# property of the event. You can also set -the [literal]#++description++# of an event, which is displayed as a tooltip in -the user interface. - -If the [literal]#++all-day++# field of the event is [literal]#++true++#, then -the event is always rendered as an all-day event. In the monthly view, this -means that no start time is displayed in the user interface and the event has an -colored background. In the weekly view, all-day events are displayed in the -upper part of the screen, and rendered similarly to the monthly view. In -addition, when the time range of an event is 24 hours or longer, it is rendered -as an all-day event in the monthly view. - -When the time range of an event is equal or less than 24 hours, with the -accuracy of one millisecond, the event is considered as a normal day event. -Normal event has a start and end times that may be on different days. - - -[[components.calendar.events.basic]] -=== Basic Events - -The easiest way to add and manage events in a calendar is to use the __basic -event__ management API. Calendar uses by default a -[classname]#BasicEventProvider#, which keeps the events in memory in an internal -reprensetation. - -For example, the following adds a two-hour event starting from the current time. -The standard Java [classname]#GregorianCalendar# provides various ways to -manipulate date and time. - - -[source, java] ----- -// Add a two-hour event -GregorianCalendar start = new GregorianCalendar(); -GregorianCalendar end = new GregorianCalendar(); -end.add(java.util.Calendar.HOUR, 2); -calendar.addEvent(new BasicEvent("Calendar study", - "Learning how to use Vaadin Calendar", - start.getTime(), end.getTime())); ----- -See the http://demo.vaadin.com/book-examples-vaadin7/book#calendar.monthlyview[on-line example, window="_blank"]. - -This adds a new event that lasts for 3 hours. As the BasicEventProvider and -BasicEvent implement some optional event interfaces provided by the calendar -package, there is no need to refresh the calendar. Just create events, set their -properties and add them to the Event Provider. - -ifdef::vaadin7[] -[[components.calendar.container]] -== Getting Events from a Container - -You can use any Vaadin [interfacename]#Container# that implements the -[interfacename]#Indexed# interface as the data source for calendar events. The -[classname]#Calendar# will listen to change events from the container as well as -write changes to the container. You can attach a container to a -[classname]#Calendar# with [methodname]#setContainerDataSource()#. - -In the following example, we bind a [classname]#BeanItemContainer# that contains -built-in [classname]#BasicEvent# events to a calendar. - - -[source, java] ----- -// Create the calendar -Calendar calendar = new Calendar("Bound Calendar"); - -// Use a container of built-in BasicEvents -final BeanItemContainer<BasicEvent> container = - new BeanItemContainer<BasicEvent>(BasicEvent.class); - -// Create a meeting in the container -container.addBean(new BasicEvent("The Event", "Single Event", - new GregorianCalendar(2012,1,14,12,00).getTime(), - new GregorianCalendar(2012,1,14,14,00).getTime())); - -// The container must be ordered by the start time. You -// have to sort the BIC every time after you have added -// or modified events. -container.sort(new Object[]{"start"}, new boolean[]{true}); - -calendar.setContainerDataSource(container, "caption", - "description", "start", "end", "styleName"); ----- -See the http://demo.vaadin.com/book-examples-vaadin7/book#calendar.beanitemcontainer[on-line example, window="_blank"]. - -The container must either use the default property IDs for event data, as -defined in the [interfacename]#CalendarEvent# interface, or provide them as -parameters for the [methodname]#setContainerDataSource()# method, as we did in -the example above. - -[[components.calendar.container.sorting]] -=== Keeping the Container Ordered - -The events in the container __must__ be kept ordered by their start date/time. -Failing to do so may and will result in the events not showing in the calendar -properly. - -Ordering depends on the container. With some containers, such as -[classname]#BeanItemContainer#, you have to sort the container explicitly every -time after you have added or modified events, usually with the -[methodname]#sort()# method, as we did in the example above. Some container, -such as [classname]#JPAContainer#, keep the in container automatically order if -you provide a sorting rule. - -For example, you could order a [classname]#JPAContainer# by the following rule, -assuming that the start date/time is held in the [literal]#++startDate++# -property: - - -[source, java] ----- -// The container must be ordered by start date. For JPAContainer -// we can just set up sorting once and it will stay ordered. -container.sort(new String[]{"startDate"}, new boolean[]{true}); ----- -See the http://demo.vaadin.com/book-examples-vaadin7/book#calendar.jpacontainer[on-line example, window="_blank"]. - - -ifdef::web[] -[[components.calendar.container.customization]] -=== Delegation of Event Management - -Setting a container as the calendar data source with -[methodname]#setContainerDataSource()# automatically switches to -[classname]#ContainerEventProvider#. You can manipulate the event data through -the API in [classname]#Calendar# and the user can move and resize event through -the user interface. The event provider delegates all such calendar operations to -the container. - -If you add events through the [classname]#Calendar# API, notice that you may be -unable to create events of the type held in the container or adding them -requires some container-specific operations. In such case, you may need to -customize the [methodname]#addEvent()# method. - -For example, [classname]#JPAContainer# requires adding new items with -[methodname]#addEntity()#. You could first add the entity to the container or -entity manager directly and then pass it to the [methodname]#addEvent()#. That -does not, however, work if the entity class does not implement -[interfacename]#CalendarEvent#. This is actually the case always if the property -names differ from the ones defined in the interface. You could handle creating -the underlying entity objects in the [methodname]#addEvent()# as follows: - - -[source, java] ----- -// Create a JPAContainer -final JPAContainer<MyCalendarEvent> container = - JPAContainerFactory.make(MyCalendarEvent.class, - "book-examples"); - -// Customize the event provider for adding events -// as entities -ContainerEventProvider cep = - new ContainerEventProvider(container) { - @Override - public void addEvent(CalendarEvent event) { - MyCalendarEvent entity = new MyCalendarEvent( - event.getCaption(), event.getDescription(), - event.getStart(), event.getEnd(), - event.getStyleName()); - container.addEntity(entity); - } -} - -// Set the container as the data source -calendar.setEventProvider(cep); - -// Now we can add events to the database through the calendar -BasicEvent event = new BasicEvent("The Event", "Single Event", - new GregorianCalendar(2012,1,15,12,00).getTime(), - new GregorianCalendar(2012,1,15,14,00).getTime()); -calendar.addEvent(event); ----- -endif::web[] -endif::vaadin7[] - - -ifdef::web[] -[[components.calendar.eventprovider]] -== Implementing an Event Provider - -If the two simple ways of storing and managing events for a calendar are not -enough, you may need to implement a custom event provider. It is the most -flexible way of providing events. You need to attach the event provider to the -[classname]#Calendar# using the [methodname]#setEventProvider()# method. - -Event queries are done by asking the event provider for all the events between -two given dates. The range of these dates is guaranteed to be at least as long -as the start and end dates set for the component. The component can, however, -ask for a longer range to ensure correct rendering. In particular, all start -dates are expanded to the start of the day, and all end dates are expanded to -the end of the day. - -[[components.calendar.eventprovider.customevents]] -=== Custom Events - -An event provider could use the built-in [classname]#BasicEvent#, but it is -usually more proper to define a custom event type that is bound directly to the -data source. Custom events may be useful for some other purposes as well, such -as when you need to add extra information to an event or customize how it is -acquired. - -Custom events must implement the [interfacename]#CalendarEvent# interface or -extend an existing event class. The built-in [classname]#BasicEvent# class -should serve as a good example of implementing simple events. It keeps the data -in member variables. - - -[source, java] ----- -public class BasicEvent - implements CalendarEventEditor, EventChangeNotifier { - ... - - public String getCaption() { - return caption; - } - - public String getDescription() { - return description; - } - - public Date getEnd() { - return end; - } - - public Date getStart() { - return start; - } - - public String getStyleName() { - return styleName; - } - - public boolean isAllDay() { - return isAllDay; - } - - public void setCaption(String caption) { - this.caption = caption; - fireEventChange(); - } - - public void setDescription(String description) { - this.description = description; - fireEventChange(); - } - - public void setEnd(Date end) { - this.end = end; - fireEventChange(); - } - - public void setStart(Date start) { - this.start = start; - fireEventChange(); - } - - public void setStyleName(String styleName) { - this.styleName = styleName; - fireEventChange(); - } - - public void setAllDay(boolean isAllDay) { - this.isAllDay = isAllDay; - fireEventChange(); - } - - public void addEventChangeListener( - EventChangeListener listener) { - ... - } - - public void removeListener(EventChangeListener listener) { - ... - } - - protected void fireEventChange() {...} -} ----- - -You may have noticed that there was some additional code in the -[classname]#BasicEvent# that was not in the [interfacename]#CalendarEvent# -interface. Namely [classname]#BasicEvent# also implements two additional -interfaces: - -[interfacename]#CalendarEditor#:: This interface defines setters for all the fields, and is required for some of -the default handlers to work. - -[interfacename]#EventChangeNotifier#:: This interface adds the possibility to listen for changes in the event, and -enables the [classname]#Calendar# to render the changes immediately. - - - -The start time and end time are mandatory, but caption, description, and style -name are not. The style name is used as a part of the CSS class name for the -HTML DOM element of the event. - -In addition to the basic event interfaces, you can enhance the functionality of -your event and event provider classes by using the [classname]#EventChange# and -[classname]#EventSetChange# events. They let the [classname]#Calendar# component -to know about changes in events and update itself accordingly. The -[classname]#BasicEvent# and [classname]#BasicEventProvider# examples given -earlier include a simple implementation of these interfaces. - - -[[components.calendar.eventprovider.eventprovider]] -=== Implementing the Event Provider - -An event provider needs to implement the [interfacename]#CalendarEventProvider# -interface. It has only one method to be implemented. Whenever the calendar is -painted, [methodname]#getEvents(Date, Date)# method is called and it must return -a list of events between the given start and end time. - -The following example implementation returns only one example event. The event -starts from the current time and is five hours long. - - -[source, java] ----- -public class MyEventProvider implements CalendarEventProvider{ - public List<Event> getEvents(Date startDate, Date endDate){ - List<Event> events = new ArrayList<Event>(); - GregorianCalendar cal = new GregorianCalendar(); - cal.setTime(new Date()); - - Date start = cal.getTime(); - cal.add(GregorianCalendar.HOUR, 5); - Date end = cal.getTime(); - BasicEvent event = new BasicEvent(); - event.setCaption("My Event"); - event.setDescription("My Event Description"); - event.setStart(start); - event.setEnd(end); - events.add(event); - - return events; - } -} ----- - -It is important to notice that the [classname]#Calendar# may query for dates -beyond the range defined by start date and end date. Particularly, it may expand -the date range to make sure the user interface is rendered correctly. - - -endif::web[] - -ifdef::web[] -[[components.calendar.appearance]] -== Styling a Calendar - -Configuring the appearance of the Vaadin Calendar component is one of the basic -tasks. At the least, you need to consider its sizing in your user interface. You -also quite probably want to use some color or colors for events. - -[[components.calendar.appearance.sizing]] -=== Sizing - -The Calendar supports component sizing as usual for defined (fixed or relative) -sizes. When using an undefined size for the calendar, all the sizes come from -CSS. In addition, when the height is undefined, a scrollbar is displayed in the -weekly view to better fit the cells to the user interface. - -Below is a list of style rules that define the size of a Calendar with undefined -size (these are the defaults): - - -[source, css] ----- -.v-calendar-month-sizedheight .v-calendar-month-day { - height: 100px; -} - -.v-calendar-month-sizedwidth .v-calendar-month-day { - width: 100px; -} - -.v-calendar-header-month-Hsized .v-calendar-header-day { - width: 101px; -} - -/* for IE */ -.v-ie6 .v-calendar-header-month-Hsized .v-calendar-header-day { - width: 104px; -} - -/* for others */ -.v-calendar-header-month-Hsized td:first-child { - padding-left: 21px; -} - -.v-calendar-header-day-Hsized { - width: 200px; -} - -.v-calendar-week-numbers-Vsized .v-calendar-week-number { - height: 100px; - line-height: 100px; -} - -.v-calendar-week-wrapper-Vsized { - height: 400px; - overflow-x: hidden !important; -} - -.v-calendar-times-Vsized .v-calendar-time { - height: 38px; -} - -.v-calendar-times-Hsized .v-calendar-time { - width: 42px; -} - -.v-calendar-day-times-Vsized .v-slot,.v-calendar-day-times-Vsized .v-slot-even { - height: 18px; -} - -.v-calendar-day-times-Hsized, .v-calendar-day-times-Hsized .v-slot,.v-calendar-day-times-Hsized .v-slot-even { - width: 200px; -} ----- - - -[[components.calendar.appearance.event-style]] -=== Event Style - -Events can be styled with CSS by setting them a __style name suffix__. The -suffix is retrieved with the [methodname]#getStyleName()# method in -[interfacename]#CalendarEvent#. If you use [classname]#BasicEvent# events, you -can set the suffix with [methodname]#setStyleName()#. - - -[source, java] ----- -BasicEvent event = new BasicEvent("Wednesday Wonder", ... ); -event.setStyleName("mycolor"); -calendar.addEvent(event); ----- - -Suffix [literal]#++mycolor++# would create -[literal]#++v-calendar-event-mycolor++# class for regular events and -[literal]#++v-calendar-event-mycolor-add-day++# for all-day events. You could -style the events with the following rules: - - -[source, css] ----- -.v-calendar .v-calendar-event-mycolor {} -.v-calendar .v-calendar-event-mycolor-all-day {} -.v-calendar .v-calendar-event-mycolor .v-calendar-event-caption {} -.v-calendar .v-calendar-event-mycolor .v-calendar-event-content {} ----- - - -endif::web[] - -ifdef::web[] -[[components.calendar.visible-hours-days]] -== Visible Hours and Days - -As we saw in <<components.calendar.daterange>>, you can set the range of dates -that are shown by the Calendar. But what if you wanted to show the entire month -but hide the weekends? Or show only hours from 8 to 16 in the weekly view? The -[methodname]#setVisibleDays()# and [methodname]#setVisibleHours()# methods allow -you to do that. - - -[source, java] ----- -calendar.setVisibleDays(1,5); // Monday to Friday -calendar.setVisibleHours(0,15); // Midnight until 4 pm ----- - -After the above settings, only weekdays from Monday to Friday would be shown. -And when the calendar is in the weekly view, only the time range from 00:00 to -16:00 would be shown. - -Note that the excluded times are never shown so you should take care when -setting the date range. If the date range contains only dates / times that are -excluded, nothing will be displayed. Also note that even if a date is not -rendered because these settings, the event provider may still be queried for -events for that date. - -endif::web[] - -ifdef::web[] -[[components.calendar.drag-and-drop]] -== Drag and Drop - -Vaadin Calendar can act as a drop target for drag and drop, described in -<<dummy/../../../framework/advanced/advanced-dragndrop#advanced.dragndrop,"Drag -and Drop">>. With the functionality, the user could drag events, for example, -from a table to a calendar. - -To support dropping, a [classname]#Calendar# must have a drop handler. When the -drop handler is set, the days in the monthly view and the time slots in the -weekly view can receive drops. Other locations, such as day names in the weekly -view, can not currently receive drops. - -Calendar uses its own implementation of [interfacename]#TargetDetails#: -[classname]#CalendarTargetdetails#. It holds information about the the drop -location, which in the context of [classname]#Calendar# means the date and time. -The drop target location can be retrieved via the [methodname]#getDropTime()# -method. If the drop is done in the monthly view, the returned date does not have -exact time information. If the drop happened in the weekly view, the returned -date also contains the start time of the slot. - -Below is a short example of creating a drop handler and using the drop -information to create a new event: - - -[source, java] ----- -private Calendar createDDCalendar() { - Calendar calendar = new Calendar(); - calendar.setDropHandler(new DropHandler() { - public void drop(DragAndDropEvent event) { - CalendarTargetDetails details = - (CalendarTargetDetails) event.getTargetDetails(); - - TableTransferable transferable = - (TableTransferable) event.getTransferable(); - - createEvent(details, transferable); - removeTableRow(transferable); - } - - public AcceptCriterion getAcceptCriterion() { - return AcceptAll.get(); - } - - }); - - return calendar; -} - - -protected void createEvent(CalendarTargetDetails details, - TableTransferable transferable) { - Date dropTime = details.getDropTime(); - java.util.Calendar timeCalendar = details.getTargetCalendar() - .getInternalCalendar(); - timeCalendar.setTime(dropTime); - timeCalendar.add(java.util.Calendar.MINUTE, 120); - Date endTime = timeCalendar.getTime(); - - Item draggedItem = transferable.getSourceComponent(). - getItem(transferable.getItemId()); - - String eventType = (String)draggedItem. - getItemProperty("type").getValue(); - - String eventDescription = "Attending: " - + getParticipantString( - (String[]) draggedItem. - getItemProperty("participants").getValue()); - - BasicEvent newEvent = new BasicEvent(); - newEvent.setAllDay(!details.hasDropTime()); - newEvent.setCaption(eventType); - newEvent.setDescription(eventDescription); - newEvent.setStart(dropTime); - newEvent.setEnd(endTime); - - BasicEventProvider ep = (BasicEventProvider) details - .getTargetCalendar().getEventProvider(); - ep.addEvent(newEvent); -} ----- - -endif::web[] - -ifdef::web[] -[[components.calendar.contextmenu]] -== Using the Context Menu - -Vaadin Calendar allows the use of context menu (mouse right-click) to manage -events. As in other context menus in Vaadin, the menu items are handled in -Vaadin as __actions__ by an __action handler__. To enable a context menu, you -have to implement a Vaadin [interfacename]#Action.Handler# and add it to the -calendar with [methodname]#addActionHandler()#. - -An action handler must implement two methods: [methodname]#getActions()# and -[methodname]#handleAction()#. The [methodname]#getActions()# is called for each -day displayed in the calendar view. It should return a list of allowed actions -for that day, that is, the items of the context menu. The [parameter]#target# -parameter is the context of the click - a [classname]#CalendarDateRange# that -spans over the day. The [parameter]#sender# is the [classname]#Calendar# object. - -The [methodname]#handleActions()# receives the target context in the -[parameter]#target#. If the context menu was opened on an event, the target is -the [interfacename]#Event# object, otherwise it is a -[classname]#CalendarDateRange#. - -endif::web[] - -ifdef::web[] -[[components.calendar.localization]] -== Localization and Formatting - -[[components.calendar.localization.locale]] -=== Setting the Locale and Time Zone - -Month and weekday names are shown in the language of the locale setting of the -[classname]#Calendar#. The translations are acquired from the standard Java -locale data. By default, [classname]#Calendar# uses the system default locale -for its internal calendar, but you can change it with -[methodname]#setLocale(Locale locale)#. Setting the locale will update also -other location specific date and time settings, such as the first day of the -week, time zone, and time format. However, time zone and time format can be -overridden by settings in the [classname]#Calendar#. - -For example, the following would set the language to US English: - - -[source, java] ----- -cal.setLocale(Locale.US); ----- - -The locale defines the default time zone. You can change it with the -[methodname]#setTimeZone()# method, which takes a -[classname]#java.util.TimeZone# object as its parameter. Setting timezone to -null will reset timezone to the locale default. - -For example, the following would set the Finnish time zone, which is EET - - -[source, java] ----- -cal.setTimeZone(TimeZone.getTimeZone("Europe/Helsinki")); ----- - - -[[components.calendar.localization.datecaption]] -=== Time and Date Caption Format - -The time may be shown either in 24 or 12 hour format. The default format is -defined by the locale, but you can change it with the -[methodname]#setTimeFormat()# method. Giving a [literal]#++null++# setting will -reset the time format to the locale default. - - -[source, java] ----- -cal.setTimeFormat(TimeFormat.Format12H); ----- - -You can change the format of the date captions in the week view with the -[methodname]#setWeeklyCaptionFormat(String dateFormatPattern)# method. The date -format pattern should follow the format of the standard Java -[classname]#java.text.SimpleDateFormat# class. - -For example: - - -[source, java] ----- -cal.setWeeklyCaptionFormat("dd-MM-yyyy"); ----- - - -endif::web[] - -ifdef::web[] -[[components.calendar.customizing]] -== Customizing the Calendar - -In this section, we give a tutorial for how to make various basic customizations -of the Vaadin Calendar. The event provider and styling was described earlier, so -now we concentrate on other features of the Calendar API. - -[[components.calendar.customizing.overview]] -=== Overview of Handlers - -Most of the handlers related to calendar events have sensible default handlers. -These are found in the [package]#com.vaadin.ui.handler# package. The default -handlers and their functionalities are described below. - -* [classname]#BasicBackwardHandler#. Handles clicking the back-button of the weekly view so that the viewed month is changed to the previous one. -* [classname]#BasicForwardHandler#. Handles clicking the forward-button of the weekly view so that the viewed month is changed to the next one. -* [classname]#BasicWeekClickHandler#. Handles clicking the week numbers int the monthly view so that the viewable date range is changed to the clicked week. -* [classname]#BasicDateClickHandler#. Handles clicking the dates on both the monthly view and the weekly view. Changes the viewable date range so that only the clicked day is visible. -* [classname]#BasicEventMoveHandler#. Handles moving the events in both monthly view and the weekly view. Events can be moved and their start and end dates are changed correctly, but only if the event implements [classname]#CalendarEventEditor# (implemented by [classname]#BasicEvent#). -* [classname]#BasicEventResizeHandler#. Handles resizing the events in the weekly view. Events can be resized and their start and end dates are changed correctly, but only if the event implements [classname]#CalendarEventEditor# (implemented by the [classname]#BasicEvent#). - -All of these handlers are automatically set when creating a new -[classname]#Calendar#. If you wish to disable some of the default functionality, -you can simply set the corresponding handler to [literal]#++null++#. This will -prevent the functionality from ever appearing on the user interface. For -example, if you set the [classname]#EventMoveHandler# to [literal]#++null++#, -the user will be unable to move events in the browser. - - -[[components.calendar.customizing.creating]] -=== Creating a Calendar - -Let us first create a new [classname]#Calendar# instance. Here we use our own -event provider, the [classname]#MyEventProvider# described in -<<components.calendar.eventprovider.eventprovider>>. - - -[source, java] ----- -Calendar cal = new Calendar(new MyEventProvider()); ----- - -This initializes the Calendar. To customize the viewable date range, we must set -a start and end date to it. - -There is only one visible event in the timeline, starting from the current time. -That is what our event provider passes to the client.//TODO See the figure -3. - -It would be nice to also be able to control the navigation forward and backward. -The default navigation is provided by the default handlers, but perhaps we want -to restrict the users so they can only navigate dates in the current year. Maybe -we also want to pose some other restrictions to the clicking week numbers and -dates. - -These restrictions and other custom logic can be defined with custom handlers. -You can find the handlers in the [package]#com.vaadin.addon.calendar.ui.handler# -package and they can be easily extended. Note that if you don not want to extend -the default handlers, you are free to implement your own. The interfaces are -described in [interfacename]#CalendarComponentEvents#. - - -endif::web[] - -[[components.calendar.navigation]] -== Backward and Forward Navigation - -Vaadin Calendar has only limited built-in navigation support. The weekly view -has navigation buttons in the top left and top right -corners. -// TODO See the figure 4. - -You can handle backward and forward navigation with a -[interfacename]#BackwardListener# and [interfacename]#ForwardListener#. - -[source, java] ----- -cal.setHandler(new BasicBackwardHandler() { - protected void setDates(BackwardEvent event, - Date start, Date end) { - - java.util.Calendar calendar = event.getComponent() - .getInternalCalendar(); - if (isThisYear(calendar, end) - && isThisYear(calendar, start)) { - super.setDates(event, start, end); - } - }}); ----- - -The forward navigation handler can be implemented in the same way. The example -handler restricts the dates to the current year. - - -ifdef::web[] -[[components.calendar.dateclick]] -== Date Click Handling - -By default, clicking a date either in month or week view switches to single-day -view, while clicking on the date header in the day view has no effect. The date -click event is handled by a [interfacename]#DateClickHandler#. - -The following example handles click events on the date header in the day view to -zoom out to the week view. For other clicks it applies the default behavior; in -the week view clicking on a day switches to the day view. - - -[source, java] ----- -calendar.setHandler(new BasicDateClickHandler() { - public void dateClick(DateClickEvent event) { - Calendar cal = event.getComponent(); - - // Check if the current range is already one day long - long currentCalDateRange = cal.getEndDate().getTime() - - cal.getStartDate().getTime(); - - // From one-day view, zoom out to week view - if (currentCalDateRange <= DateConstants.DAYINMILLIS) { - // Change the date range to the current week - GregorianCalendar weekstart = new GregorianCalendar(); - GregorianCalendar weekend = new GregorianCalendar(); - weekstart.setTime(event.getDate()); - weekend.setTime(event.getDate()); - weekstart.setFirstDayOfWeek(java.util.Calendar.SUNDAY); - weekstart.set(java.util.Calendar.HOUR_OF_DAY, 0); - weekstart.set(java.util.Calendar.DAY_OF_WEEK, - java.util.Calendar.SUNDAY); - weekend.set(java.util.Calendar.HOUR_OF_DAY, 23); - weekend.set(java.util.Calendar.DAY_OF_WEEK, - java.util.Calendar.SATURDAY); - cal.setStartDate(weekstart.getTime()); - cal.setEndDate(weekend.getTime()); - - Notification.show("Custom zoom to week"); - } else { - // Default behavior, change date range to one day - super.dateClick(event); - } - } - }); ----- - -endif::web[] - -ifdef::web[] -[[components.calendar.weekclick]] -== Handling Week Clicks - -The monthly view displays week numbers for each week row on the left side of the -date grid. The week number are clickable and you can handle the click events by -setting a [interfacename]#WeekClickHandler# for the [classname]#Calendar# -object. The default handler changes the date range to be the clicked week. - -In the following example, we add a week click handler that changes the date -range of the calendar to one week only if the start and end dates of the week -are in the current month. - - -[source, java] ----- -cal.setHandler(new BasicWeekClickHandler() { - protected void setDates(WeekClick event, - Date start, Date end) { - java.util.Calendar calendar = event.getComponent() - .getInternalCalendar(); - if (isThisMonth(calendar, start) - && isThisMonth(calendar, end)) { - super.setDates(event, start, end); - } - } -}); ----- - -endif::web[] - -ifdef::web[] -[[components.calendar.eventclick]] -== Handling Event Clicks - -The calendar events in all views are are clickable. There is no default handler. -Just like the date and week click handlers, event click handling is enabled by -setting an [interfacename]#EventClickHandler# for the [classname]#Calendar# -object. - -You can get hold of the clicked event by the [methodname]#getCalendarEvent()# -method in the [classname]#EventClick# object passed to the handler, as shown in -the following example. - - -[source, java] ----- -cal.setHandler(new EventClickHandler() { - public void eventClick(EventClick event) { - BasicEvent e = (BasicEvent) event.getCalendarEvent(); - - // Do something with it - new Notification("Event clicked: " + e.getCaption(), - e.getDescription()).show(Page.getCurrent()); - } -}); ----- - -endif::web[] - -ifdef::web[] -[[components.calendar.eventdrag]] -== Event Dragging - -The user can drag an event to change its position in time. The default handler -sets the start and end time of the event accordingly. You can do many things -with a custom move handler, such as restrict moving events. - -In the following example, we add a [interfacename]#EventMoveHandler# to a -[classname]#Calendar#. The event handler updates the new position to the -datasource, but only if the new dates are in the current month. This requires -making some changes to the event provider class. - - -[source, java] ----- -cal.setHandler(new BasicEventMoveHandler() { - private java.util.Calendar javaCalendar; - - public void eventMove(MoveEvent event) { - javaCalendar = event.getComponent().getInternalCalendar(); - super.eventMove(event); - } - - protected void setDates(CalendarEventEditor event, - Date start, Date end) { - if (isThisMonth(javaCalendar, start) - && isThisMonth(javaCalendar, end)) { - super.setDates(event, start, end); - } - } -}); ----- - -For the above example to work, the example event provider presented earlier -needs to be changed slightly so that it doesn't always create a new event when -[methodname]#getEvents()# is called. - - -[source, java] ----- -public static class MyEventProvider - implements CalendarEventProvider { - private List<CalendarEvent> events = - new ArrayList<CalendarEvent>(); - - public MyEventProvider() { - events = new ArrayList<CalendarEvent>(); - GregorianCalendar cal = new GregorianCalendar(); - cal.setTime(new Date()); - - Date start = cal.getTime(); - cal.add(GregorianCalendar.HOUR, 5); - Date end = cal.getTime(); - BasicEvent event = new BasicEvent(); - event.setCaption("My Event"); - event.setDescription("My Event Description"); - event.setStart(start); - event.setEnd(end); - events.add(event); - } - - public void addEvent(CalendarEvent BasicEvent) { - events.add(BasicEvent); - } - - public List<CalendarEvent> getEvents(Date startDate, - Date endDate) { - return events; - } -} ----- - -After these changes, the user can move events around as earlier, but dropping an -event, the start and end dates are checked by the server. Note that as the -server-side must move the event in order for it to render to the place it was -dropped. The server can also reject moves by not doing anything when the event -is received. - -endif::web[] - -ifdef::web[] -[[components.calendar.dragselection]] -== Handling Drag Selection - -Drag selection works both in the monthly and weekly views. To listen for drag -selection, you can add a [interfacename]#RangeSelectListener# to the -[classname]#Calendar#. There is no default handler for range select. - -In the code example below, we create an new event when any date range is -selected. Drag selection opens a window where the user is asked for a caption -for the new event. After confirming, the new event is be passed to the event -provider and calendar is updated. Note that as our example event provider and -event classes do not implement the event change interface, we must refresh the -[classname]#Calendar# manually after changing the events. - - -[source, java] ----- -cal.setHandler(new RangeSelectHandler() { - public void rangeSelect(RangeSelectEvent event) { - BasicEvent calendarEvent = new BasicEvent(); - calendarEvent.setStart(event.getStart()); - calendarEvent.setEnd(event.getEnd()); - - // Create popup window and add a form in it. - VerticalLayout layout = new VerticalLayout(); - layout.setMargin(true); - layout.setSpacing(true); - - final Window w = new Window(null, layout); - ... - - // Wrap the calendar event to a BeanItem - // and pass it to the form - final BeanItem<CalendarEvent> item = - new BeanItem<CalendarEvent>(myEvent); - - final Form form = new Form(); - form.setItemDataSource(item); - ... - - layout.addComponent(form); - - HorizontalLayout buttons = new HorizontalLayout(); - buttons.setSpacing(true); - buttons.addComponent(new Button("OK", new ClickListener() { - - public void buttonClick(ClickEvent event) { - form.commit(); - - // Update event provider's data source - provider.addEvent(item.getBean()); - - UI.getCurrent().removeWindow(w); - } - })); - - ... - } -}); ----- - -endif::web[] - -ifdef::web[] -[[components.calendar.eventresizing]] -== Resizing Events - -The user can resize an event by dragging from both ends to change its start or -end time. This offers a convenient way to change event times without the need to -type anything. The default resize handler sets the start and end time of the -event according to the resize. - -In the example below, we set a custom handler for resize events. The handler -prevents any event to be resized over 12 hours in length. Note that this does -not prevent the user from resizing an event over 12 hours in the client. The -resize will just be corrected by the server. - - -[source, java] ----- -cal.setHandler(new BasicEventResizeHandler() { - private static final long twelveHoursInMs = 12*60*60*1000; - - protected void setDates(CalendarEventEditor event, - Date start, Date end) { - long eventLength = end.getTime() - start.getTime(); - if (eventLength <= twelveHoursInMs) { - super.setDates(event, start, end); - } - } -}); ----- - -endif::web[] diff --git a/documentation/components/components-combobox.asciidoc b/documentation/components/components-combobox.asciidoc index f3fd6d9962..b5eb92de7e 100644 --- a/documentation/components/components-combobox.asciidoc +++ b/documentation/components/components-combobox.asciidoc @@ -7,6 +7,8 @@ layout: page [[components.combobox]] = [classname]#ComboBox# +*_This section has not yet been updated for Vaadin Framework 8_* + ifdef::web[] [.sampler] image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/data-input/multiple-value/combo-box"] diff --git a/documentation/components/components-datefield.asciidoc b/documentation/components/components-datefield.asciidoc index 751381f44e..bf535c702c 100644 --- a/documentation/components/components-datefield.asciidoc +++ b/documentation/components/components-datefield.asciidoc @@ -9,17 +9,15 @@ layout: page ifdef::web[] [.sampler] -image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/data-input/dates/popup-date-field"] +image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/data-input/dates/date-field"] endif::web[] The [classname]#DateField# component provides the means to display and input -dates. The field comes in two variations: [classname]#PopupDateField#, +dates. The field comes in two variations: [classname]#DateField#, with a numeric input box and a popup calendar view, and -[classname]#InlineDateField#, with the calendar view always visible. The -[classname]#DateField# base class defaults to the popup variation. +[classname]#InlineDateField#, with the calendar view always visible. -The example below illustrates the use of the [classname]#DateField# base class, -which is equivalent to the [classname]#PopupDateField#. We set the initial date +The example below illustrates the use of the [classname]#DateField#. We set the initial date of the date field to current date by using the factory method [methodname]#now# of the [classname]#java.time.LocalDate# class. @@ -36,15 +34,13 @@ date.setValue(LocalDate.now()); The result is shown in <<figure.components.datefield.basic>>. [[figure.components.datefield.basic]] -.[classname]#DateField# ([classname]#PopupDateField#) for Selecting a Date +.[classname]#DateField# for Selecting a Date image::img/datefield-example1.png[width=35%, scaledwidth=60%] [[components.datefield.popupdatefield]] -== [classname]#PopupDateField# +== [classname]#DateField# -The [classname]#PopupDateField# provides date input using a text box. As the -[classname]#DateField# defaults to this component, the use is exactly the same -as described earlier. Clicking the handle right of the date opens a popup view +The [classname]#DateField# provides date input using a text box. Clicking the handle right of the date opens a popup view for selecting the year, month, and day. The Down key also opens the popup. Once opened, the user can navigate the calendar using the cursor keys. @@ -71,7 +67,7 @@ date.setDateFormat("yyyy-MM-dd"); The result is shown in <<figure.components.datefield.popupdatefield.format>>. [[figure.components.datefield.popupdatefield.format]] -.Custom Date Format for [classname]#PopupDateField# +.Custom Date Format for [classname]#DateField# image::img/datefield-formatting.png[width=35%, scaledwidth=60%] The same format specification is also used for parsing user-input date, @@ -121,10 +117,9 @@ in the following example. ---- // Create a date field with a custom parsing and a // custom error message for invalid format -PopupDateField date = new PopupDateField("My Date") { +DateField date = new DateField("My Date") { @Override - protected Date handleUnparsableDateString(String dateString) - throws Property.ConversionException { + protected Result<Date> handleUnparsableDateString(String dateString) { // Try custom parsing String fields[] = dateString.split("/"); if (fields.length >= 3) { @@ -132,18 +127,15 @@ PopupDateField date = new PopupDateField("My Date") { int year = Integer.parseInt(fields[0]); int month = Integer.parseInt(fields[1])-1; int day = Integer.parseInt(fields[2]); - GregorianCalendar c = - new GregorianCalendar(year, month, day); - return c.getTime(); + + return Result.ok(LocalDate.of(year, month, day)); } catch (NumberFormatException e) { - throw new Property. - ConversionException("Not a number"); + return Result.error("Not a number"); } } // Bad date - throw new Property. - ConversionException("Your date needs two slashes"); + return Result.error("Your date needs two slashes"); } }; @@ -174,17 +166,16 @@ done in the example below: [source, java] ---- // Create a date field with a custom error message for invalid format -PopupDateField date = new PopupDateField("My Date") { +DateField date = new DateField("My Date") { @Override - protected Date handleUnparsableDateString(String dateString) - throws Property.ConversionException { + protected Result<LocalDate> handleUnparsableDateString(String dateString) { // Have a notification for the error Notification.show( "Your date needs two slashes", Notification.TYPE_WARNING_MESSAGE); // A failure must always also throw an exception - throw new Property.ConversionException("Bad date"); + return Result.error("Bad date"); } }; ---- @@ -196,19 +187,18 @@ undesired. endif::web[] [[components.datefield.popupdatefield.prompt]] -=== Input Prompt +=== Placeholder -Like other fields that have a text box, [classname]#PopupDateField# allows an -input prompt that is visible until the user has input a value. You can set the -prompt with [methodname]#setInputPrompt#. +Like other fields that have a text box, [classname]#DateField# allows an +placeholder that is visible until the user has input a value. You can set that with [methodname]#setPlaceholder#. [source, java] ---- -PopupDateField date = new PopupDateField(); +DateField date = new DateField(); // Set the prompt -date.setInputPrompt("Select a date"); +date.setPlaceholder("Select a date"); // Set width explicitly to accommodate the prompt date.setWidth("10em"); @@ -231,9 +221,8 @@ The input prompt is not available in the [classname]#DateField# superclass. .v-datefield-button {} ---- -The top-level element of [classname]#DateField# and all its variants have -[literal]#++v-datefield++# style. The base class and the -[classname]#PopupDateField# also have the +The top-level element of [classname]#DateField# and [classname]#InlineDateField# have +[literal]#++v-datefield++# style. The [classname]#DateField# also has the [literal]#++v-datefield-popupcalendar++# style. In addition, the top-level element has a style that indicates the resolution, @@ -311,10 +300,6 @@ The user can also navigate the calendar using the cursor keys. .v-last {} .v-datefield-calendarpanel-weeknumber {} .v-datefield-calendarpanel-day {} - .v-datefield-calendarpanel-time {} - .v-datefield-time {} - .v-select {} - .v-label {} ---- The top-level element has the [literal]#++v-datefield++# style. In addition, the @@ -334,7 +319,7 @@ The other style names should be self-explanatory. For weekdays, the endings for the weekday bar. [[components.datefield.resolution]] -== Date and Time Resolution +== Date Resolution In addition to display a calendar with dates, [classname]#DateField# can also display just the month or year. The visibility of the input components is diff --git a/documentation/components/components-features.asciidoc b/documentation/components/components-features.asciidoc index 186429afed..28b7ea2093 100644 --- a/documentation/components/components-features.asciidoc +++ b/documentation/components/components-features.asciidoc @@ -136,7 +136,6 @@ button.setDescription( " <li>etc.</li>"+ "</ul>"); ---- -See the http://demo.vaadin.com/book-examples-vaadin7/book#component.features.description.richtext[on-line example, window="_blank"]. The result is shown in <<figure.components.tooltip.richtext>>. @@ -144,9 +143,8 @@ The result is shown in <<figure.components.tooltip.richtext>>. .A Rich Text Tooltip image::img/tooltip-richtext-withpointer-hi.png[width=40%, scaledwidth=75%] -Notice that the setter and getter are defined for all fields in the -[classname]#Field# interface, not for all components in the -[classname]#Component# interface. +Notice that the setter and getter are defined for all field components implementing the +[classname]#HasValue# interface, not for all components. [[components.features.enabled]] @@ -180,13 +178,13 @@ buttons. .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 state. No client -interaction with such a component is sent to the server and, as an important +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 read-only state. This feature exists in all built-in -components in Vaadin and is automatically handled for all [classname]#Field# -components for the field property value. For custom widgets, you need to make -sure that the read-only state is checked on the server-side for all +the client in the disabled state. This feature exists in all built-in +components in Vaadin and is automatically handled for all [classname]#HasValue# +components that have a value. For custom widgets, you need to make +sure that the disabled state is checked on the server-side for all safety-critical variables. === CSS Style Rules @@ -426,7 +424,7 @@ endif::web[] ((("read-only property"))) ((("Component interface", "read-only"))) The property defines whether the value of a component can be changed. The -property is mainly applicable to [classname]#Field# components, as they have a +property is only applicable to [classname]#HasValue# components implementing the `HasValue` interface, as they have a value that can be edited by the user. [source, java] @@ -449,20 +447,16 @@ The resulting read-only text field is shown in .A read-only component image::img/features-readonly-simple.png[width=50%, scaledwidth=80%] -Setting a layout or some other component container as read-only does not usually -make the contained components read-only recursively. This is different from, for -example, the disabled state, which is usually applied recursively. - 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 read-only -[classname]#Table# 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. +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]#Field# component. The latter is an important +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. @@ -470,7 +464,7 @@ 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]#Table#. Custom components should check the read-only +position of a [classname]#ListSelect#. Custom components should check the read-only state for variables bound to business data. //// @@ -575,11 +569,6 @@ The resulting invisible component is shown in .An invisible component image::img/features-visible-simple.png[] -Beware that invisible beings can leave footprints. The containing layout cell -that holds the invisible component will not go away, but will show in the layout -as extra empty space. Also expand ratios work just like if the component was -visible - it is the layout cell that expands, not the component. - 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. @@ -622,7 +611,7 @@ mycomponent.setWidth(100, Unit.PERCENTAGE); mycomponent.setWidth(400, Unit.PIXELS); ---- -Alternatively, you can speficy the size as a string. The format of such a string +Alternatively, you can specify the size as a string. The format of such a string must follow the HTML/CSS standards for specifying measures. @@ -678,7 +667,7 @@ 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]#Field# and [classname]#Select# components and also by +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 diff --git a/documentation/components/components-fields.asciidoc b/documentation/components/components-fields.asciidoc index b839b7f729..45325b9146 100644 --- a/documentation/components/components-fields.asciidoc +++ b/documentation/components/components-fields.asciidoc @@ -7,6 +7,8 @@ layout: page [[components.fields]] = Field Components +*_This section has not yet been updated for Vaadin Framework 8_* + ((("[classname]#Field#", id="term.components.fields", range="startofrange"))) _Fields_ are components that have a value that the user can change through the @@ -66,13 +68,10 @@ displayed in a tooltip when the mouse pointer hovers over the error indicator. [[components.fields.valuechanges]] == Handling Field Value Changes -[classname]#Field# provides two methods for listening to changes to the field value: -[methodname]#onChange# and [methodname]#addValueChangeListener#. The difference -is that the former takes a [interfacename]#Consumer# object that only receives the new value; -the latter, on the other hand, takes an [interfacename]#EventListener# that gets -a [classname]#ValueChange# event instance containing extra information about the event. +[classname]#Field# provides [methodname]#addValueChangeListener# method for listening to changes to the field value. This method takes a [interfacename]#EventListener# that gets +a [classname]#ValueChange# event instance containing information about the event. -Both methods return a [classname]#Registration# object that can be used to later +This method returns a [classname]#Registration# object that can be used to later remove the added listener if necessary. [source, java] @@ -80,9 +79,6 @@ remove the added listener if necessary. TextField textField = new TextField(); Label echo = new Label(); -// Just echo in the label anything the user enters -textField.onChange(echo::setValue); - // Add a more complex listener textField.addValueChangeListener(event -> { String origin = event.isUserOriginated() diff --git a/documentation/components/components-grid.asciidoc b/documentation/components/components-grid.asciidoc index a06989501a..2366961e03 100644 --- a/documentation/components/components-grid.asciidoc +++ b/documentation/components/components-grid.asciidoc @@ -7,6 +7,8 @@ layout: page [[components.grid]] = [classname]#Grid# +*_This section has not yet been updated for Vaadin Framework 8_* + ifdef::web[] [.sampler] image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/grids-and-trees/grid"] diff --git a/documentation/components/components-interfaces.asciidoc b/documentation/components/components-interfaces.asciidoc index 5d266617fd..263366b944 100644 --- a/documentation/components/components-interfaces.asciidoc +++ b/documentation/components/components-interfaces.asciidoc @@ -7,6 +7,8 @@ layout: page [[components.interfaces]] = Interfaces and Abstractions +*_This section has not yet been updated for Vaadin Framework 8_* + ((("interfaces"))) Vaadin user interface components are built on a skeleton of interfaces and abstract classes that define and implement the features common to all components diff --git a/documentation/components/components-label.asciidoc b/documentation/components/components-label.asciidoc index f225c6ba73..ee2113fa84 100644 --- a/documentation/components/components-label.asciidoc +++ b/documentation/components/components-label.asciidoc @@ -17,19 +17,19 @@ for short simple labels or for displaying long text, such as paragraphs. The text can be formatted in HTML or as preformatted text, depending on the __content mode__ of the label. -You can give the label text most conviniently in the constructor, as is done in -the following. Label has 100% default width, so the containing layout must also -have defined width. +You can give the label text most conveniently in the constructor, as is done in +the following. Label has undefined default width, so it will only take the space it needs. + [source, java] ---- // A container that is 100% wide by default VerticalLayout layout = new VerticalLayout(); +// label will only take the space it needs Label label = new Label("Labeling can be dangerous"); layout.addComponent(label); ---- -See the http://demo.vaadin.com/book-examples-vaadin7/book#component.label.basic[on-line example, window="_blank"]. You can get and set the text of a [classname]#Label# with the [methodname]#getValue()# and [methodname]#setValue()# methods. @@ -41,10 +41,8 @@ TextField editor = new TextField(null, // No caption label.getValue()); // Change the label's text -editor.onChange(label::setValue); -// or onChange(value -> label.setValue(value)); +editor.addValueChangeListener(event -> label.setValue(event.getValue())); ---- -See the http://demo.vaadin.com/book-examples-vaadin7/book#component.label.basic[on-line example, window="_blank"]. Even though [classname]#Label# is text and is often used as a caption, it is a normal component and therefore also has a caption that you can set with @@ -54,11 +52,9 @@ managed by the containing layout. [[components.label.wrap]] == Text Width and Wrapping -[classname]#Label# has 100% default width, so the containing layout must also -have a defined width. If the width of the label's text exceeds the width of the -label, the text will wrap around and continue on the next line. Some layout -components have undefined width by default, such as -[classname]#HorizontalLayout#, so you need to pay special care with them. +[classname]#Label# has undefined default width, so it will only take the space it needs. +If the width of the label's text exceeds the available width for the label in the layout, +the text overflows, and normally, gets truncated. [source, java] @@ -70,30 +66,30 @@ panel.setWidth("300px"); panel.setContent( new Label("This is a Label inside a Panel. There is " + "enough text in the label to make the text " + - "wrap when it exceeds the width of the panel.")); + "get truncated when it exceeds the width of the panel.")); ---- -See the http://demo.vaadin.com/book-examples-vaadin7/book#component.label.wrap[on-line example, window="_blank"]. As the size of the [classname]#Panel# in the above example is fixed and the -width of [classname]#Label# is the default 100%, the text in the -[classname]#Label# will wrap to fit the panel, as shown in +width of [classname]#Label# is the default undefined, the [classname]#Label# + will overflow the layout horizontally and be truncated. <<figure.components.label>>. +//// +// TODO update figure to match new label settings in Vaadin Framwork 8 [[figure.components.label]] .The Label Component image::img/label-example1.png[width=50%, scaledwidth=75%] +//// -Setting [classname]#Label# to undefined width will cause it to not wrap at the -end of the line, as the width of the content defines the width. If placed inside -a layout with defined width, the [classname]#Label# will overflow the layout -horizontally and, normally, be truncated. +Setting [classname]#Label# to defined width will cause it to not overflow the layout, +but to wrap to the next line. [[components.label.content-mode]] == Content Mode The content of a label is formatted depending on a __content mode__. By default, -the text is assumed to be plain text and any contained XML-specific characters +the text is assumed to be plain text and any contained HTML-specific characters will be quoted appropriately to allow rendering the contents of a label in HTML in a web browser. The content mode can be set in the constructor or with [methodname]#setContentMode()#, and can have the values defined in the @@ -102,7 +98,7 @@ in a web browser. The content mode can be set in the constructor or with TEXT:: The default content mode where the label contains only plain text. All characters are allowed, including the special [literal]#++<++#, -[literal]#++>++#, and [literal]#++&++# characters in XML or HTML, which are +[literal]#++>++#, and [literal]#++&++# characters in HTML, which are quoted properly in HTML while rendering the component. This is the default mode. PREFORMATTED:: Content mode where the label contains preformatted text. It will be, by default, @@ -168,7 +164,6 @@ Label htmlLabel = new Label( "are preserved.", ContentMode.HTML); ---- -See the http://demo.vaadin.com/book-examples-vaadin7/book#component.label.content-modes.contentmodes[on-line example, window="_blank"]. The rendering will look as shown in <<figure.components.label.content-mode>>. diff --git a/documentation/components/components-overview.asciidoc b/documentation/components/components-overview.asciidoc index 65d3053b94..c0ce787e27 100644 --- a/documentation/components/components-overview.asciidoc +++ b/documentation/components/components-overview.asciidoc @@ -7,6 +7,8 @@ layout: page [[components.overview]] = Overview +*_This section has not yet been updated for Vaadin Framework 8_* + Vaadin provides a comprehensive set of user interface components and allows you to define custom components. <<figure.uicomponents>> illustrates the inheritance hierarchy of the UI component classes and interfaces. Interfaces are displayed diff --git a/documentation/components/components-popupview.asciidoc b/documentation/components/components-popupview.asciidoc index ad4000fa04..bcb17db713 100644 --- a/documentation/components/components-popupview.asciidoc +++ b/documentation/components/components-popupview.asciidoc @@ -46,7 +46,7 @@ PopupView popup = new PopupView(null, new Table(null, TableExample.generateContent())); // A component to open the view -Button button = new Button("Show table", click -> // Java 8 +Button button = new Button("Show table", click -> popup.setPopupVisible(true)); layout.addComponents(button, popup); diff --git a/documentation/components/components-selection.asciidoc b/documentation/components/components-selection.asciidoc index a5ec2f086f..0b42116a82 100644 --- a/documentation/components/components-selection.asciidoc +++ b/documentation/components/components-selection.asciidoc @@ -7,15 +7,17 @@ layout: page [[components.selection]] = Selection Components +For a better overview on how selection works, see link:../datamodel/datamodel-selection.asciidoc[Selecting items] + Vaadin offers many alternative ways for selecting one or more items. The core -library includes the following selection components, all based on the -[classname]#AbstractSelect# class: +library includes the following selection components, all based on either +`AbstractSingleSelect` or `AbstractMultiSelect` class: // TODO Only use section numbers here, prefixed with "Section", not include section title [classname]#ComboBox# (<<components-combobox#components.combobox,"ComboBox">>):: A drop-down list with a text box, where the user can type text to find matching items. -The component also provides an input prompt and the user can enter new items. +The component also provides a placeholder and the user can enter new items. [classname]#ListSelect# (<<components-listselect#components.listselect,"ListSelect">>):: A vertical list box for selecting items in either single or multiple selection mode. @@ -33,36 +35,22 @@ Shows the items as a vertically arranged group of check boxes in multiple select [classname]#TwinColSelect# (<<components-twincolselect#components.twincolselect, "TwinColSelect">>):: Shows two list boxes side by side where the user can select items from a list of available items and move them to a list of selected items using control buttons. -In addition, the [classname]#Tree#, [classname]#Table#, and [classname]#TreeTable# components allow special forms of selection. -They also inherit [classname]#AbstractSelect#. +In addition, the [classname]#Grid# component allows user selection. [[components.selection.databinding]] == Binding Selection Components to Data -The selection components typically bound to list of items obtained from backend system. -You can give the the list of items in the constructor or set it set +The selection components are typically bound to list of items obtained from backend system. +You can give the list of items in the constructor or set it with [methodname]#setItems()#. Read more in <<dummy/../../../framework/datamodel/datamodel-overview.asciidoc#datamodel.overview,"Binding Components to Data">>. You can get the current selection as the -value of the selection component using [methodname]#getSelected# defined in -[interfacename]#Select# interface. Also selection changes are handled as -selection change events, as is described later. - -[[components.selection.adding]] -== Adding New Items - -New items are added with the [methodname]#addItems()# method. - -[source, java] ----- -// Create a selection component -ComboBox<String> select = new ComboBox<>("Select a planet"); +value of the selection component using [methodname]#getValue# defined in +[interfacename]#HasValue# interface. Selection changes are handled as value change or +selection events, as is described later. -// Add items to select -select.setItems("Mercury","Venus","Earth"); ----- [[components.selection.captions]] == Item Captions @@ -70,7 +58,7 @@ select.setItems("Mercury","Venus","Earth"); The items are typically a strings, in which case they can be used as the caption, but can be any object type. We could as well have given Planet instances for the items and use captions generated based on them -[methodname]#setItemCaptionProvider()# method. +[methodname]#setItemCaptionGenerator()# method. [source, java] ---- @@ -86,15 +74,17 @@ ComboBox<Planet> select = new ComboBox<>("My Select"); // Add an items to the ComboBox select.setItems(planets); -select.setItemCaptionProvider(planet -> planet.getName()); -// or even select.setItemCaptionProvider(Planet::getName); +select.setItemCaptionGenerator(planet -> planet.getName()); +// or even select.setItemCaptionGenerator(Planet::getName); // Select the first -select.select(planets.get(0)); +select.setSelectedItem(planets.get(0)); +// or +select.setValue(planets.get(0)); ---- In addition to a caption, an item can have an icon. The icon is set with -[methodname]#setItemIconProvider()#. +[methodname]#setItemIconGenerator()#. Typical use cases for captions are: @@ -126,39 +116,12 @@ planets.add(new Planet("Mercury")); planets.add(new Planet("Venus")); planets.add(new Planet("Earth")); -select.addItems(planets); +select.setItems(planets); ---- Using a field of a item as caption: the caption is retrieved using the -[interfacename]#ItemCaptionProvider# typically given as Java 8 lambda: - - - -INDEX:: -Index number of item is used as caption. -This caption mode is applicable only to data sources that implement the [interfacename]#Container.Indexed# interface. -If the interface is not available, the component will throw a -[classname]#ClassCastException#. -The [classname]#AbstractSelect# itself does not implement this interface, so the mode is not usable without a separate data source. -An [classname]#IndexedContainer#, for example, would work. +[interfacename]#ItemCaptionGenerator# typically given as Java 8 lambda. -ITEM:: [classname]#String# representation of item, acquired with -[methodname]#toString()#, is used as the caption. This is applicable mainly when -using a custom [classname]#Item# class, which also requires using a custom -[classname]#Container# that is used as a data source for the selection -component. - -PROPERTY:: Item captions are read from the [classname]#String# representation of the -property with the identifier specified with -[methodname]#setItemCaptionPropertyId()#. This is useful, for example, when you -have a container that you use as the data source for the selection component, -and you want to use a specific property for caption. - -+ -In the example below, we bind a selection component to a bean container and use -a property of the bean as the caption. - -+ [source, java] ---- // A class that implements toString() @@ -197,60 +160,27 @@ planets.add(new Planet(4, "Mars")); ComboBox<Planet> select = new ComboBox<>("Planets"); -// Set the caption provider to read the +// Set the caption generator to read the // caption directly from the 'name' // property of the bean -select.setItemCaptionProvider(Planet::getName); ----- - -[[components.selection.getset]] -== Getting and Setting Selection - -You can get the item with [methodname]#getSelected()# of the -[classname]#Select# interface that returns collection of selected items. -You can select an item with the corresponding [methodname]#select()# method. - -In multiselect mode, the [methodname]#getSelected()# returns an unmodifiable -set of items. If no item is selected, the select will be an empty collection. - -The [classname]#ComboBox# and [classname]#NativeSelect# will show empty -selection when no actual item is selected. - - -[[components.selection.valuechange]] -== Handling Selection Changes - -You can access currently selected item with the [methodname]#getSelected()# or -[methodname]#getFirstSelected()# method of the component. Also, when -handling selection changes with a -[classname]#SelectionChangeListener#, the -[classname]#SelectionChange# will have the selected items of the event. - - -[source, java] +select.setItemCaptionGenerator(Planet::getName); ---- -// Create a selection component with some items -ComboBox<String> select = new ComboBox<>("My Select"); -select.setItems("Io", "Europa", "Ganymedes", "Callisto"); -// Handle selection change -select.addSelectionChangeListener(event -> - layout.addComponent(new Label("Selected " + - event.getSelected()))); ----- -The result of user interaction is shown in -<<figure.components.selection.valuechange>>. +[[components.selection.item-icons]] +== Item Icons -[[figure.components.selection.valuechange]] -.Selected Item -image::img/select-selected1.png[width=30%, scaledwidth=40%] +You can set an icon for each item with [methodname]#setItemIconGenerator()#, +in a fashion similar to captions. Notice, however, that icons are not +supported in [classname]#NativeSelect#, [classname]#TwinColSelect#, and +some other selection components and modes. This is because HTML does not +support images inside the native [literal]#++select++# +elements. [[components.selection.newitems]] == Allowing Adding New Items - [classname]#ComboBox# allows the user to add new items, when the user types in a value and presses kbd:[Enter]. You need to enable this with [methodname]#setNewItemHandler()#. @@ -262,7 +192,7 @@ attempt to do so may result in an exception. === Handling New Items Adding new items is handled by a [interfacename]#NewItemHandler#, which gets the -item caption string as parameter for the [methodname]#addNewItem()# method. +item caption string as parameter for the [methodname]#accept(String)# method. ifdef::web[] @@ -280,7 +210,7 @@ ComboBox<Planet> select = select.setItems(planets); // Use the name property for item captions -select.setItemCaptionProvider(Planet::getName); +select.setItemCaptionGenerator(Planet::getName); // Allow adding new items and add // handling for new items @@ -299,22 +229,69 @@ select.setNewItemHandler(inputString -> { Notification.show("Added new planet called " + inputString); }); + + +[[components.selection.getset]] +== Getting and Setting Selection + +For a better overview on how selection works, see link:../datamodel/datamodel-selection.asciidoc[Selecting items] + +You can get selected the item with [methodname]#getValue()# of the +[classname]#HasValue# interface that returns either a single selected item +(case of `SingleSelect`) or a collection of selected items (case of `MultiSelect`). +You can select an item with the corresponding [methodname]#setValue()# method. + +The [classname]#ComboBox# and [classname]#NativeSelect# will show empty +selection when no actual item is selected. + + +[[components.selection.valuechange]] +== Handling Selection Changes + +You can access the currently selected item with the [methodname]#getValue()# (`SingleSelect`) or +[methodname]#getSelectedItems()# (`MultiSelect`) method of the component. Also, when +handling selection changes with a +[classname]#SelectionListener#, the +[classname]#SelectionEvent# will have the selected items of the event. Single- and Multiselect +components have their own more specific listener and event types, `SingleSelectionListener` for `SingleSelectionEvent` and `MultiSelectionListener` for `MultiSelectionEvent` respectively. Both can be added with the `addSelectionListener` method. + + +[source, java] +---- +// Create a selection component with some items +ComboBox<String> select = new ComboBox<>("My Select"); +select.setItems("Io", "Europa", "Ganymedes", "Callisto"); + +// Handle selection change +select.addSelectionListener(event -> + layout.addComponent(new Label("Selected " + + event.getSelectedItem().orElse("none"))); +---- + +The result of user interaction is shown in +<<figure.components.selection.valuechange>>. + +[[figure.components.selection.valuechange]] +.Selected Item +image::img/select-selected1.png[width=30%, scaledwidth=40%] + + ---- -See the http://demo.vaadin.com/book-examples-vaadin7/book#component.select.combobox.newitemhandler[on-line example, window="_blank"]. endif::web[] [[components.selection.multiple]] == Multiple Selection +For a better overview on how selection works, see link:../datamodel/datamodel-selection.asciidoc[Selecting items] + Some selection components, such as [classname]#CheckBoxGroup#, -[classname]#ListSelect# and [classname]#TwinColSelect# are multiselect components, +[classname]#ListSelect# and [classname]#TwinColSelect# are multiselect components, they extend [classname]#AbstractMultiSelect# class. -Multiselect components use the [interfacename]#SelectionModel.Multi# selection model. -This model allows to select multiple items. -You can get and set the selection with the [methodname]#SelectionModel.getSelectedItems()# and +Multiselect components use the `MultiSelect` interface which extends `HasValue`. +This provides more fine grained API for selection. You can get and set the selection with the [methodname]#MultiSelect.getSelectedItems()# and [methodname]#SelectionModel.Multi.selectItems()# methods. A change in the selection will trigger a [classname]#SelectionChange#, which @@ -338,14 +315,3 @@ select.addSelectionListener(event -> { }); ---- - - -[[components.selection.item-icons]] -== Item Icons - -You can set an icon for each item with [methodname]#setItemIconProvider()#, -in a fashion similar to captions. Notice, however, that icons are not -supported in [classname]#NativeSelect#, [classname]#TwinColSelect#, and -some other selection components and modes. This is because HTML does not -support images inside the native [literal]#++select++# -elements. Icons are also not really visually applicable. diff --git a/documentation/components/components-table.asciidoc b/documentation/components/components-table.asciidoc deleted file mode 100644 index 25abb2263c..0000000000 --- a/documentation/components/components-table.asciidoc +++ /dev/null @@ -1,1166 +0,0 @@ ---- -title: Table -order: 21 -layout: page ---- - -[[components.table]] -= [classname]#Table# - -ifdef::web[] -[.sampler] -image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/grids-and-trees/table"] -endif::web[] - -((("[classname]#Table#", id="term.components.table", range="startofrange"))) - -[NOTE] -==== -[classname]#Table# is largely obsolete and has been replaced by the newer [classname]#Grid# component. -Nevertheless, it still has some features, such as drag and drop, which have no counterpart in Grid. -Table also still uses the old data API. -Hence, only a short introduction is given below; see the online Vaadin Docs for more details. -==== - -The [classname]#Table# component is intended for presenting tabular data -organized in rows and columns. The [classname]#Table# is one of the most -versatile components in Vaadin. Table cells can include text or arbitrary UI -components. You can easily implement editing of the table data, for example -clicking on a cell could change it to a text field for editing. - -.Basic Table Example -image::img/table-example1.png[width=35%, scaledwidth=50%] - -The data contained in a [classname]#Table# is managed using the Vaadin data model (see <<dummy/../../../framework/datamodel/datamodel-overview.asciidoc#datamodel.overview,"Binding Components to Data">>), through the [classname]#Container# interface of the [classname]#Table#. -This makes it possible to bind a table directly to a data source, such as a database query. -Only the visible part of the table is loaded -into the browser and moving the visible window with the scrollbar loads content -from the server. While the data is being loaded, a tooltip will be displayed -that shows the current range and total number of items in the table. The rows of -the table are __items__ in the container and the columns are __properties__. -Each table row (item) is identified with an __item identifier__ (IID), and each -column (property) with a __property identifier__ (PID). - -When creating a table, you first need to define columns with -[methodname]#addContainerProperty()#. This method comes in two flavors. The -simpler one takes the property ID of the column and uses it also as the caption -of the column. The more complex one allows differing PID and header for the -column. This may make, for example, internationalization of table headers -easier, because if a PID is internationalized, the internationalization has to -be used everywhere where the PID is used. The complex form of the method also -allows defining an icon for the column from a resource. The "default value" -parameter is used when new properties (columns) are added to the table, to fill -in the missing values. (This default has no meaning in the usual case, such as -below, where we add items after defining the properties.) - -[source, java] ----- -Table table = new Table("The Brightest Stars"); - -// Define two columns for the built-in container -table.addContainerProperty("Name", String.class, null); -table.addContainerProperty("Mag", Float.class, null); - -// Add a row the hard way -Object newItemId = table.addItem(); -Item row1 = table.getItem(newItemId); -row1.getItemProperty("Name").setValue("Sirius"); -row1.getItemProperty("Mag").setValue(-1.46f); - -// Add a few other rows using shorthand addItem() -table.addItem(new Object[]{"Canopus", -0.72f}, 2); -table.addItem(new Object[]{"Arcturus", -0.04f}, 3); -table.addItem(new Object[]{"Alpha Centauri", -0.01f}, 4); - -// Show exactly the currently contained rows (items) -table.setPageLength(table.size()); ----- - -In this example, we used an increasing [classname]#Integer# object as the Item -Identifier, given as the second parameter to [methodname]#addItem()#. The actual -rows are given simply as object arrays, in the same order in which the -properties were added. The objects must be of the correct class, as defined in -the [methodname]#addContainerProperty()# calls. - -ifdef::vaadin7[] - -Scalability of the [classname]#Table# is largely dictated by the container. The -default [classname]#IndexedContainer# is relatively heavy and can cause -scalability problems, for example, when updating the values. Use of an optimized -application-specific container is recommended. Table does not have a limit for -the number of items and is just as fast with hundreds of thousands of items as -with just a few. With the current implementation of scrolling, there is a limit -of around 500 000 rows, depending on the browser and the pixel height of rows. - -Common selection component features are described in -<<dummy/../../../framework/components/components-selection#components.selection,"Selection Components">>. - -[[components.table.selecting]] -== Selecting Items in a Table - -The [classname]#Table# allows selecting one or more items by clicking them with -the mouse. When the user selects an item, the IID of the item will be set as the -property of the table and a [classname]#ValueChangeEvent# is triggered. To -enable selection, you need to set the table __selectable__. You will also need -to set it as __immediate__ in most cases, as we do below, because without it, -the change in the property will not be communicated immediately to the server. - -The following example shows how to enable the selection of items in a -[classname]#Table# and how to handle [classname]#ValueChangeEvent# events that -are caused by changes in selection. You need to handle the event with the -[methodname]#valueChange()# method of the -[classname]#Property.ValueChangeListener# interface. - - -[source, java] ----- -// Allow selecting items from the table. -table.setSelectable(true); - -// Send changes in selection immediately to server. -table.setImmediate(true); - -// Shows feedback from selection. -final Label current = new Label("Selected: -"); - -// Handle selection change. -table.addValueChangeListener(new Property.ValueChangeListener() { - public void valueChange(ValueChangeEvent event) { - current.setValue("Selected: " + table.getValue()); - } -}); ----- - -.Table selection example -image::img/table-example2.png[width=35%, scaledwidth=80%] - -If the user clicks on an already selected item, the selection will deselected -and the table property will have [parameter]#null# value. You can disable this -behaviour by setting [methodname]#setNullSelectionAllowed(false)# for the table. - -The selection is the value of the table's property, so you can get it with -[methodname]#getValue()#. You can get it also from a reference to the table -itself. In single selection mode, the value is the item identifier of the -selected item or [parameter]#null# if no item is selected. In multiple selection -mode (see below), the value is a [classname]#Set# of item identifiers. Notice -that the set is unmodifiable, so you can not simply change it to change the -selection. - -=== Multiple Selection Mode - -A table can also be in __multiselect__ mode, where a user can select multiple -items by clicking them with left mouse button while holding the kbd:[Ctrl] key (or kbd:[Meta] key) pressed. If kbd:[Ctrl] is not held, clicking an item will select it and -other selected items are deselected. The user can select a range by selecting an -item, holding the kbd:[Shift] key pressed, and clicking another item, in which case -all the items between the two are also selected. Multiple ranges can be selected -by first selecting a range, then selecting an item while holding kbd:[Ctrl], and then -selecting another item with both kbd:[Ctrl] and kbd:[Shift] pressed. - -The multiselect mode is enabled with the [methodname]#setMultiSelect()# method -of the [classname]#AbstractSelect# superclass of [classname]#Table#. Setting -table in multiselect mode does not implicitly set it as __selectable__, so it -must be set separately. - -The [methodname]#setMultiSelectMode()# property affects the control of multiple -selection: [parameter]#MultiSelectMode.DEFAULT# is the default behaviour, which -requires holding the kbd:[Ctrl] (or kbd:[Meta]) key pressed while selecting items, while in -[parameter]#MultiSelectMode.SIMPLE# holding the kbd:[Ctrl] key is not needed. In the -simple mode, items can only be deselected by clicking them. - - - -[[components.table.features]] -== Table Features - -=== Page Length and Scrollbar - -The default style for [classname]#Table# provides a table with a scrollbar. The -scrollbar is located at the right side of the table and becomes visible when the -number of items in the table exceeds the page length, that is, the number of -visible items. You can set the page length with [methodname]#setPageLength()#. - -Setting the page length to zero makes all the rows in a table visible, no matter -how many rows there are. Notice that this also effectively disables buffering, -as all the entire table is loaded to the browser at once. Using such tables to -generate reports does not scale up very well, as there is some inevitable -overhead in rendering a table with Ajax. For very large reports, generating HTML -directly is a more scalable solution. - - -[[components.table.features.resizing]] -=== Resizing Columns - -You can set the width of a column programmatically from the server-side with -[methodname]#setColumnWidth()#. The column is identified by the property ID and -the width is given in pixels. - -The user can resize table columns by dragging the resize handle between two -columns. Resizing a table column causes a [classname]#ColumnResizeEvent#, which -you can handle with a [classname]#Table.ColumnResizeListener#. The table must be -set in immediate mode if you want to receive the resize events immediately, -which is typical. - - -[source, java] ----- -table.addColumnResizeListener(new Table.ColumnResizeListener(){ - public void columnResize(ColumnResizeEvent event) { - // Get the new width of the resized column - int width = event.getCurrentWidth(); - - // Get the property ID of the resized column - String column = (String) event.getPropertyId(); - - // Do something with the information - table.setColumnFooter(column, String.valueOf(width) + "px"); - } -}); - -// Must be immediate to send the resize events immediately -table.setImmediate(true); ----- - -See <<figure.component.table.columnresize>> for a result after the columns of a -table has been resized. - -[[figure.component.table.columnresize]] -.Resizing Columns -image::img/table-column-resize.png[width=50%, scaledwidth=80%] - - -[[components.table.features.reordering]] -=== Reordering Columns - -If [methodname]#setColumnReorderingAllowed(true)# is set, the user can reorder -table columns by dragging them with the mouse from the column header, - - -[[components.table.features.collapsing]] -=== Collapsing Columns - -When [methodname]#setColumnCollapsingAllowed(true)# is set, the right side of -the table header shows a drop-down list that allows selecting which columns are -shown. Collapsing columns is different than hiding columns with -[methodname]#setVisibleColumns()#, which hides the columns completely so that -they can not be made visible (uncollapsed) from the user interface. - -You can collapse columns programmatically with -[methodname]#setColumnCollapsed()#. Collapsing must be enabled before collapsing -columns with the method or it will throw an [classname]#IllegalAccessException#. - - -[source, java] ----- -// Allow the user to collapse and uncollapse columns -table.setColumnCollapsingAllowed(true); - -// Collapse this column programmatically -try { - table.setColumnCollapsed("born", true); -} catch (IllegalAccessException e) { - // Can't occur - collapsing was allowed above - System.err.println("Something horrible occurred"); -} - -// Give enough width for the table to accommodate the -// initially collapsed column later -table.setWidth("250px"); ----- - -See <<figure.component.table.columncollapsing>>. - -[[figure.component.table.columncollapsing]] -.Collapsing Columns -image::img/table-column-collapsing.png[width=40%, scaledwidth=80%] - -If the table has undefined width, it minimizes its width to fit the width of the -visible columns. If some columns are initially collapsed, the width of the table -may not be enough to accomodate them later, which will result in an ugly -horizontal scrollbar. You should consider giving the table enough width to -accomodate columns uncollapsed by the user. - - -[[components.table.features.components]] -=== Components Inside a Table - -The cells of a [classname]#Table# can contain any user interface components, not -just strings. If the rows are higher than the row height defined in the default -theme, you have to define the proper row height in a custom theme. - -When handling events for components inside a [classname]#Table#, such as for the -[classname]#Button# in the example below, you usually need to know the item the -component belongs to. Components do not themselves know about the table or the -specific item in which a component is contained. Therefore, the handling method -must use some other means for finding out the Item ID of the item. There are a -few possibilities. Usually the easiest way is to use the [methodname]#setData()# -method to attach an arbitrary object to a component. You can subclass the -component and include the identity information there. You can also simply search -the entire table for the item with the component, although that solution may not -be so scalable. - -The example below includes table rows with a [classname]#Label# in HTML content -mode, a multiline [classname]#TextField#, a [classname]#CheckBox#, and a -[classname]#Button# that shows as a link. - - -[source, java] ----- -// Create a table and add a style to -// allow setting the row height in theme. -Table table = new Table(); -table.addStyleName("components-inside"); - -/* Define the names and data types of columns. - * The "default value" parameter is meaningless here. */ -table.addContainerProperty("Sum", Label.class, null); -table.addContainerProperty("Is Transferred", CheckBox.class, null); -table.addContainerProperty("Comments", TextField.class, null); -table.addContainerProperty("Details", Button.class, null); - -/* Add a few items in the table. */ -for (int i=0; i<100; i++) { - // Create the fields for the current table row - Label sumField = new Label(String.format( - "Sum is <b>$%04.2f</b><br/><i>(VAT incl.)</i>", - new Object[] {new Double(Math.random()*1000)}), - ContentMode.HTML); - CheckBox transferredField = new CheckBox("is transferred"); - - // Multiline text field. This required modifying the - // height of the table row. - TextField commentsField = new TextField(); - commentsField.setRows(3); - - // The Table item identifier for the row. - Integer itemId = new Integer(i); - - // Create a button and handle its click. A Button does not - // know the item it is contained in, so we have to store the - // item ID as user-defined data. - Button detailsField = new Button("show details"); - detailsField.setData(itemId); - detailsField.addClickListener(new Button.ClickListener() { - public void buttonClick(ClickEvent event) { - // Get the item identifier from the user-defined data. - Integer iid = (Integer)event.getButton().getData(); - Notification.show("Link " + - iid.intValue() + " clicked."); - } - }); - detailsField.addStyleName("link"); - - // Create the table row. - table.addItem(new Object[] {sumField, transferredField, - commentsField, detailsField}, - itemId); -} - -// Show just three rows because they are so high. -table.setPageLength(3); ----- -See the http://demo.vaadin.com/book-examples-vaadin7/book#component.table.components.components2[on-line example, window="_blank"]. - -The row height has to be set higher than the default with a style rule such as -the following: - - -[source, css] ----- -/* Table rows contain three-row TextField components. */ -.v-table-components-inside .v-table-cell-content { - height: 54px; -} ----- -See the http://demo.vaadin.com/book-examples-vaadin7/book#component.table.components.components2[on-line example, window="_blank"]. - -The table will look as shown in <<figure.components.table.components-inside>>. - -[[figure.components.table.components-inside]] -.Components in a Table -image::img/table-components.png[width=70%, scaledwidth=100%] - - -[[components.table.features.iterating]] -=== Iterating Over a Table - -As the items in a [classname]#Table# are not indexed, iterating over the items -has to be done using an iterator. The [methodname]#getItemIds()# method of the -[classname]#Container# interface of [classname]#Table# returns a -[classname]#Collection# of item identifiers over which you can iterate using an -[classname]#Iterator#. For an example about iterating over a [classname]#Table#, -please see -<<dummy/../../../framework/datamodel/datamodel-container#datamodel.container,"Collecting -Items in Containers">>. Notice that you may not modify the [classname]#Table# -during iteration, that is, add or remove items. Changing the data is allowed. - - -[[components.table.features.filtering]] -=== Filtering Table Contents - -A table can be filtered if its container data source implements the -[classname]#Filterable# interface, as the default [classname]#IndexedContainer# -does. See -<<dummy/../../../framework/datamodel/datamodel-container#datamodel.container.filtered,"Filterable -Containers">>. ((("Container", -"Filterable"))) - - - -[[components.table.editing]] -== Editing the Values in a Table - -Normally, a [classname]#Table# simply displays the items and their fields as -text. If you want to allow the user to edit the values, you can either put them -inside components as we did earlier or simply call -[methodname]#setEditable(true)#, in which case the cells are automatically -turned into editable fields. - -Let us begin with a regular table with a some columns with usual Java types, -namely a [classname]#Date#, [classname]#Boolean#, and a [classname]#String#. - - -[source, java] ----- -// Create a table. It is by default not editable. -Table table = new Table(); - -// Define the names and data types of columns. -table.addContainerProperty("Date", Date.class, null); -table.addContainerProperty("Work", Boolean.class, null); -table.addContainerProperty("Comments", String.class, null); - -... ----- - -You could put the table in editable mode right away. We continue the example by -adding a check box to switch the table between normal and editable modes: - - -[source, java] ----- -CheckBox editable = new CheckBox("Editable", true); -editable.addValueChangeListener(valueChange -> // Java 8 - table.setEditable((Boolean) editable.getValue())); ----- - -Now, when you check to checkbox, the components in the table turn into editable -fields, as shown in <<figure.component.table.editable>>. - -[[figure.component.table.editable]] -.A Table in Normal and Editable Mode -image::img/table-editable3.png[width=100%, scaledwidth=100%] - -[[components.table.editing.fieldfactories]] -=== Field Factories - -The field components that allow editing the values of particular types in a -table are defined in a field factory that implements the -[classname]#TableFieldFactory# interface. The default implementation is -[classname]#DefaultFieldFactory#, which offers the following crude mappings: - -.Type to Field Mappings in [classname]#DefaultFieldFactory# -[options="header",cols="2,5"] -|=============== -|Property Type|Mapped to Field Class -|[classname]#Date#|A [classname]#DateField#. -|[classname]#Boolean#|A [classname]#CheckBox#. -|[classname]#Item#|A [classname]#Form# (deprecated in Vaadin 7). The fields of the form are automatically created from the item's properties using a [classname]#FormFieldFactory#. The normal use for this property type is inside a [classname]#Form# and is less useful inside a [classname]#Table#. -|__other__|A [classname]#TextField#. The text field manages conversions from the basic types, if possible. - -|=============== - - - -Field factories are covered with more detail in -<<dummy/../../../framework/datamodel/datamodel-itembinding#datamodel.itembinding,"Creating -Forms by Binding Fields to Items">>. You could just implement the -[classname]#TableFieldFactory# interface, but we recommend that you extend the -[classname]#DefaultFieldFactory# according to your needs. In the default -implementation, the mappings are defined in the -[methodname]#createFieldByPropertyType()# method (you might want to look at the -source code) both for tables and forms. - - -ifdef::web[] -[[components.table.editing.navigation]] -=== Navigation in Editable Mode - -In the editable mode, the editor fields can have focus. Pressing Tab moves the -focus to next column or, at the last column, to the first column of the next -item. Respectively, pressing kbd:[Shift+Tab] moves the focus backward. If the focus is -in the last column of the last visible item, the pressing kbd:[Tab] moves the focus -outside the table. Moving backward from the first column of the first item moves -the focus to the table itself. Some updates to the table, such as changing the -headers or footers or regenerating a column, can move the focus from an editor -component to the table itself. - -The default behaviour may be undesirable in many cases. For example, the focus -also goes through any read-only editor fields and can move out of the table -inappropriately. You can provide better navigation is to use event handler for -shortcut keys such as kbd:[Tab], kbd:[Arrow Up], kbd:[Arrow Down], and kbd:[Enter]. - - -[source, java] ----- -// Keyboard navigation -class KbdHandler implements Handler { - Action tab_next = new ShortcutAction("Tab", - ShortcutAction.KeyCode.TAB, null); - Action tab_prev = new ShortcutAction("Shift+Tab", - ShortcutAction.KeyCode.TAB, - new int[] {ShortcutAction.ModifierKey.SHIFT}); - Action cur_down = new ShortcutAction("Down", - ShortcutAction.KeyCode.ARROW_DOWN, null); - Action cur_up = new ShortcutAction("Up", - ShortcutAction.KeyCode.ARROW_UP, null); - Action enter = new ShortcutAction("Enter", - ShortcutAction.KeyCode.ENTER, null); - public Action[] getActions(Object target, Object sender) { - return new Action[] {tab_next, tab_prev, cur_down, - cur_up, enter}; - } - - public void handleAction(Action action, Object sender, - Object target) { - if (target instanceof TextField) { - // Move according to keypress - int itemid = (Integer) ((TextField) target).getData(); - if (action == tab_next || action == cur_down) - itemid++; - else if (action == tab_prev || action == cur_up) - itemid--; - // On enter, just stay where you were. If we did - // not catch the enter action, the focus would be - // moved to wrong place. - - if (itemid >= 0 && itemid < table.size()) { - TextField newTF = valueFields.get(itemid); - if (newTF != null) - newTF.focus(); - } - } - } -} - -// Panel that handles keyboard navigation -Panel navigator = new Panel(); -navigator.addStyleName(Reindeer.PANEL_LIGHT); -navigator.addComponent(table); -navigator.addActionHandler(new KbdHandler()); ----- - -The main issue in implementing keyboard navigation in an editable table is that -the editor fields do not know the table they are in. To find the parent table, -you can either look up in the component container hierarchy or simply store a -reference to the table with [methodname]#setData()# in the field component. The -other issue is that you can not acquire a reference to an editor field from the -[classname]#Table# component. One solution is to use some external collection, -such as a [classname]#HashMap#, to map item IDs to the editor fields. - - -[source, java] ----- -// Can't access the editable components from the table so -// must store the information -final HashMap<Integer,TextField> valueFields = - new HashMap<Integer,TextField>(); ----- - -The map has to be filled in a [classname]#TableFieldFactory#, such as in the -following. You also need to set the reference to the table there and you can -also set the initial focus there. - - -[source, java] ----- -table.setTableFieldFactory(new TableFieldFactory () { - public Field createField(Container container, Object itemId, - Object propertyId, Component uiContext) { - TextField field = new TextField((String) propertyId); - - // User can only edit the numeric column - if ("Source of Fear".equals(propertyId)) - field.setReadOnly(true); - else { // The numeric column - // The field needs to know the item it is in - field.setData(itemId); - - // Remember the field - valueFields.put((Integer) itemId, field); - - // Focus the first editable value - if (((Integer)itemId) == 0) - field.focus(); - } - return field; - } -}); ----- - -The issues are complicated by the fact that the editor fields are not generated -for the entire table, but only for a cache window that includes the visible -items and some items above and below it. For example, if the beginning of a big -scrollable table is visible, the editor component for the last item does not -exist. This issue is relevant mostly if you want to have wrap-around navigation -that jumps from the last to first item and vice versa. - -endif::web[] - - -[[components.table.headersfooters]] -== Column Headers and Footers - -[classname]#Table# supports both column headers and footers; the headers are -enabled by default. - -[[components.table.headersfooters.headers]] -=== Headers - -The table header displays the column headers at the top of the table. You can -use the column headers to reorder or resize the columns, as described earlier. -By default, the header of a column is the property ID of the column, unless -given explicitly with [methodname]#setColumnHeader()#. - - -[source, java] ----- -// Define the properties -table.addContainerProperty("lastname", String.class, null); -table.addContainerProperty("born", Integer.class, null); -table.addContainerProperty("died", Integer.class, null); - -// Set nicer header names -table.setColumnHeader("lastname", "Name"); -table.setColumnHeader("born", "Born"); -table.setColumnHeader("died", "Died"); ----- - -The text of the column headers and the visibility of the header depends on the -__column header mode__. The header is visible by default, but you can disable it -with [methodname]#setColumnHeaderMode(Table.COLUMN_HEADER_MODE_HIDDEN)#. - - -[[components.table.headersfooters.footers]] -=== Footers - -The table footer can be useful for displaying sums or averages of values in a -column, and so on. The footer is not visible by default; you can enable it with -[methodname]#setFooterVisible(true)#. Unlike in the header, the column headers -are empty by default. You can set their value with -[methodname]#setColumnFooter()#. The columns are identified by their property -ID. - -The following example shows how to calculate average of the values in a column: - - -[source, java] ----- -// Have a table with a numeric column -Table table = new Table("Custom Table Footer"); -table.addContainerProperty("Name", String.class, null); -table.addContainerProperty("Died At Age", Integer.class, null); - -// Insert some data -Object people[][] = { {"Galileo", 77}, - {"Monnier", 83}, - {"Vaisala", 79}, - {"Oterma", 86}}; -for (int i=0; i<people.length; i++) - table.addItem(people[i], new Integer(i)); - -// Calculate the average of the numeric column -double avgAge = 0; -for (int i=0; i<people.length; i++) - avgAge += (Integer) people[i][1]; -avgAge /= people.length; - -// Set the footers -table.setFooterVisible(true); -table.setColumnFooter("Name", "Average"); -table.setColumnFooter("Died At Age", String.valueOf(avgAge)); - -// Adjust the table height a bit -table.setPageLength(table.size()); ----- - -The resulting table is shown in -<<figure.components.table.headersfooters.footer>>. - -[[figure.components.table.headersfooters.footer]] -.A Table with a Footer -image::img/table-footer.png[width=25%, scaledwidth=40%] - - -[[components.table.headersfooters.clicks]] -=== Handling Mouse Clicks on Headers and Footers - -Normally, when the user clicks a column header, the table will be sorted by the -column, assuming that the data source is [classname]#Sortable# and sorting is -not disabled. In some cases, you might want some other functionality when the -user clicks the column header, such as selecting the column in some way. - -Clicks in the header cause a [classname]#HeaderClickEvent#, which you can handle -with a [classname]#Table.HeaderClickListener#. Click events on the table header -(and footer) are, like button clicks, sent immediately to server, so there is no -need to set [methodname]#setImmediate()#. - - -[source, java] ----- -// Handle the header clicks -table.addHeaderClickListener(new Table.HeaderClickListener() { - public void headerClick(HeaderClickEvent event) { - String column = (String) event.getPropertyId(); - Notification.show("Clicked " + column + - "with " + event.getButtonName()); - } -}); - -// Disable the default sorting behavior -table.setSortDisabled(true); ----- - -Setting a click handler does not automatically disable the sorting behavior of -the header; you need to disable it explicitly with -[methodname]#setSortDisabled(true)#. Header click events are not sent when the -user clicks the column resize handlers to drag them. - -The [classname]#HeaderClickEvent# object provides the identity of the clicked -column with [methodname]#getPropertyId()#. The [methodname]#getButton()# reports -the mouse button with which the click was made: [parameter]#BUTTON_LEFT#, -[parameter]#BUTTON_RIGHT#, or [parameter]#BUTTON_MIDDLE#. The -[methodname]#getButtonName()# a human-readable button name in English: " -[parameter]#left#", " [parameter]#right#", or " [parameter]#middle#". The -[methodname]#isShiftKey()#, [methodname]#isCtrlKey()#, etc., methods indicate if -the kbd:[Shift], kbd:[Ctrl], kbd:[Alt] or other modifier keys were pressed during the click. - -Clicks in the footer cause a [classname]#FooterClickEvent#, which you can handle -with a [classname]#Table.FooterClickListener#. Footers do not have any default -click behavior, like the sorting in the header. Otherwise, handling clicks in -the footer is equivalent to handling clicks in the header. - - - -[[components.table.columngenerator]] -== Generated Table Columns - -A table can have generated columns which values can be calculated based on the -values in other columns. The columns are generated with a class implementing the -[interfacename]#Table.ColumnGenerator# interface. - -The [classname]#GeneratedPropertyContainer# described in -<<dummy/../../../framework/datamodel/datamodel-container#datamodel.container.gpc,"GeneratedPropertyContainer">> -is another way to accomplish the same task at container level. In addition to -generating values, you can also use the feature for formatting or styling -columns. - -ifdef::web[] -[[components.table.columngenerator.generator]] -=== Defining a Column Generator - -Column generators are objects that implement the -[classname]#Table.ColumnGenerator# interface and its -[methodname]#generateCell()# method. The method gets the identity of the item -and column as its parameters, in addition to the table object, and has to return -a component. The interface is functional, so you can also define it by a lambda -expression or a method reference in Java 8. - -The following example defines a generator for formatting [classname]#Double# -valued fields according to a format string (as in -[classname]#java.util.Formatter#). - - -[source, java] ----- -/** Formats the value in a column containing Double objects. */ -class ValueColumnGenerator implements Table.ColumnGenerator { - String format; /* Format string for the Double values. */ - - /** - * Creates double value column formatter with the given - * format string. - */ - public ValueColumnGenerator(String format) { - this.format = format; - } - - /** - * Generates the cell containing the Double value. - * The column is irrelevant in this use case. - */ - public Component generateCell(Table source, Object itemId, - Object columnId) { - // Get the object stored in the cell as a property - Property prop = - source.getItem(itemId).getItemProperty(columnId); - if (prop.getType().equals(Double.class)) { - Label label = new Label(String.format(format, - new Object[] { (Double) prop.getValue() })); - - // Set styles for the column: one indicating that it's - // a value and a more specific one with the column - // name in it. This assumes that the column name - // is proper for CSS. - label.addStyleName("column-type-value"); - label.addStyleName("column-" + (String) columnId); - return label; - } - return null; - } -} ----- - -The column generator is called for all the visible (or more accurately cached) -items in a table. If the user scrolls the table to another position in the -table, the columns of the new visible rows are generated dynamically. - -Generated column cells are automatically updated when a property value in the -table row changes. Note that a generated cell, even if it is a field, does not -normally have a property value bound to the table's container, so changes in -generated columns do not trigger updates in other generated columns. It should -also be noted that if a generated column cell depends on values in other rows, -changes in the other rows do not trigger automatic update. You can get notified -of such value changes by listening for them with a -[interfacename]#ValueChangeListener# in the generated components. If you do so, -you must remove such listeners when the generated components are detached from -the UI or otherwise the listeners will accumulate in the container when the -table is scrolled back and forth, causing possibly severe memory leak. - -endif::web[] - -ifdef::web[] -[[components.table.columngenerator.adding]] -=== Adding Generated Columns - -You add new generated columns to a [classname]#Table# with -[methodname]#addGeneratedColumn()#. It takes a property ID of the generated -column as the first parameter and the generator as the second. - - -[source, java] ----- -// Define the generated columns and their generators -table.addGeneratedColumn("date", // Java 8: - this::generateNonEditableCell); -table.addGeneratedColumn("price", - new PriceColumnGenerator()); -table.addGeneratedColumn("consumption", - new ConsumptionColumnGenerator()); -table.addGeneratedColumn("dailycost", - new DailyCostColumnGenerator()); ----- - -Notice that the [methodname]#addGeneratedColumn()# always places the generated -columns as the last column, even if you defined some other order previously. You -will have to set the proper order with [methodname]#setVisibleColumns()#. - - -[source, java] ----- -table.setVisibleColumns("date", "quantity", "price", "total"); ----- - -endif::web[] - -ifdef::web[] -[[components.table.columngenerator.editable]] -=== Generators in Editable Table - -When you set a table as [parameter]#editable#, table cells change to editable -fields. When the user changes the values in the fields, the generated cells in -the same row are updated automatically. However, putting a table with generated -columns in editable mode has a few quirks. One is that the editable mode does -not affect generated columns. You have two alternatives: either you generate the -editing fields in the generator or, in case of formatter generators, remove the -generators in the editable mode to allow editing the values. The following -example uses the latter approach. - - -[source, java] ----- -// Have a check box that allows the user -// to make the quantity and total columns editable. -final CheckBox editable = new CheckBox( - "Edit the input values - calculated columns are regenerated"); - -editable.setImmediate(true); -editable.addClickListener(new ClickListener() { - public void buttonClick(ClickEvent event) { - table.setEditable(editable.booleanValue()); - - // The columns may not be generated when we want to - // have them editable. - if (editable.booleanValue()) { - table.removeGeneratedColumn("quantity"); - table.removeGeneratedColumn("total"); - } else { // Not editable - // Show the formatted values. - table.addGeneratedColumn("quantity", - new ValueColumnGenerator("%.2f l")); - table.addGeneratedColumn("total", - new ValueColumnGenerator("%.2f e")); - } - // The visible columns are affected by removal - // and addition of generated columns so we have - // to redefine them. - table.setVisibleColumns("date", "quantity", - "price", "total", "consumption", "dailycost"); - } -}); ----- - -You will also have to set the editing fields in [parameter]#immediate# mode to -have the update occur immediately when an edit field loses the focus. You can -set the fields in [parameter]#immediate# mode with the a custom -[classname]#TableFieldFactory#, such as the one given below, that just extends -the default implementation to set the mode: - - -[source, java] ----- -public class ImmediateFieldFactory extends DefaultFieldFactory { - public Field createField(Container container, - Object itemId, - Object propertyId, - Component uiContext) { - // Let the DefaultFieldFactory create the fields... - Field field = super.createField(container, itemId, - propertyId, uiContext); - - // ...and just set them as immediate. - ((AbstractField)field).setImmediate(true); - - return field; - } -} -... -table.setTableFieldFactory(new ImmediateFieldFactory()); ----- - -If you generate the editing fields with the column generator, you avoid having -to use such a field factory, but of course have to generate the fields for both -normal and editable modes. - -<<figure.ui.table.generated>> shows a table with columns calculated (blue) and -simply formatted (black) with column generators. - -[[figure.ui.table.generated]] -.Table with generated columns -image::img/table-generatedcolumns1.png[width=90%, scaledwidth=100%] - -endif::web[] - - -[[components.table.columnformatting]] -== Formatting Table Columns - -The displayed values of properties shown in a table are normally formatted using -the [methodname]#toString()# method of each property. Customizing the format in -a table column can be done in several ways: - -* Using [classname]#ColumnGenerator# to generate a second column that is formatted. The original column needs to be set invisible. See <<components.table.columngenerator>>. -* Using a [classname]#Converter# to convert between the property data model and its representation in the table. -* Using a [classname]#GeneratedPropertyContainer# as a wrapper around the actual container to provide formatting. -* Overriding the default [methodname]#formatPropertyValue()# in [classname]#Table#. - -As using a [classname]#PropertyFormatter# is generally much more awkward than -overriding the [methodname]#formatPropertyValue()#, its use is not described -here. - -You can override [methodname]#formatPropertyValue()# as is done in the following -example: - - -[source, java] ----- -// Create a table that overrides the default -// property (column) format -final Table table = new Table("Formatted Table") { - @Override - protected String formatPropertyValue(Object rowId, - Object colId, Property property) { - // Format by property type - if (property.getType() == Date.class) { - SimpleDateFormat df = - new SimpleDateFormat("yyyy-MM-dd hh:mm:ss"); - return df.format((Date)property.getValue()); - } - - return super.formatPropertyValue(rowId, colId, property); - } -}; - -// The table has some columns -table.addContainerProperty("Time", Date.class, null); - -... Fill the table with data ... ----- - -You can also distinguish between columns by the [parameter]#colId# parameter, -which is the property ID of the column. [classname]#DecimalFormat# is useful for -formatting decimal values. - - -[source, java] ----- -... in formatPropertyValue() ... -} else if ("Value".equals(pid)) { - // Format a decimal value for a specific locale - DecimalFormat df = new DecimalFormat("#.00", - new DecimalFormatSymbols(locale)); - return df.format((Double) property.getValue()); -} -... -table.addContainerProperty("Value", Double.class, null); ----- - -A table with the formatted date and decimal value columns is shown in -<<figure.components.table.columnformatting>>. - -[[figure.components.table.columnformatting]] -.Formatted Table columns -image::img/table-columnformatting.png[width=40%, scaledwidth=50%] - -You can use CSS for further styling of table rows, columns, and individual cells by using a [classname]#CellStyleGenerator#. -ifdef::web[It is described in <<components.table.css>>.] - -[[components.table.css]] -== CSS Style Rules - -[source, css] ----- -.v-table {} - .v-table-header-wrap {} - .v-table-header {} - .v-table-header-cell {} - .v-table-resizer {} /* Column resizer handle. */ - .v-table-caption-container {} - .v-table-body {} - .v-table-row-spacer {} - .v-table-table {} - .v-table-row {} - .v-table-cell-content {} ----- - -Notice that some of the widths and heights in a table are calculated dynamically -and can not be set in CSS. - -ifdef::web[] -[[components.table.css.cellstylegenerator]] -=== Generating Cell Styles With [interfacename]#CellStyleGenerator# - -The [classname]#Table.CellStyleGenerator# interface allows you to set the CSS -style for each individual cell in a table. You need to implement the -[methodname]#getStyle()#, which gets the row (item) and column (property) -identifiers as parameters and can return a style name for the cell. The returned -style name will be concatenated to prefix " -[literal]#++v-table-cell-content-++#". - -The [methodname]#getStyle()# is called also for each row, so that the -[parameter]#propertyId# parameter is [literal]#++null++#. This allows setting a -row style. - -Alternatively, you can use a [classname]#Table.ColumnGenerator# (see -<<components.table.columngenerator>>) to generate the actual UI components of -the cells and add style names to them. - - -[source, java] ----- -Table table = new Table("Table with Cell Styles"); -table.addStyleName("checkerboard"); - -// Add some columns in the table. In this example, the property -// IDs of the container are integers so we can determine the -// column number easily. -table.addContainerProperty("0", String.class, null, "", null, null); -for (int i=0; i<8; i++) - table.addContainerProperty(""+(i+1), String.class, null, - String.valueOf((char) (65+i)), null, null); - -// Add some items in the table. -table.addItem(new Object[]{ - "1", "R", "N", "B", "Q", "K", "B", "N", "R"}, new Integer(0)); -table.addItem(new Object[]{ - "2", "P", "P", "P", "P", "P", "P", "P", "P"}, new Integer(1)); -for (int i=2; i<6; i++) - table.addItem(new Object[]{String.valueOf(i+1), - "", "", "", "", "", "", "", ""}, new Integer(i)); -table.addItem(new Object[]{ - "7", "P", "P", "P", "P", "P", "P", "P", "P"}, new Integer(6)); -table.addItem(new Object[]{ - "8", "R", "N", "B", "Q", "K", "B", "N", "R"}, new Integer(7)); -table.setPageLength(8); - -// Set cell style generator -table.setCellStyleGenerator(new Table.CellStyleGenerator() { - public String getStyle(Object itemId, Object propertyId) { - // Row style setting, not relevant in this example. - if (propertyId == null) - return "green"; // Will not actually be visible - - int row = ((Integer)itemId).intValue(); - int col = Integer.parseInt((String)propertyId); - - // The first column. - if (col == 0) - return "rowheader"; - - // Other cells. - if ((row+col)%2 == 0) - return "black"; - else - return "white"; - } -}); ----- - -You can then style the cells, for example, as follows: - - -[source, css] ----- -/* Center the text in header. */ -.v-table-header-cell { - text-align: center; -} - -/* Basic style for all cells. */ -.v-table-checkerboard .v-table-cell-content { - text-align: center; - vertical-align: middle; - padding-top: 12px; - width: 20px; - height: 28px; -} - -/* Style specifically for the row header cells. */ -.v-table-cell-content-rowheader { - background: #E7EDF3 - url(../default/table/img/header-bg.png) repeat-x scroll 0 0; -} - -/* Style specifically for the "white" cells. */ -.v-table-cell-content-white { - background: white; - color: black; -} - -/* Style specifically for the "black" cells. */ -.v-table-cell-content-black { - background: black; - color: white; -} ----- - -The table will look as shown in <<figure.components.table.cell-style>>. - -[[figure.components.table.cell-style]] -.Cell style generator for a Table -image::img/table-cellstylegenerator1.png[width=50%, scaledwidth=80%] - -endif::web[] - -endif::vaadin7[] - -(((range="endofrange", startref="term.components.table"))) diff --git a/documentation/components/components-textfield.asciidoc b/documentation/components/components-textfield.asciidoc index 5ecd2dc70d..1b543ed2ff 100644 --- a/documentation/components/components-textfield.asciidoc +++ b/documentation/components/components-textfield.asciidoc @@ -35,9 +35,7 @@ The result is shown in <<figure.components.textfield.basic>>. .[classname]#TextField# Example image::img/textfield-example.png[width=40%, scaledwidth=50%] -Value changes are handled by adding a listener using either the [methodname]#onChange()# -or [methodname]#addValueChangeListener()# method, as in most other fields. The value can be -acquired with [methodname]#getValue()# directly from the text field or from the parameter +Value changes are handled by adding a listener using [methodname]#addValueChangeListener()# method, as in most other fields. The value can be acquired with [methodname]#getValue()# directly from the text field or from the parameter passed to the event listener. [source, java] @@ -136,8 +134,8 @@ counter.setValue(tf.getValue().length() + " of " + tf.getMaxLength()); // Display the current length interactively in the counter -tf.onChange(value -> { - int len = value.length(); +tf.addValueChangeListener(event -> { + int len = event.getValue().length(); counter.setValue(len + " of " + tf.getMaxLength()); }); diff --git a/documentation/components/components-tree.asciidoc b/documentation/components/components-tree.asciidoc deleted file mode 100644 index b95f8bd2ae..0000000000 --- a/documentation/components/components-tree.asciidoc +++ /dev/null @@ -1,169 +0,0 @@ ---- -title: Tree -order: 22 -layout: page ---- - -[[components.tree]] -= [classname]#Tree# - -ifdef::web[] -[.sampler] -image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/grids-and-trees/tree"] -endif::web[] - -[NOTE] -==== -[classname]#Tree# still uses the old data API from Vaadin 7. -==== - -The [classname]#Tree# component allows a natural way to represent data that has hierarchical relationships. -The user can drill down in the hierarchy by expanding items by clicking on the expand arrow, and likewise collapse items. -[classname]#Tree# is a selection component that allows selecting items. -It also supports drag and drop, so you can drag items to and from a tree, and drop them in the hierarchy. - -A typical use of the [classname]#Tree# component is for displaying a hierarchical menu, as illustrated in <<figure.components.tree>>, or for displaying file systems or hierarchical datasets. - -[[figure.components.tree]] -.A [classname]#Tree# component as a menu -image::img/tree-example1.png[width=25%, scaledwidth=50%] - -The data is managed in a container implementing the [interfacename]#Hierarchical# interface, such as [classname]#HierarchicalContainer# or [classname]#FilesystemContainer#. -You can use [classname]#ContainerHierarchicalWrapper# to add hierarchical capability to any other container. [classname]#Tree# itself implements the interface and delegates operations to the underlying container. - -[source, java] ----- -// A menu tree -Tree menu = new Tree(); - -// Couple of childless root items -menu.addItem("Mercury"); -menu.setChildrenAllowed("Mercury", false); -menu.addItem("Venus"); -menu.setChildrenAllowed("Venus", false); - -// An item with hierarchy -menu.addItem("Earth"); -menu.addItem("The Moon"); -menu.setChildrenAllowed("The Moon", false); -menu.setParent("The Moon", "Earth"); -menu.expandItem("Earth"); // Expand programmatically -... ----- - -The result was shown in <<figure.components.tree>> in a practical situation, with the [classname]`Tree` wrapped inside a [classname]`Panel`. -[classname]`Tree` itself does not have scrollbar, but [classname]`Panel` can be used for the purpose. - -The caption of tree items is by default the item ID. -You can define how the item captions are determined with [methodname]#setItemCaptionMode()#, as explained <<components-selection#components.selection.captions, "Selection Component Item Captions">>. - -[[components.tree.selection]] -== Handling Selection and Clicks - -[classname]#Tree# is a selection component, which are described in <<components-selection#components.selection, "Selection Components">>. -You can thereby get or set the currently selected item by the value property of the tree, that is, with [methodname]#getValue()# and [methodname]#setValue()#. -When the user selects an item, the tree will receive an [classname]#ValueChangeEvent#, which you can catch with a [classname]#ValueChangeListener#. - -[source, Java] ----- -// Handle selection changes -menu.addValueChangeListener(event -> { // Java 8 - if (event.getProperty() != null && - event.getProperty().getValue() != null) { - location.setValue("The cat is in " + - event.getProperty().getValue()); - } -}); ----- - -[classname]#Tree# is selectable by default; you can disallow selection with [methodname]#setSelectable(false)#. - -[classname]#Tree# also emits [classname]##ItemClickEvent##s when items are clicked. -This way you can handle item clicks also when selection is not enabled or you want special user interaction specifically on clicks. - -[source, Java] ----- -tree.addItemClickListener( - new ItemClickEvent.ItemClickListener() { - public void itemClick(ItemClickEvent event) { - // Pick only left mouse clicks - if (event.getButton() == ItemClickEvent.BUTTON_LEFT) - Notification.show("Left click", - Notification.Type.HUMANIZED_MESSAGE); - } - }); ----- - -[[components.tree.expand-collapse]] -== Expanding and Collapsing Items - -An item can have children only if the [propertyname]#childrenAllowed# property is set as true. -The expand indicator is shown when and only when the property is true. -The property is defined in the container and can be set with [methodname]#setChildrenAllowed()#. - -Expanding an item fires an [classname]#Tree.ExpandEvent# and collapsing an [classname]#Tree.CollapseEvent#, which you can handle with respective listeners. - -[source, Java] ----- -tree.addExpandListener(new Tree.ExpandListener() { - public void nodeExpand(ExpandEvent event) { - Notification.show("Expand!"); - } -}); ----- - -You can expand and collapse items programmatically with [methodname]#expandItem()# or [methodname]#expandItemRecursively()#. - -[source, Java] ----- -// Expand all items that can be -for (Object itemId: tree.getItemIds()) - tree.expandItem(itemId); ----- - -TIP: [classname]#Tree# itself does not support lazy loading, which makes it impractical for huge hierarchies. -You can implement one kind of lazy loading by adding items in an expand listener and removing them in a collapse listener. -For more proper lazy loading, you can use [classname]#TreeTable# or hierarchical support extension for [classname]#Grid#. - -[[components.tree.css]] -== CSS Style Rules - -[source, css] ----- -.v-tree {} - .v-tree-node {} /* A node (item) */ - .v-tree-node-caption {} /* Caption of the node */ - .v-tree-node-children {} /* Contains child nodes */ - .v-tree-node-root {} /* If node is a root node */ - .v-tree-node-leaf {} /* If node has no children */ ----- - -[[components.tree.css.itemstyles]] -=== Generating Item Styles - -You can style each tree item individually by generating a style name for them with a [interfacename]#Tree.ItemStyleGenerator#, which you assign to a tree with [methodname]#setItemStyleGenerator()#. -The generator should return a style name for each item or `null`. - -[source, Java] ----- -// Show all leaf nodes as disabled -tree.setItemStyleGenerator(new Tree.ItemStyleGenerator() { - @Override - public String getStyle(Tree source, Object itemId) { - if (! tree.hasChildren(itemId)) - return "disabled"; - return null; - } -}); ----- - -The style names are prefixed with `v-tree-node-caption-`. -You could thereby define the item styling as follows: - -[source, CSS] ----- -.v-tree-node-caption-disabled { - color: graytext; - font-style: italic; -} ----- diff --git a/documentation/components/components-treetable.asciidoc b/documentation/components/components-treetable.asciidoc deleted file mode 100644 index 9fdfd10c78..0000000000 --- a/documentation/components/components-treetable.asciidoc +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: TreeTable -order: 23 -layout: page ---- - -[[components.treetable]] -= [classname]#TreeTable# - -ifdef::web[] -[.sampler] -image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/grids-and-trees/tree-table"] -endif::web[] - -[NOTE] -==== -[classname]#TreeTable# still uses the old data API from Vaadin 7. -==== - -[classname]#TreeTable# is an extension of the [classname]#Table# component with -support for a tree-like hierarchy in the first column. As with -[classname]#Tree#, the hierarchy is determined by the parent-children -relationships defined in the [interfacename]#Container.Hierarchical# interface. -The default container is [classname]#HierarchicalContainer#, but you can bind -[classname]#TreeTable# to any container implementing the interface. - -[[figure.components.treetable.basic]] -.The [classname]#TreeTable# component -image::img/treetable-basic.png[width=40%, scaledwidth=60%] - -As with [classname]#Tree#, you can define the parent-child relationships with -[methodname]#setParent()#, as is shown in the following example with numeric -item IDs: - -[source, java] ----- -TreeTable ttable = new TreeTable("My TreeTable"); -ttable.addContainerProperty("Name", String.class, null); -ttable.addContainerProperty("Number", Integer.class, null); - -// Create the tree nodes and set the hierarchy -ttable.addItem(new Object[]{"Menu", null}, 0); -ttable.addItem(new Object[]{"Beverages", null}, 1); -ttable.setParent(1, 0); -ttable.addItem(new Object[]{"Foods", null}, 2); -ttable.setParent(2, 0); -ttable.addItem(new Object[]{"Coffee", 23}, 3); -ttable.addItem(new Object[]{"Tea", 42}, 4); -ttable.setParent(3, 1); -ttable.setParent(4, 1); -ttable.addItem(new Object[]{"Bread", 13}, 5); -ttable.addItem(new Object[]{"Cake", 11}, 6); -ttable.setParent(5, 2); -ttable.setParent(6, 2); ----- - -Some container types may allow defining hierarchies if the container data -itself, without explicitly setting the parent-child relationships with -[methodname]#setParent()#. - -Unlike [classname]#Tree#, a [classname]#TreeTable# can have components in the -hierarchical column, both when the property type is a component type and when -the tree table is in editable mode. - -For other features, we refer you to documentation for [classname]#Table# in -<<dummy/../../../framework/components/components-table#components.table,"Table">> and [classname]#Tree# in <<dummy/../../../framework/components/components-tree#components.tree,"Tree">>. - -ifdef::web[] -[[components.treetable.collapsed]] -== Expanding and Collapsing Items - -As in [classname]#Tree#, you can set the expanded/collapsed state of an item -programmatically with [methodname]#setCollapsed()#. Note that if you want to -expand all items, there is no [methodname]#expandItemsRecursively()# like in -[classname]#Tree#. Moreover, the [methodname]#getItemIds()# only returns the IDs -of the currently visible items for ordinary [interfacename]#Hierarchical# (not -[interfacename]#Collapsible#) containers. Hence you can not use that to iterate -over all the items, but you need to get the IDs from the underlying container. - - -[source, java] ----- -// Expand the tree -for (Object itemId: ttable.getContainerDataSource() - .getItemIds()) { - ttable.setCollapsed(itemId, false); - - // As we're at it, also disallow children from - // the current leaves - if (! ttable.hasChildren(itemId)) - ttable.setChildrenAllowed(itemId, false); -} ----- - -In large tables, this explicit setting becomes infeasible, as it needs to be -stored in the [classname]#TreeTable# (more exactly, in the -[classname]#HierarchicalStrategy# object) for all the contained items. You can -use a [interfacename]#Collapsible# container to store the collapsed states in -the container, thereby avoiding the explicit settings and memory overhead. There -are no built-in collapsible containers in the Vaadin core framework, so you -either need to use an add-on container or implement it yourself. - -endif::web[] diff --git a/documentation/components/components-twincolselect.asciidoc b/documentation/components/components-twincolselect.asciidoc index cf0ed36e37..b5306359cb 100644 --- a/documentation/components/components-twincolselect.asciidoc +++ b/documentation/components/components-twincolselect.asciidoc @@ -46,14 +46,13 @@ select.setItems("Mercury", "Venus", "Earth", "Mars", select.setRows(select.size()); // Preselect a few items -select.setSelection("Venus", "Earth", "Mars"); +select.select("Venus", "Earth", "Mars"); // Handle value changes -select.onSelect(selectedItems -> +select.addSelectionListener(event -> layout.addComponent( - new Label("Selected: " + selectedItems))); + new Label("Selected: " + event.getNewSelection()))); ---- -See the http://demo.vaadin.com/book-examples-vaadin7/book#component.select.twincolselect.captions[on-line example, window="_blank"]. The resulting component is shown in <<figure.components.twincolselect.basic>>. diff --git a/documentation/components/components-upload.asciidoc b/documentation/components/components-upload.asciidoc index bb46228398..848dd9ef66 100644 --- a/documentation/components/components-upload.asciidoc +++ b/documentation/components/components-upload.asciidoc @@ -12,6 +12,8 @@ ifdef::web[] image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/data-input/other/upload"] endif::web[] +*_This section has not yet been updated to Vaadin Framework 8_* + The [classname]#Upload# component allows a user to upload files to the server. It displays a file name entry box, a file selection button, and an upload submit button. The user can either write the filename in the text area or click the @@ -45,7 +47,7 @@ upload.setButtonCaption("Upload Now"); You can also hide the upload button with [literal]#++.v-upload .v-button {display: none}++# in theme, have custom logic for starting the upload, and call [methodname]#startUpload()# to start it. If the upload component has -[methodname]#setImmediate(true)# enabled, uploading starts immediately after +[methodname]#setImmediateMode(true)# enabled, uploading starts immediately after choosing the file. [[components.upload.receiving]] |