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