class sap.ui.unified.calendar.MonthsRow

Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Module: sap/ui/unified/calendar/MonthsRow
Application Component: CA-UI5-CTR

Renders a row of months using ItemNavigation. There is no paging or navigation outside the rendered area implemented. This is done inside the CalendarMonthInterval. If used inside the CalendarMonthInterval the properties and aggregation are directly taken from the parent (to not duplicate and synchronize DateRanges and so on...).

The MontsRow works with JavaScript Date objects, but only the month and the year are used to display and interact. As representation for a month, the 1st of the month will always be returned in the API.


Constructor

Constructor for a new MonthsRow. It shows a calendar with month granularity

Note: This is used inside the CalendarMonthInterval, not for standalone usage.

Accepts an object literal mSettings that defines initial property values, aggregated and associated objects as well as event handlers. See sap.ui.base.ManagedObject#constructor for a general description of the syntax of the settings object.

new sap.ui.unified.calendar.MonthsRow(sId?, mSettings?)
Param Type Default Value Description
sId? string

ID for the new control, generated automatically if no ID is given

mSettings? object

Initial settings for the new control


Properties

Name Type Default Value Description
date object

A date as JavaScript Date object. The month including this date is rendered and this date is focused initially (if no other focus is set). If the date property is not in the range startDate + months in the rendering phase, it is set to the startDate. So after setting the startDate the date should be set to be in the visible range.

Visibility: public
intervalSelection boolean false

If set, interval selection is allowed

Visibility: public
months int 12

Number of months displayed

Visibility: public
showHeader boolean false

If set, a header with the years is shown to visualize what month belongs to what year.

Visibility: public
singleSelection boolean true

If set, only a single month or interval, if intervalSelection is enabled, can be selected

Note: Selection of multiple intervals is not supported in the current version.

Visibility: public
startDate object

Start date, as JavaScript Date object, of the row. The month of this date is the first month of the displayed row.

Visibility: public

Aggregations

Default Aggregation:

Name Cardinality Type Description
selectedDates 0..n sap.ui.unified.DateRange

Date ranges for selected dates. If singleSelection is set, only the first entry is used.

Note: Even if only one day is selected, the whole corresponding month is selected.

specialDates 0..n sap.ui.unified.DateTypeRange

Date ranges with type to visualize special months in the row. If one day is assigned to more than one type, only the first one will be used.

Note: Even if only one day is set as a special day, the whole corresponding month is displayed in this way.


Associations

Name Cardinality Type Description
ariaLabelledBy 0..n sap.ui.core.Control

Association to controls / IDs which label this control (see WAI-ARIA attribute aria-labelledby).

legend 0..1 sap.ui.unified.CalendarLegend

Association to the CalendarLegend explaining the colors of the specialDates.

Note The legend does not have to be rendered but must exist, and all required types must be assigned.

Since: 1.38.5.


Events Overview

Event Description
focus

Month focus changed

select

Month selection changed

focus

Month focus changed

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
date object

First date, as JavaScript Date object, of the month that is focused.

notVisible boolean

If set, the focused date is not rendered yet. (This happens by navigating out of the visible area.)

select

Month selection changed

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object

Methods Overview

Method Description
addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

addSelectedDate

Adds some selectedDate to the aggregation selectedDates.

addSpecialDate

Adds some specialDate to the aggregation specialDates.

attachFocus

Attaches event handler fnFunction to the focus event of this sap.ui.unified.calendar.MonthsRow.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.unified.calendar.MonthsRow itself.

Month focus changed

attachSelect

Attaches event handler fnFunction to the select event of this sap.ui.unified.calendar.MonthsRow.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.unified.calendar.MonthsRow itself.

Month selection changed

checkDateFocusable

Checks if a date is focusable in the current rendered output. This means that if it is not rendered, it is not focusable.

destroySelectedDates

Destroys all the selectedDates in the aggregation selectedDates.

