Calendar Event Linker

A Flutter plugin that provides seamless integration with native device calendars on both Android and iOS platforms. Add and delete calendar events directly from your Flutter application.

Features

• ✅ Add events to native device calendar
• ✅ Delete events from native device calendar
• ✅ Cross-platform support (Android & iOS)
• ✅ Timezone support
• ✅ Permission handling
• ✅ Error handling and validation

Getting Started

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  calendar_event_linker: ^1.0.0

Then run:

flutter pub get

Platform Setup

Android

Add the following permissions to your android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.READ_CALENDAR" />
<uses-permission android:name="android.permission.WRITE_CALENDAR" />

iOS

Add the following to your ios/Runner/Info.plist:

<key>NSCalendarsUsageDescription</key>
<string>This app needs access to calendar to add and manage events.</string>

Usage

Import the plugin

import 'package:calendar_event_linker/calendar_event_linker.dart';

Create an instance

final calendarEventLinker = CalendarEventLinker();

Add an event to calendar

try {
  final eventId = await calendarEventLinker.addEventToCalendar(
    title: 'Meeting with Client',
    description: 'Discuss project requirements and timeline',
    startTime: DateTime(2024, 1, 15, 10, 0),
    endTime: DateTime(2024, 1, 15, 11, 0),
    timezone: 'America/New_York', // Optional, defaults to device timezone
  );

  if (eventId != null) {
    print('Event added successfully with ID: $eventId');
  } else {
    print('Failed to add event');
  }
} catch (e) {
  print('Error adding event: $e');
}

Delete an event from calendar

try {
  final success = await calendarEventLinker.deleteEventFromCalendar('event_id_here');

  if (success) {
    print('Event deleted successfully');
  } else {
    print('Failed to delete event');
  }
} catch (e) {
  print('Error deleting event: $e');
}

API Reference

Methods

addEventToCalendar

Adds an event to the native device calendar.

Parameters:

• title (String, required): The title of the event
• description (String, required): The description of the event
• startTime (DateTime, required): The start time of the event
• endTime (DateTime, required): The end time of the event
• timezone (String, optional): The timezone for the event (defaults to device timezone)

Returns: Future<String?> - Returns the event ID if successful, null otherwise

deleteEventFromCalendar

Deletes an event from the native device calendar.

Parameters:

• eventId (String, required): The ID of the event to delete

Returns: Future<bool> - Returns true if successful, false otherwise

Permissions

This plugin requires calendar permissions on both platforms:

• Android: READ_CALENDAR and WRITE_CALENDAR
• iOS: NSCalendarsUsageDescription

The plugin will automatically request these permissions when needed. Make sure to handle permission denied scenarios in your app.

Error Handling

The plugin provides comprehensive error handling:

try {
  final eventId = await calendarEventLinker.addEventToCalendar(
    title: 'My Event',
    description: 'Event description',
    startTime: DateTime.now(),
    endTime: DateTime.now().add(Duration(hours: 1)),
  );
} on PlatformException catch (e) {
  switch (e.code) {
    case 'CALENDAR_ACCESS_DENIED':
      // Handle permission denied
      break;
    case 'INVALID_ARGUMENTS':
      // Handle invalid arguments
      break;
    case 'EVENT_SAVE_ERROR':
      // Handle save error
      break;
    default:
      // Handle other errors
      break;
  }
}

Platform Differences

Android

• Uses CalendarContract API
• Requires explicit calendar and timezone handling
• Returns numeric event ID

iOS

• Uses EventKit framework
• Handles timezone automatically
• Returns string event identifier

Example App

Check out the example directory for a complete working example demonstrating all features of the plugin.

Troubleshooting

Common Issues

1. Permission Denied: Ensure you've added the required permissions to your platform-specific configuration files.

2. Event Not Found: When deleting events, make sure the event ID is valid and the event exists.

3. Invalid Date Format: Ensure your DateTime objects are properly formatted and within valid ranges.

4. No Calendar Found (Android): This can happen if the device has no calendars set up. The plugin will use the first available calendar.

Debug Tips

• Enable debug logging to see detailed error messages
• Check device calendar settings and permissions
• Verify that the calendar app is properly configured on the device

Contributing

Contributions are welcome! Please read our Contributing Guide for details on how to submit pull requests, report issues, and contribute to the project.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

If you encounter any issues or have questions:

1. Check the documentation
2. Search existing issues
3. Create a new issue

Changelog

See CHANGELOG.md for a detailed history of changes.

---

Made with ❤️ by Akshay