Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added SwiftUI Widgets file, what widgets are and how to create one #2123

Merged
merged 12 commits into from
Aug 3, 2023
58 changes: 58 additions & 0 deletions content/swiftui/concepts/widgets/widgets.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
---
Title: 'SwiftUI Widgets'
JaseTheJap marked this conversation as resolved.
Show resolved Hide resolved
Description: 'Building user interfaces across Apple platforms.'
Subjects:
- 'iOS Development'
Tags:
- 'SwiftUI'
- 'User Interface'
- 'iOS'
CatalogContent:
- 'paths/iOS Development'
JaseTheJap marked this conversation as resolved.
Show resolved Hide resolved
- 'Learn SwiftUI'
JaseTheJap marked this conversation as resolved.
Show resolved Hide resolved
---

# SwiftUI Widgets
yangc95 marked this conversation as resolved.
Show resolved Hide resolved

## What are SwiftUI Widgets?
yangc95 marked this conversation as resolved.
Show resolved Hide resolved
**SwiftUI Widgets** are interactive components that provide users with glanceable information or quick access to app functionality directly from the home screen of their device. They are mini-applications that can display dynamic content, such as weather updates, calendar events, or news headlines. SwiftUI widgets can be created using the WidgetKit framework and are highly customizable, allowing developers to design visually appealing and personalized experiences for users without requiring them to open the full app.
JaseTheJap marked this conversation as resolved.
Show resolved Hide resolved

## To create a widget using the Widget Extension template in Xcode, follow these steps:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
## To create a widget using the Widget Extension template in Xcode, follow these steps:
## Xcode Widget Extension Template

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section is getting into the "tutorial realm" which we would like to differentiate Docs from. Rather than set-up, I think it would be more helpful to perhaps explain in this section how Xcode offers developers a template to use which "will generate the necessary files and folders for the widget extension, including a default SwiftUI widget view and a widget extension entry point."

You can also go into other info about this template as you've done here after the steps.


1. Open Xcode and create a new project or open an existing project.
2. In the project navigator, right-click on the project's root folder.
3. Select "New File" from the contextual menu.
4. In the template selection dialog, search for "Widget Extension" or navigate to "App Extension" -> "Widget Extension."
5. Click "Next" to proceed.
6. Provide a name for your widget extension and choose the target app.
7. Select the desired options such as widget size and intent configuration (if applicable).
8. Click "Finish" to create the widget extension.

Xcode will generate the necessary files and folders for the widget extension, including a default SwiftUI widget view and a widget extension entry point.

Next, you can customize your widget by modifying the SwiftUI view and implementing the widget's data provider.

In the generated widget view file (e.g., YourWidget.swift), you can modify the appearance and content of the widget by editing the body property. Add SwiftUI components, apply styles, and display dynamic data to create your desired widget UI.

In the generated widget extension entry point file (e.g., YourWidgetExtension.swift), you'll find a struct conforming to Widget protocol. You can modify this struct to configure your widget's behavior, supported families, and timeline provider.

After customizing the widget view and the widget extension, you can build and run your app to see the widget in the widget gallery.

To add your widget to the home screen, long-press on the home screen, tap the "+" button, search for your app's name, and select your widget to add it to the desired location.

Remember to adjust the code and configurations as per your project's requirements to create a fully functional and visually appealing SwiftUI widget.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Nitpick] Pronouns are not allowed to be used according to the style guide, so consider revising.

Suggested change
In the generated widget view file (e.g., YourWidget.swift), you can modify the appearance and content of the widget by editing the body property. Add SwiftUI components, apply styles, and display dynamic data to create your desired widget UI.
In the generated widget extension entry point file (e.g., YourWidgetExtension.swift), you'll find a struct conforming to Widget protocol. You can modify this struct to configure your widget's behavior, supported families, and timeline provider.
After customizing the widget view and the widget extension, you can build and run your app to see the widget in the widget gallery.
To add your widget to the home screen, long-press on the home screen, tap the "+" button, search for your app's name, and select your widget to add it to the desired location.
Remember to adjust the code and configurations as per your project's requirements to create a fully functional and visually appealing SwiftUI widget.
In the generated widget view file (e.g., YourWidget.swift), you can modify the appearance and content of the widget by editing the body property. Add SwiftUI components, apply styles, and display dynamic data to create your desired widget UI.
In the generated widget extension entry point file (e.g., YourWidgetExtension.swift), you'll find a struct conforming to Widget protocol. You can modify this struct to configure your widget's behavior, supported families, and timeline provider.
After customizing the widget view and the widget extension, you can build and run your app to see the widget in the widget gallery.
To add your widget to the home screen, long-press on the home screen, tap the "+" button, search for your app's name, and select your widget to add it to the desired location.
Remember to adjust the code and configurations as per your project's requirements to create a fully functional and visually appealing SwiftUI widget.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's remove pronouns here (I, we, you, etc.)


# WidgetKit

## What is WidgetKit?
JaseTheJap marked this conversation as resolved.
Show resolved Hide resolved
WidgetKit is a framework introduced by Apple that allows developers to create interactive and dynamic widgets for iOS, macOS, and watchOS. Widgets provide users with quick access to information or app functionality directly from the home screen or Today View.

With WidgetKit, developers can design and build widgets using SwiftUI, leveraging its declarative syntax and powerful UI components. Widgets can display various types of information such as weather updates, calendar events, news headlines, or custom data from the app.

WidgetKit includes features like the TimelineProvider protocol, which enables widgets to provide timely updates and display different content based on the current context. It also offers support for widget families, allowing developers to create widgets of different sizes and layouts, adapting to the available space on the user's device.

Widgets created with WidgetKit can take advantage of system intelligence to manage resources efficiently, ensuring that updates occur at appropriate times to conserve battery life. Additionally, WidgetKit provides customization options for users, enabling them to personalize and configure widgets based on their preferences.

By utilizing WidgetKit, developers can enhance the user experience by providing at-a-glance information and quick interactions without requiring users to open the full app.