destroySpecialDates

Destroys all the specialDates in the aggregation specialDates.

detachFocus

Detaches event handler fnFunction from the focus event of this sap.ui.unified.calendar.MonthsRow.

The passed function and listener object must match the ones used for event registration.

detachSelect

Detaches event handler fnFunction from the select event of this sap.ui.unified.calendar.MonthsRow.

The passed function and listener object must match the ones used for event registration.

displayDate

Displays the month of a given date without setting the focus

sap.ui.unified.calendar.MonthsRow.extend

Creates a new subclass of class sap.ui.unified.calendar.MonthsRow with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.core.Control.extend.

fireFocus

Fires event focus to attached listeners.

fireSelect

Fires event select to attached listeners.

getAriaLabelledBy

Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.

getDate

Gets current value of property date.

A date as JavaScript Date object. The month including this date is rendered and this date is focused initially (if no other focus is set). If the date property is not in the range startDate + months in the rendering phase, it is set to the startDate. So after setting the startDate the date should be set to be in the visible range.

getIntervalSelection

Gets current value of property intervalSelection.

If set, interval selection is allowed

Default value is false.

getLegend

ID of the element which is the current target of the association legend, or null.

sap.ui.unified.calendar.MonthsRow.getMetadata

Returns a metadata object for class sap.ui.unified.calendar.MonthsRow.

getMonths

Gets current value of property months.

Number of months displayed

Default value is 12.

getSelectedDates

Gets content of aggregation selectedDates.

Date ranges for selected dates. If singleSelection is set, only the first entry is used.

Note: Even if only one day is selected, the whole corresponding month is selected.

getShowHeader

Gets current value of property showHeader.

If set, a header with the years is shown to visualize what month belongs to what year.

Default value is false.

getSingleSelection

Gets current value of property singleSelection.

If set, only a single month or interval, if intervalSelection is enabled, can be selected

Note: Selection of multiple intervals is not supported in the current version.

Default value is true.

getSpecialDates

Gets content of aggregation specialDates.

Date ranges with type to visualize special months in the row. If one day is assigned to more than one type, only the first one will be used.

Note: Even if only one day is set as a special day, the whole corresponding month is displayed in this way.

getStartDate

Gets current value of property startDate.

Start date, as JavaScript Date object, of the row. The month of this date is the first month of the displayed row.

indexOfSelectedDate

Checks for the provided sap.ui.unified.DateRange in the aggregation selectedDates. and returns its index if found or -1 otherwise.

indexOfSpecialDate

Checks for the provided sap.ui.unified.DateTypeRange in the aggregation specialDates. and returns its index if found or -1 otherwise.

insertSelectedDate

Inserts a selectedDate into the aggregation selectedDates.

insertSpecialDate

Inserts a specialDate into the aggregation specialDates.

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAllSelectedDates

Removes all the controls from the aggregation selectedDates.

Additionally, it unregisters them from the hosting UIArea.

removeAllSpecialDates

Removes all the controls from the aggregation specialDates.

Additionally, it unregisters them from the hosting UIArea.

removeAriaLabelledBy

Removes an ariaLabelledBy from the association named ariaLabelledBy.

removeSelectedDate

Removes a selectedDate from the aggregation selectedDates.

removeSpecialDate

Removes a specialDate from the aggregation specialDates.

setIntervalSelection

Sets a new value for property intervalSelection.

If set, interval selection is allowed

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

setLegend

Sets the associated legend.

setMonths

Sets a new value for property months.

Number of months displayed

When called with a value of null or undefined, the default value of the property will be restored.

Default value is 12.

setShowHeader

Sets a new value for property showHeader.

If set, a header with the years is shown to visualize what month belongs to what year.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

setSingleSelection

Sets a new value for property singleSelection.

If set, only a single month or interval, if intervalSelection is enabled, can be selected

Note: Selection of multiple intervals is not supported in the current version.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

