QVRWeekView
About
QVRWeekView is a work in progress framework that contains a week/day view that allows you to display, add and remove events.
Features
- Horizontal and vertical scrolling
- Infinite horizontal scrolling
- Zooming
- Colour, size and font customization features
- Day and hour label font resizing
- Dynamic event adding and removing
- Event tap, long press and event request callbacks
- Number of visible days customizable
Example
To run the example project, clone the repo, and run pod install from the Example directory first.
Most useful example code can be found in Example > QVRWeekView > CalendarViewController or StartViewController
Requirements
This pod requires a minimum deployment target of iOS 9.0.
Installation
QVRWeekView is available through CocoaPods. To install it, simply add the following line to your Podfile:
pod "QVRWeekView"Usage
Setup
Once the framework is installed, there are two ways you can incorporate the WeekView into your project:
1. Programatically
To add the WeekView programatically, simply import QVRWeekView into your code by adding:
import QVRWeekViewat the top of your source file containing your view controller. Then insert the WeekView into your view controller by adding:
let weekView = WeekView(frame: self.view.frame)
self.view.addSubview(weekView)into either your viewDidLoad or viewWillAppear method.
2. Via the storyboard
To add the WeekView via the storyboard, simply add a View onto your View Controller and resize it or add constraints. Then go to the identity inspector of your view and select the Class to be WeekView and the module to be QVRWeekView (See image).
Then you should be all set!
Working with WeekView
WeekView Delegate
WeekView has a delegate called WeekViewDelegate. For now this delegate contains only three functions:
| Function | Parameters | Behaviour | Recommended use |
|---|---|---|---|
| didLongPressDayView | weekView:WeekView, date:Date |
Called when a dayView column is long pressed. The passed date contains which time point was pressed |
Use this to trigger the creation of an event |
| didTapEvent | weekView:WeekView, eventId:Int |
Called when an event is tapped. eventId of the tapped event is passed |
Use this to prompt event editing or removal |
| eventLoadRequest | weekView:WeekView, startDate:Date , endDate:Date |
Called when events are ready to be loaded. startDate and endDate indicate (inclusively) between which two dates events are required. |
Use this to load in stored events |
| activeDayChanged | weekView:WeekView, date: Date |
Called when the current leftmost day changes. | Use this to keep track of current active day |
| didEndZooming | weekView:WeekView, scale: Double |
Called when zooming stops, the scale is the current zoomScale | Use this to persist the zoom scale of the WeekView |
| didEndVerticalScrolling | weekView:WeekView, top: Double, bottom: Double |
Called when vertical scrolling stops. The top an bottom values are percentages values of how far down the screen is. | Use this to persist vertical position of the WeekView |
WeekView Public Functions
| Function | Parameters | Behaviour |
|---|---|---|
| updateTimeDisplayed | \ |
Updates the time displayed by the hour indicator |
| showDay | date:Date |
Scrolls the week view to the day passed by date |
| showToday | \ |
Scrolls the week view to today |
| loadEvents | eventsData:[EventData] |
Loads, processes and displays the events provided by the eventsData array of EventData1 objects. Passing an empty array removes all visible events. |
| redrawEvents | Triggers a setNeedsLayout on all DayViewCells and will trigger a redrawing of all events |
WeekView Public Properties
| Property | Type | Description |
|---|---|---|
| allVisibleEvents | [EventData] |
An array of EventData of the events currently visible on screen |
| visibleDayDateRange | ClosedRange<DayDate> |
A ClosedRange of DayDates of the day columns which are currently visible on screen |
| delegate | WeekViewDelegate? |
The delegate of this WeekView |
EventData1
EventData is the main object used to communicate events between the WeekView and your code. EventData can be overriden.
| Variable/Function | Purpose |
|---|---|
id:String |
A unique identifier for this event |
title:String |
A title that will be displayed for this event |
locating:String |
The "location" of this event (or any other data you wish to be displayed alongside the title in an event) |
startDate:Date |
The start date for this event |
endDate:Date |
The end date for this event |
color:UIColor |
The main color for this event |
allDay:Bool |
Indicates if this event is an all day event, all day events are displayed along the top bar |
configureGradient(CAGradientLayer?) -> Void |
Use to configure a gradient that will be used to render your event instead of just a solid color |
Saving and Persisting Events
Events can be stored in Core Data (the following guide assumes some basic knowledge of Core Data):
- Create a new Core Data model if you don't have one already. Create a new Entity in this model.
- Add a new Attribute of type
Transformableto the new Entity. - Select the new Attribute and make sure its
CustomClassis set to (this can be changed in the right-hand side menu):EventDataArrayif you want to store an array of eventsEventDataif you want to store a single event
- If you are getting Undeclared Type warnings, you may need to add
@import QVRWeekViewto your[ProjectName]-Bridging-Header.hfile. - You can now use the new Core Data Entity to persist
EventDataobjects.
The EventDataArray class has a single variable: eventsData: [EventData] and is simply used as a proxy to store an array of events.
A detailed example can be found in the example Project folder /Example. A more detailed guide can be found here.
Customizing WeekView
Below is a table of all customizable properties of the WeekView
| Property | Description | Default |
|---|---|---|
mainBackgroundColor:UIColor |
The background color of the WeekView. | dark grey: #cacaca |
defaultTopBarHeight:CGFloat |
The default height of the top bar containing the day labels. | 35 |
topBarColor:UIColor |
The color of the top bar containing the day labels. | grey: #dcdcdc |
sideBarWidth:CGFloat |
The width of the sidebar containing the hour labels. | 25 |
sideBarColor:UIColor |
The color of the sidebar containing the hour labels. | dark grey: #cacaca |
dayLabelDefaultFont:UIFont |
The default font the the day labels. | boldSystemFont size: 14 |
dayLabelTextColor:UIColor |
The text color of the day labels. | black: #000 |
dayLabelTodayTextColor:UIColor |
The text color of the today day label. | dark blue: #14426f |
dayLabelMinimumFontSize:CGFloat |
The minimum day label font size. Used during automatic resizing. | 8 |
dayLabelShortDateFormat:String |
The date format of the day label when there is not enough space to display the normal date format. Date formats can be found here. | d MMM |
dayLabelNormalDateFormat:String |
The date format of the day label when there is not enough space to display the long date format. Date formats can be found here. | E d MMM |
dayLabelLongDateFormat:String |
The longest date format of the day label, only shown when there is enough space to display it. Date formats can be found here. | E d MMM y |
dayLabelDateLocale:Locale |
Locale used by the day label formatter. Locales can be found here | NSLocale.current |
hourLabelFont:UIFont |
The font the the hour labels. | boldSystemFont size: 12 |
hourLabelTextColor:UIColor |
The text color of the hour labels. | black #000 |
hourLabelMinimumFontSize:CGFloat |
The minimum day label font size. Used during automatic resizing. | 6 |
hourLabelDateFormat:String |
The date format used to display the hours in the side bar. | HH |
allDayEventHeight:CGFloat |
The height of an all day event. | 40 |
allDayEventVerticalSpacing:CGFloat |
The vertical spacing above and below an all day event. | 5 |
allDayEventsSpreadOnX:Bool |
When enabled, all day events are displayed next to each other, instead of above and below each other. | true |
autoConvertAllDayEvents:Bool |
When enabled, events that cross multiple days will be converted to all day events. | true |
visibleDaysInPortraitMode:Int |
The amount of day columns visible in portrait mode. | 2 |
visibleDaysInLandscapeMode:Int |
The amount day columns visible in landscape mode. | 7 |
eventLabelFont:UIFont |
The font of the text inside events. | boldSystemFont size: 12 |
eventLabelInfoFont:UIFont |
The info font of the text inside events. | boldFont size: 12 |
eventLabelTextColor:UIColor |
The color of the text inside events. | white #fff |
eventLabelHorizontalTextPadding:CGFloat |
Horizontal padding of the text within event labels. | 2 |
eventLabelVerticalTextPadding:CGFloat |
Vertical padding of the text within event labels. | 2 |
eventStyleCallback:(CALayer, EventData?) -> Void |
Use this callback to customise an Event layer any way you want. The EventData will be nil if it is the Preview Event layer that is being rendered. Example usage in CalendarViewController. | nil |
previewEventText:String |
The text shown inside the preview event. | New Event |
previewEventColor:UIColor |
The color of the preview event. | random color |
previewEventHeightInHours:Double |
Height of the preview event in hours. | 2.0 |
previewEventPrecisionInMinutes:Double |
The number of minutes the preview event will snap to. Ex: 15.0 will snap preview event to nearest 15 minutes. | 15.0 |
showPreviewOnLongPress:Bool |
When enabled a preview event will be displayed on a long press. | true |
defaultDayViewColor:UIColor |
The default color of a day column. | light grey #f8f8f8 |
weekendDayViewColor:UIColor |
The color of a weekend day column. | grey #eaeaea |
passedDayViewColor:UIColor |
The color of a day column that is in the past. | grey #f0f0f0 |
passedWeekendDayViewColor:UIColor |
The color of a weekend day column that is in the past. | grey #e4e4e4 |
todayViewColor:UIColor |
The color of today's day column. | light grey #f8f8f8 |
showTodayTimeOverlay:Bool |
Show or hide "current time" overlay in the today day view cell. | true |
dayViewCellInitialHeight:CGFloat |
Height for the day columns. This is the initial height for zoom scale = 1.0. | 1400 |
dayViewHourIndicatorColor:UIColor |
Color of the current hour indicator. | very dark grey #5a5a5a |
dayViewHourIndicatorThickness:CGFloat |
Thickness (or height) of the current hour indicator. | 3 |
dayViewMainSeparatorColor:UIColor |
Color of the main hour separators in the day view cells. Main separators are full lines and not dashed. | dark grey: #cacaca |
dayViewMainSeparatorThickness:CGFloat |
Thickness of the main hour separators in the day view cells. Main separators are full lines and not dashed. | 1 |
dayViewDashedSeparatorColor:UIColor |
Color of the dashed/dotted hour separators in the day view cells. | dark grey: #cacaca |
dayViewDashedSeparatorThickness:CGFloat |
Thickness of the dashed/dotted hour separators in the day view cells. | 1 |
dayViewDashedSeparatorPattern:[NSNumber] |
Sets the pattern for the dashed/dotted hour separators. Requires an array of NSNumbers. Example 1: (10, 5) will set a pattern of 10 points drawn, 5 points empty, repeated. Example 2: (3, 4, 9, 2) will set a pattern of 4 points drawn, 4 points empty, 9 points drawn, 2 points empty, repeated. See Apple API for additional information on pattern drawing. | [3, 1] |
portraitDayViewSideSpacing:CGFloat |
Amount of spacing in between day columns when in portrait mode. | 5 |
landscapeDayViewSideSpacing:CGFloat |
Amount of spacing in between day columns when in landscape mode. | 1 |
portraitDayViewVerticalSpacing:CGFloat |
Amount of spacing above and below day columns when in portrait mode. | 15 |
landscapeDayViewVerticalSpacing:CGFloat |
Amount of spacing above and below day columns when in landscape mode. | 10 |
minimumZoomScale:CGFloat |
The minimum zoom scale to which the weekview can be zoomed. Ex. 0.5 means that the weekview can be zoomed to half the original given dayViewCellHeight. | 0.75 |
currentZoomScale:CGFloat |
The current zoom scale to which the weekview will be zoomed. Ex. 0.5 means that the weekview will be zoomed to half the original given dayViewCellHeight. | 1.0 |
maximumZoomScale:CGFloat |
The maximum zoom scale to which the weekview can be zoomed. Ex. 2.0 means that the weekview can be zoomed to double the original given dayViewCellHeight. | 3.0 |
velocityOffsetMultiplier:CGFloat |
Sensitivity for horizontal scrolling. A higher number will multiply input velocity more and thus result in more cells being skipped when scrolling. | 0.75 |
horizontalScrolling:HorizontalScrolling |
Used to determine horizontal scrolling behaviour. .infinite is infinite scrolling, .finite(number, startDate) is finite scrolling for a given number of days from the starting date. |
.infinite |
How it works
The main WeekView view is a subclass of UIView. The view layout is retrieved from the WeekView xib file. WeekView contains a top and side bar sub view. The side bar contains an HourSideBarView which displays the hours. WeekView also contains a DayScrollView (UIScrollView subclass) which controls vertical scrolling and also delegates and contains a DayCollectionView (UICollectionView subclass) which controls the horizontal scrolling. DayCollectionView cells are DayViewCells, whose view is generated programtically (due to inefficiencies caused by auto-layout).
WeekView handles all top level operations such as pinch gestures and orientation change. Scrolling of the top and side bar is handled by a function inside of WeekView which is called by the DayScrollView when scrolling. Top bar day labels are generated, displayed and discarded simulaneously with DayCollectionView cells by the WeekView.
Upcoming features
- Ability to add and remove events
- Event color customization
- Extra customization features
- Improved UI features
- Increased event processing efficiency
- Add scroll to all day events
Author
Reinert Lemmens, [email protected]
License
QVRWeekView is available under the MIT license. See the LICENSE file for more info.