Add calendar widget help

app/ui/src/main/java/de/mm20/launcher2/ui/launcher/sheets/ConfigureWidgetSheet.kt

@@ -5,7 +5,10 @@ import android.appwidget.AppWidgetHost
 import android.appwidget.AppWidgetManager
 import android.appwidget.AppWidgetProviderInfo
 import android.content.Intent
+import android.net.Uri
 import androidx.appcompat.app.AppCompatActivity
+import androidx.browser.customtabs.CustomTabColorSchemeParams
+import androidx.browser.customtabs.CustomTabsIntent
 import androidx.compose.foundation.background
 import androidx.compose.foundation.clickable
 import androidx.compose.foundation.gestures.Orientation
@@ -27,6 +30,7 @@ import androidx.compose.foundation.verticalScroll
 import androidx.compose.material.icons.Icons
 import androidx.compose.material.icons.rounded.Build
 import androidx.compose.material.icons.rounded.Error
+import androidx.compose.material.icons.rounded.HelpOutline
 import androidx.compose.material.icons.rounded.OpenInNew
 import androidx.compose.material.icons.rounded.UnfoldMore
 import androidx.compose.material3.ButtonDefaults
@@ -52,6 +56,7 @@ import androidx.compose.runtime.setValue
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.draw.clip
+import androidx.compose.ui.graphics.toArgb
 import androidx.compose.ui.platform.LocalContext
 import androidx.compose.ui.platform.LocalDensity
 import androidx.compose.ui.platform.LocalLifecycleOwner
@@ -565,6 +570,35 @@ fun ColumnScope.ConfigureCalendarWidget(
             text = stringResource(R.string.widget_config_calendar_no_calendars)
         )
     }
+    if (hasPermission) {
+        val colorScheme = MaterialTheme.colorScheme
+        TextButton(
+            modifier = Modifier
+                .padding(top = 8.dp)
+                .align(Alignment.CenterHorizontally),
+            contentPadding = ButtonDefaults.TextButtonWithIconContentPadding,
+            onClick = {
+                CustomTabsIntent.Builder()
+                    .setDefaultColorSchemeParams(
+                        CustomTabColorSchemeParams.Builder()
+                            .setToolbarColor(colorScheme.primaryContainer.toArgb())
+                            .setSecondaryToolbarColor(colorScheme.secondaryContainer.toArgb())
+                            .build()
+                    )
+                    .build().launchUrl(
+                        context,
+                        Uri.parse("https://kvaesitso.mm20.de/docs/user-guide/widgets/calendar-widget#my-calendars-dont-show-up")
+                    )
+            }) {
+            Icon(
+                modifier = Modifier
+                    .padding(end = ButtonDefaults.IconSpacing)
+                    .requiredSize(ButtonDefaults.IconSize),
+                imageVector = Icons.Rounded.HelpOutline, contentDescription = null
+            )
+            Text(stringResource(R.string.widget_config_calendar_missing_calendars_hint))
+        }
+    }
 }
 
 @Composable

core/i18n/src/main/res/values/strings.xml

@@ -394,6 +394,7 @@
     <string name="missing_permission_calendar_search_settings">Calendar permission is required to search calendar</string>
     <!-- Missing calendar permission in calendar widget settings screen -->
     <string name="missing_permission_calendar_widget_settings">This widget requires calendar permission</string>
+    <string name="widget_config_calendar_missing_calendars_hint">Can\'t find your calendars?</string>
     <!-- Missing permission app shortcuts permission in search settings screen. %1$s: app name -->
     <string name="missing_permission_appshortcuts_search_settings">%1$s must be set as default home app to search app shortcuts</string>
     <!-- Missing file permission in search settings screen -->

docs/docs/user-guide/widgets/calendar-widget.md

@@ -1,5 +0,0 @@
-# Calendar Widget
-
-Display calendar events and appointments for the next seven days.
-
-Calendar apps need to use the Android calendar provider APIs to store their calendar data in order to make them accessible for this widget. Some calendar apps (notably Proton calendar) do not do this and therefore do not work with this widget.

docs/docs/user-guide/widgets/calendar-widget.mdx

@@ -0,0 +1,65 @@
+import TuneRoundedIcon from '@mui/icons-material/TuneRounded'
+
+# Calendar Widget
+
+Display calendar events and appointments for the next seven days. In the widget settings, you can
+choose which calendars to display: Tap 'Edit widgets', then tap the <TuneRoundedIcon /> icon for the
+calendar widget. There is also an option to hide all-day events.
+
+## My calendars don't show up!
+
+Calendar apps need to use the Android calendar provider APIs to store their calendar data in order
+to make them accessible for other apps (like this widget).
+
+The calendar provider framework consists of two parts:
+- calendar providers that serve as a backend to store and sync calendar data
+- calendar apps that provide a user interface to view and modify calendar data
+
+Both parts can be provided by the same app, or they can be provided by different apps. Calendar apps
+can interact with multiple calendar providers, and calendar providers can be used by multiple calendar
+apps. This system makes it possible that you can, for example, use the Google Calendar app to read
+and modify your Outlook calendar.
+
+If your calendar doesn't show up, it is
+likely that your calendar app doesn't participate in this system. For some apps, there are solutions
+or workarounds:
+
+### Outlook
+
+Outlook doesn't sync its calendar data with the Android calendar provider by default. To enable it,
+open the Outlook app, and navigate to its settings. Tap on your account, then enable 'Sync calendar'.
+
+### Proton Calendar
+
+Proton Calendar does not support syncing with the Android calendar provider. Unfortunately, they
+see this as a privacy feature, so it is unlikely that this will change in the future. For that reason,
+this widget cannot display Proton Calendar events. As a workaround, if you are on a paid Proton Calendar
+plan, you can [share your calendar via link](https://proton.me/support/share-calendar-via-link) and
+then sync that calendar link using [ICSx⁵](https://f-droid.org/de/packages/at.bitfire.icsdroid/). However,
+this solution has some drawbacks:
+- The synced calendar is read-only, if you need to make changes, you need to do that in the Proton Calendar app
+- The calendar widget will not open the event in the Proton Calendar app, but in the default calendar app
+- You effectively bypass Proton's privacy features
+
+### Simple Calendar
+
+Simple calendar uses its own internal calendar storage by default. These calendars are not accessible
+to other apps. Simple calendar can also read and write calendars to the Android calendar provider.
+This feature mainly intended to allow Simple Calendar users to use their (Google, Outlook, etc.)
+calendars in Simple Calendar. Unfortunately, Simple Calendar cannot act as a calendar provider, so
+you need to rely on another calendar provider app.
+
+If you want an offline solution, you
+can use [Etar](https://f-droid.org/de/packages/ws.xsoh.etar/) (which is a full-blown calendar app by
+its own, but it has the capability to create offline calendars) or
+[Offline Calendar](https://f-droid.org/de/packages/org.sufficientlysecure.localcalendar/) (which is
+just a calendar provider but no longer maintained). It is also possible that your device's default
+calendar app has this feature built-in, so best check that first.
+
+After you have created an offline calendar, you can sync it with Simple Calendar by opening the
+Simple Calendar settings, and enabling 'CalDAV sync'. There you can select your offline calendar.
+
+To migrate your existing Simple Calendar calendars to the new calendar provider, select
+'Export events to an .ics file', then clear them from Simple Calendar (settings > Delete all events and tasks)
+and reimport them ('Import events from an .ics file'). Make sure to select the right calendar
+and that 'Ignore event types in the file, always use the default one' is ticked.