setStartDate

Sets a new value for property startDate.

Start date, as JavaScript Date object, of the row. The month of this date is the first month of the displayed row.

When called with a value of null or undefined, the default value of the property will be restored.

addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

Param Type DefaultValue Description
vAriaLabelledBy sap.ui.core.ID sap.ui.core.Control

The ariaLabelledBy to add; if empty, nothing is inserted

addSelectedDate

Adds some selectedDate to the aggregation selectedDates.

Param Type DefaultValue Description
oSelectedDate sap.ui.unified.DateRange

The selectedDate to add; if empty, nothing is inserted

addSpecialDate

Adds some specialDate to the aggregation specialDates.

Param Type DefaultValue Description
oSpecialDate sap.ui.unified.DateTypeRange

The specialDate to add; if empty, nothing is inserted

attachFocus

Attaches event handler fnFunction to the focus event of this sap.ui.unified.calendar.MonthsRow.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.unified.calendar.MonthsRow itself.

Month focus changed

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.unified.calendar.MonthsRow itself

attachSelect

Attaches event handler fnFunction to the select event of this sap.ui.unified.calendar.MonthsRow.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.unified.calendar.MonthsRow itself.

Month selection changed

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.unified.calendar.MonthsRow itself

checkDateFocusable

Checks if a date is focusable in the current rendered output. This means that if it is not rendered, it is not focusable.

Param Type DefaultValue Description
oDateTime object

JavaScript Date object for focused date.

destroySelectedDates

Destroys all the selectedDates in the aggregation selectedDates.

destroySpecialDates

Destroys all the specialDates in the aggregation specialDates.

detachFocus

Detaches event handler fnFunction from the focus event of this sap.ui.unified.calendar.MonthsRow.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

detachSelect

Detaches event handler fnFunction from the select event of this sap.ui.unified.calendar.MonthsRow.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

displayDate

Displays the month of a given date without setting the focus

Param Type DefaultValue Description
oDate object

JavaScript Date object for focused date.

sap.ui.unified.calendar.MonthsRow.extend

Creates a new subclass of class sap.ui.unified.calendar.MonthsRow with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.core.Control.extend.

Param Type DefaultValue Description
sClassName string

Name of the class being created

oClassInfo object

Object literal with information about the class

FNMetaImpl function

Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class

fireFocus

Fires event focus to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

date object

First date, as JavaScript Date object, of the month that is focused.

notVisible boolean

If set, the focused date is not rendered yet. (This happens by navigating out of the visible area.)

fireSelect

Fires event select to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

getAriaLabelledBy

Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.

getDate

Gets current value of property date.

A date as JavaScript Date object. The month including this date is rendered and this date is focused initially (if no other focus is set). If the date property is not in the range startDate + months in the rendering phase, it is set to the startDate. So after setting the startDate the date should be set to be in the visible range.

getIntervalSelection

Gets current value of property intervalSelection.

If set, interval selection is allowed

Default value is false.

getLegend

ID of the element which is the current target of the association legend, or null.

sap.ui.unified.calendar.MonthsRow.getMetadata

Returns a metadata object for class sap.ui.unified.calendar.MonthsRow.

getMonths

Gets current value of property months.

Number of months displayed

Default value is 12.

getSelectedDates

Gets content of aggregation selectedDates.

Date ranges for selected dates. If singleSelection is set, only the first entry is used.

Note: Even if only one day is selected, the whole corresponding month is selected.

getShowHeader

Gets current value of property showHeader.

If set, a header with the years is shown to visualize what month belongs to what year.

Default value is false.

getSingleSelection

Gets current value of property singleSelection.

If set, only a single month or interval, if intervalSelection is enabled, can be selected

Note: Selection of multiple intervals is not supported in the current version.

Default value is true.

getSpecialDates

Gets content of aggregation specialDates.

Date ranges with type to visualize special months in the row. If one day is assigned to more than one type, only the first one will be used.

