Warning, /plasma/plasma-welcome/README.md is written in an unsupported language. File is not indexed.
0001 <!-- 0002 SPDX-License-Identifier: CC0-1.0 0003 SPDX-FileCopyrightText: 2022-Nate Graham <nate@kde.org> 0004 --> 0005 0006 # Plasma Welcome App 0007 Friendly onboarding wizard for Plasma 0008 0009 Welcome Center is the perfect introduction to KDE Plasma! It can help you learn how to connect to the internet, install apps, customize the system, and more! 0010 0011 There are four mutually exclusive usage modes: 0012 - Run the app normally and it will show a welcome/onboarding wizard. 0013 - Run the app with the `--post-update` argument to show a post-update message. 0014 - Run the app with the `--post-update-beta` argument to show a post-update message for beta releases. 0015 - Run the app with the `--live-environment` argument to show a reduced wizard with the live installer page and no settings pages. 0016 0017 ## Screenshots 0018 | Welcome to KDE Plasma! | Managing Software | Getting Involved | 0019 | --- | --- | --- | 0020 | ![Welcome to KDE Plasma!](https://cdn.kde.org/screenshots/plasma-welcome/plasma-welcome-page-1.png) | ![Managing Software](https://cdn.kde.org/screenshots/plasma-welcome/plasma-welcome-page-2.png) | ![Getting Involved](https://cdn.kde.org/screenshots/plasma-welcome/plasma-welcome-page-6.png) | 0021 0022 # For live distributions 0023 When Welcome Center is ran in a live environment, it can show a reduced wizard with a page welcoming the user to the disibution and without any settings pages. 0024 0025 To ensure that Welcome Center's launcher recognises the live environment, you will need to create/change the config in your live user's `~/.config/plasma-welcomerc`: 0026 0027 ```conf 0028 [General] 0029 LiveEnvironment=true 0030 LiveInstaller=calamares 0031 ``` 0032 0033 `LiveInstaller` is optional, used to show a shortcut to launch the installer. It should be the name of a desktop file in `/usr/share/applications`, without the `.desktop` extension. 0034 0035 # Customizing the first page 0036 By default, the first page introduces the distro and mostly talks about Plasma and KDE. If desired, this can be changed by placing a specially crafted desktop file at `/usr/share/plasma/plasma-welcome/intro-customization.desktop`. In this file, you can supply custom intro text, which will be displayed first, before the standard text talking about Plasma and KDE. It is recommended to keep this text short. 0037 0038 In addition, you can optionally specify a custom icon or image to replace the Konqi image, a custom caption for it, and a custom URL to open when clicking on it. Text can be localized in the standard way that text in desktop files is localized. Note that you are expected to do this yourself! 0039 0040 ## Example intro text customization file 0041 ``` 0042 [Desktop Entry] 0043 # Required since this is a Desktop file; ignored 0044 Type=Application 0045 0046 # Required; becomes the first paragraph on the Welcome page 0047 # Don't forget to offer translations of the text! 0048 Name=Welcome to NateOS! It's the best OS ever, until it explodes. Did you know that's a feature? It's right there on the box! 0049 Name[fr]=Bienvenue sur NateOS! C'est le meilleur système d'exploitation du monde, justqu'à qu'il esplose. Saviez-vous que c'est intentionnel? C'est écrit sur la boîte! 0050 0051 # Optional; replaces the default image on the Welcome page 0052 # can be an icon name or an absolute path to an image on disk beginning with file:/ 0053 Icon=edit-bomb 0054 0055 # Optional; replaces the default image caption on the Welcome page 0056 # Don't forget to offer translations of the text! 0057 Comment=This is what a bomb looks like. Don't worry, you'll become very familiar with them! 0058 Comment[fr]=Voici à quoi ressemble une bombe. Ne vous inquiétez pas, vous allez vous familiariser avec elles! 0059 0060 # Optional; replaces the default URL opened when clicking on the Welcome page's image or icon 0061 URL=https://www.youtube.com/watch?v=dQw4w9WgXcQ 0062 ``` 0063 0064 Translations can be tested by manually running Welcome Center in a different language, e.g. `LANG=fr_FR plasma-welcome`. 0065 0066 # Extending Welcome Center with custom pages 0067 Custom distro-specific pages can be embedded in the app, and will appear right before the "Get Involved" page. Only content that is safely skippable should be added, since the user can close the app at any time, potentially before they see your custom pages. 0068 0069 To make custom pages visible to the app, place them in `/usr/share/plasma/plasma-welcome/extra-pages/`, prefixed with a number and a dash. For example if you define two pages with the following names: 0070 0071 - `01-WelcomeToDistro.qml` 0072 - `02-InstallMediaCodecs.qml` 0073 0074 These two pages will be added into the wizard, with WelcomeToDistro shown first, and then InstallMediaCodecs. 0075 0076 Custom pages are QML files with a root item that inherit from `Kirigami.Page`. Any content within the page is supported, though to maintain visual consistency with existing pages, it is recommended to use `GenericPage`, `ScrollablePage` or `KCMPage` as the root item and set the `heading` and `description` properties, with any custom content going beneath them. You can reference [existing pages](src/contents/ui/pages) when creating your own. 0077 0078 Because pages are written in QML without support for C++ support code, only functions that can be performed entirely with QML are available. Here are some examples: 0079 0080 ## Open a URL in the default web browser 0081 ``` 0082 Kirigami.Icon { 0083 source: "media-default-track" 0084 HoverHandler { 0085 cursorShape: Qt.PointingHandCursor 0086 } 0087 TapHandler { 0088 onTapped: Qt.openUrlExternally("https://www.youtube.com/watch?v=dQw4w9WgXcQ") 0089 } 0090 } 0091 ``` 0092 0093 ## Open an external app 0094 ``` 0095 ApplicationIcon { 0096 anchors.centerIn: parent 0097 application: "org.kde.dolphin" 0098 size: Kirigami.Units.gridUnit * 10 0099 } 0100 ``` 0101 0102 ## Run a terminal command 0103 ``` 0104 Kirigami.Icon { 0105 source: "notification" 0106 HoverHandler { 0107 cursorShape: Qt.PointingHandCursor 0108 } 0109 TapHandler { 0110 onTapped: Controller.runCommand("notify-send foo bar") 0111 } 0112 } 0113 ``` 0114 0115 ## Embed a KCM in the page 0116 ``` 0117 KCMPage { 0118 heading: i18nc("@title: window", "Learn about Activities") 0119 description: i18nc("@info:usagetip", "Activities can be used to separate high-level projects or tasks so you can focus on one at a time. You can set them up in System Settings, and also right here.") 0120 0121 path: "kcm_activities" 0122 } 0123 ``` 0124 0125 If you find that your specific use case can't be supported with these tools, please file a bug report at https://bugs.kde.org/enter_bug.cgi?product=Welcome%20Center detailing the use case and what would be needed to support it. 0126 0127 ## Example custom page 0128 Name this file `01-NateOS.qml` and place it in `/usr/share/plasma/plasma-welcome/extra-pages/`: 0129 0130 ``` 0131 /* 0132 * SPDX-FileCopyrightText: 2021 Felipe Kinoshita <kinofhek@gmail.com> 0133 * SPDX-FileCopyrightText: 2022 Nate Graham <nate@kde.org> 0134 * 0135 * SPDX-License-Identifier: GPL-2.0-only OR GPL-3.0-only OR LicenseRef-KDE-Accepted-GPL 0136 */ 0137 0138 import QtQuick 0139 import QtQuick.Controls as QQC2 0140 import QtQuick.Layouts 0141 import org.kde.kirigami as Kirigami 0142 import Qt5Compat.GraphicalEffects 0143 0144 import org.kde.plasma.welcome 0145 0146 GenericPage { 0147 heading: i18nc("@info:window", "Welcome to NateOS") 0148 description: i18nc("@info:usagetip", "It's the best distro in the world… <i>until it explodes</i>.") 0149 0150 topContent: [ 0151 Kirigami.UrlButton { 0152 Layout.topMargin: Kirigami.Units.largeSpacing 0153 text: i18nc("@action:button", "All your base are belong to us") 0154 url: "https://en.wikipedia.org/wiki/All_your_base_are_belong_to_us" 0155 } 0156 ] 0157 0158 ColumnLayout { 0159 anchors.centerIn: parent 0160 spacing: 0 0161 0162 Kirigami.Icon { 0163 id: image 0164 Layout.preferredWidth: Kirigami.Units.gridUnit * 10 0165 Layout.preferredHeight: Layout.preferredWidth 0166 0167 source: "granatier" 0168 0169 HoverHandler { 0170 id: hoverHandler 0171 cursorShape: Qt.PointingHandCursor 0172 } 0173 0174 TapHandler { 0175 onTapped: showPassiveNotification(i18n("You have no chance to survive make your time")); 0176 } 0177 0178 QQC2.ToolTip { 0179 visible: hoverHandler.hovered 0180 text: i18nc("@action:button", "Detonate the bomb") 0181 } 0182 0183 layer.enabled: true 0184 layer.effect: DropShadow { 0185 transparentBorder: true 0186 horizontalOffset: 0 0187 verticalOffset: 1 0188 radius: 20 0189 samples: 20 0190 color: Qt.rgba(0, 0, 0, 0.2) 0191 } 0192 } 0193 0194 Kirigami.Heading { 0195 Layout.alignment: Qt.AlignHCenter 0196 Layout.bottomMargin: Kirigami.Units.gridUnit 0197 text: i18nc("@title a friendly warning", "Someone set us up the bomb") 0198 wrapMode: Text.WordWrap 0199 level: 3 0200 } 0201 } 0202 } 0203 ```