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` or `KCM` as the root item and set the `heading` and `description` properties, with any custom content going beneath them. It is recommended to 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 KCM {
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 ```