Note: Even if only one day is set as a special day, the whole corresponding month is displayed in this way.

getStartDate

Gets current value of property startDate.

Start date, as JavaScript Date object, of the row. The month of this date is the first month of the displayed row.

indexOfSelectedDate

Checks for the provided sap.ui.unified.DateRange in the aggregation selectedDates. and returns its index if found or -1 otherwise.

Param Type DefaultValue Description
oSelectedDate sap.ui.unified.DateRange

The selectedDate whose index is looked for

indexOfSpecialDate

Checks for the provided sap.ui.unified.DateTypeRange in the aggregation specialDates. and returns its index if found or -1 otherwise.

Param Type DefaultValue Description
oSpecialDate sap.ui.unified.DateTypeRange

The specialDate whose index is looked for

insertSelectedDate

Inserts a selectedDate into the aggregation selectedDates.

Param Type DefaultValue Description
oSelectedDate sap.ui.unified.DateRange

The selectedDate to insert; if empty, nothing is inserted

iIndex int

The 0-based index the selectedDate should be inserted at; for a negative value of iIndex, the selectedDate is inserted at position 0; for a value greater than the current size of the aggregation, the selectedDate is inserted at the last position

insertSpecialDate

Inserts a specialDate into the aggregation specialDates.

Param Type DefaultValue Description
oSpecialDate sap.ui.unified.DateTypeRange

The specialDate to insert; if empty, nothing is inserted

iIndex int

The 0-based index the specialDate should be inserted at; for a negative value of iIndex, the specialDate is inserted at position 0; for a value greater than the current size of the aggregation, the specialDate is inserted at the last position

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAllSelectedDates

Removes all the controls from the aggregation selectedDates.

Additionally, it unregisters them from the hosting UIArea.

removeAllSpecialDates

Removes all the controls from the aggregation specialDates.

Additionally, it unregisters them from the hosting UIArea.

removeAriaLabelledBy

Removes an ariaLabelledBy from the association named ariaLabelledBy.

Param Type DefaultValue Description
vAriaLabelledBy int sap.ui.core.ID sap.ui.core.Control

The ariaLabelledBy to be removed or its index or ID

removeSelectedDate

Removes a selectedDate from the aggregation selectedDates.

Param Type DefaultValue Description
vSelectedDate int string sap.ui.unified.DateRange

The selectedDate to remove or its index or id

removeSpecialDate

Removes a specialDate from the aggregation specialDates.

Param Type DefaultValue Description
vSpecialDate int string sap.ui.unified.DateTypeRange

The specialDate to remove or its index or id

setIntervalSelection

Sets a new value for property intervalSelection.

If set, interval selection is allowed

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Param Type DefaultValue Description
bIntervalSelection boolean false

New value for property intervalSelection

setLegend

Sets the associated legend.

Param Type DefaultValue Description
oLegend sap.ui.core.ID sap.ui.unified.CalendarLegend

ID of an element which becomes the new target of this legend association; alternatively, an element instance may be given

setMonths

Sets a new value for property months.

Number of months displayed

When called with a value of null or undefined, the default value of the property will be restored.

Default value is 12.

Param Type DefaultValue Description
iMonths int 12

New value for property months

setShowHeader

Sets a new value for property showHeader.

If set, a header with the years is shown to visualize what month belongs to what year.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Param Type DefaultValue Description
bShowHeader boolean false

New value for property showHeader

setSingleSelection

Sets a new value for property singleSelection.

If set, only a single month or interval, if intervalSelection is enabled, can be selected

Note: Selection of multiple intervals is not supported in the current version.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Param Type DefaultValue Description
bSingleSelection boolean true

New value for property singleSelection

setStartDate

Sets a new value for property startDate.

Start date, as JavaScript Date object, of the row. The month of this date is the first month of the displayed row.

When called with a value of null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
oStartDate object

New value for property startDate