Warning, /maui/mauiman/Mainpage.dox is written in an unsupported language. File is not indexed.
0001 /* 0002 * This file is part of MauiKit 0003 * SPDX-FileCopyrightText: 2023 Camilo Higuita <milo.h@aol.com> 0004 * 0005 * SPDX-License-Identifier: LGPL-2.0-or-later 0006 */ 0007 0008 0009 /** @mainpage mauiman 0010 0011 0012 @subsection overview Introduction 0013 MauiMan stands for Maui Manager, and exists for setting, saving, and syncing the configuration preferences for the Maui Apps & Shell ecosystem. These configurations are global, and some of them can be overridden by the apps themselves, but more about that later. 0014 0015 To store the configurations MauiMan uses the `MauiMan.conf` config file, located at your system local config path: for example at `~/.config/Maui/MauiMan.conf.` 0016 0017 @note The settings modifications are only written/saved when using the MauiMan API directly. 0018 0019 MauiMan consists of two parts, a (1) background server that syncs and broadcasts the preference properties changes to all the running Maui Apps, and a (2) public API, that allows app developers to easily hook their apps to the system preferences. The MauiMan server program is named `MauiManServer4` and uses the DBus IPC. 0020 0021 The public API and the server are divided into modules, for different settings categories, such as Theme, Background, Accessibility, FormFactor, etc… 0022 0023 @image html mauiman.png "MauiMan configuration interfaces" 0024 0025 @subsection tutorial Tutorial 0026 To configure any existing preferences, there are different ways to do it, from a graphical interface to editing a text file or even hooking to the public API directly (for developers), in the following sections we’ll cover all the possible ways. 0027 0028 The ideal way to set/modify the configurations, from a user perspective, is to use the Maui Settings application, which exposes all of the MauiMan preferences in a graphical user interface; although, some of the settings presented are “curated” to use predefined and sane values, for example, not allowing to set the border-radius of elements to an unfitting value - rendering the interface unusable. 0029 This means that with this approach you dont get full control over the values of the properties in all the cases, but you are less prompt to mess up. 0030 0031 Maui Settings also exposes other settings for other system parts, such as Networks, Sound, Notifications, etc. 0032 0033 @note If any of the needed servers to sync configurations are offline, Maui Settings warns you about it and allows you to launch the server daemon with a single click. 0034 0035 @warning Keep in mind that Maui Settings is still under heavy development and most modules are still not implemented. 0036 0037 @image html mauisettings.gif "Maui Settings" 0038 0039 @section usage Usage 0040 0041 @subsection dbus DBus 0042 Another way to do interact with MauiMan is by using DBus directly. For this, one can use a graphical application and navigate to `org.mauiman.Manager` and then dive into the existing modules for modifying the properties. 0043 0044 @note DBusViewer is a handy application to navigate and modify the running services properties. 0045 0046 (!) Using this approach will not save the changes: it will keep the changes in memory as long as the MauiManServer daemon is running, but once the process is restarted those changes will be lost, since changes to the MauiMan properties are only saved when using the MauiMan public API. 0047 0048 @subsection conf Conf File 0049 Another approach is to manually edit the `MauiMan.conf` file. It has a couple downsides: 0050 0051 @warning The changes won’t be broadcast to all the running applications. Changes won’t be loaded until `MauiManServer4` process has been restarted since MauiManServer4 saves in memory the properties and only loads preferences from the conf file on startup. 0052 0053 Using this conf file is a convenient way to set default values for distributions shipping Maui apps, so they can be styled for the distribution preferences. This conf file is located at: 0054 0055 `~/.config/Maui/MauiMan.conf` 0056 0057 Here’s a snapshot of the conf file contents: 0058 0059 @code 0060 [Accessibility] 0061 SingleClick=false 0062 0063 [Background] 0064 DimWallpaper=false 0065 FitWallpaper=false 0066 ShowWallpaper=true 0067 SolidColor=#ffff00 0068 SourceDir=file:///usr/share/wallpapers/Cask 0069 Wallpaper=file:///usr/share/wallpapers/Cask/Cloudy Noon - 5K (16:10).jpg 0070 0071 [FormFactor] 0072 PreferredMode=0 0073 0074 [InputDevices] 0075 KeyboardLayout=us 0076 0077 [Screen] 0078 Orientation=1 0079 ScaleFactor=1 0080 0081 [Theme] 0082 AccentColor=#000 0083 BorderRadius=12 0084 CustomColorScheme=Amethyst 0085 DefaultFont="Noto Sans,10,-1,0,50,0,0,0,0,0,Regular" 0086 EnableCSD=true 0087 EnableEffects=true 0088 IconSize=16 0089 IconTheme=Colloid 0090 MarginSize=4 0091 MonospacedFont="xos4 Terminus,12,-1,7,50,0,0,0,0,0,Regular" 0092 PaddingSize=4 0093 SpacingSize=4 0094 StyleType=1 0095 WindowControlsTheme=CadiumGloss 0096 @endcode 0097 0098 @subsection api API 0099 Accessing these MauiMan properties is also possible from an application side too: for developers there is the MauiMan public library which exposes all the properties trough a public API. So if you need to know about the current workspace background image source, you could hook to `MauiMan::BackgroundManager::wallpaper()` and connect to the `wallpaperChanged` signal to know in real time when the wallpaper has been changed. 0100 0101 @code 0102 #include <MauiMan/backgroundmanager.h> 0103 0104 void func() 0105 { 0106 auto wallpaper = MauiMan::BackgroundManager().wallpaperSource(); // do something with the information 0107 } 0108 @endcode 0109 0110 Here you will find the complete documentation of all the available modules and its properties. 0111 0112 @subsection mauikit MauiKit 0113 Most of the properties are already quickly accessible via the MauiKit Style object, (for apps developed using MauiKit) which besides syncing to MauiMan changes can also override these properties with in-app specific values and if needed clear those using the `undefined` value to reset back to the default MauiMan values. 0114 0115 For example, for setting the style type as dark for an app, despite the global preference being different: 0116 @code 0117 Maui.ApplicationWindow 0118 { 0119 Maui.Style.styleType: Maui.Style.Dark 0120 } 0121 @endcode 0122 0123 and to reset the value back to the global system preference: 0124 0125 @code 0126 Maui.ApplicationWindow 0127 { 0128 Maui.Style.styleType: undefined 0129 } 0130 @endcode 0131 0132 0133 @section notes Notes 0134 0135 @subsection contributing Contributing 0136 0137 If you find any syntax errors, missing documentation, or not working code snippets or examples, please consider reporting the issue at 0138 <a href="https://invent.kde.org/maui/mauiman/-/issues">MauiKit</a> issues page, with the **documentation** tag. 0139 0140 If you want to contribute with the documentation efforts, you can contact the Maui Project at Telegram `[at]mauiproject`. 0141 0142 @authors 0143 Camilo Higuita \<milo.h@aol.com.com\><br> 0144 0145 @maintainers 0146 Camilo Higuita \<milo.h@aol.com.com\><br> 0147 0148 @licenses 0149 @lgpl 0150 */ 0151 0152 // DOXYGEN_SET_RECURSIVE = YES 0153 // DOXYGEN_SET_EXCLUDE_PATTERNS += *_p.h */private/* */examples/* */doc/* */styles/* 0154 // DOXYGEN_SET_PROJECT_NAME = MauiKit 0155 // vim:ts=4:sw=4:expandtab:filetype=doxygen