# ukui-sidebar
## Introduction
ukui-sidebar is a sidebar shortcut tool for the UKUI desktop environment, mainly consisting of two parts: the Control Center and the Notification Center.

### Build Dependencies
The project uses CMake as its build system and supports both Qt5 and Qt6. Taking Debian-based systems as an example:

```shell
# Qt6 dependencies (current):
sudo apt install cmake pkgconf libxcb1-dev libgsettings-qt6-dev \
    qt6-base-dev qt6-base-private-dev qt6-declarative-dev qt6-declarative-private-dev \
    qt6-tools-dev qtchooser libkf6windowsystem-dev \
    libkysdk-base-dev libkysdk-system-dev libopencv-dev \
    libukui-quick-dev libukui-notification-dev libukui-search-dev

# You can also use mk-build-deps to automatically install all build dependencies:
sudo apt install devscripts
sudo mk-build-deps -i
```

### Build
```shell
git clone https://gitee.com/openkylin/ukui-sidebar.git
cd ukui-sidebar
mkdir build && cd build
cmake ..
make
sudo make install
```

### Project Structure
The project is mainly divided into two parts:
- **ukui-shortcut** — Shortcut plugin manager and plugin interface library
- **src** — The ukui-sidebar application itself (control center, notification center, window management, etc.)

## Running
As a component of the UKUI desktop environment, ukui-sidebar starts automatically on boot (via `/etc/xdg/autostart/ukui-sidebar.desktop`) and cannot be disabled.

The sidebar has two display modes: **PC mode** and **Tablet mode**.
- **PC mode**: The sidebar can be invoked by clicking the tray icon, swiping left from the right edge of the screen, or using the shortcut key `Super + A`.
- **Tablet mode**: The sidebar is split into the Control Center and Notification Center. The Control Center can be invoked using the same three methods as PC mode. The Notification Center is invoked by swiping down from the top edge of the screen.

## Command Line Options
```shell
Options:
  -S, --state          Show the current state of the sidebar.
  -s, --show <option>  There are two options, 'notify' and 'control'.
  -q, --quit           Quit sidebar.
  -h, --help           Displays this help.
  -v, --version        Displays version information.
```

## D-Bus Interface
The sidebar registers a D-Bus service at startup:

```
Service:   org.ukui.Sidebar
Path:      /org/ukui/Sidebar
Interface: org.ukui.Sidebar
```

### Methods
| Method | Arguments | Description |
|--------|-----------|-------------|
| `sidebarActive()` | — | Activate the sidebar (PC notification page) |
| `shortcutsActive()` | — | Activate the shortcuts panel |
| `active(module)` | `String module` | Activate a specific module: `"sidebar"`, `"shortcut"`, or `"notice"` |
| `shortcutWidgetActive(id, showReturnButton)` | `String id`, `Bool showReturnButton` | Activate a specific shortcut widget by ID |

### Signals
| Signal | Arguments | Description |
|--------|-----------|-------------|
| `activeRequest(module, display)` | `String module`, `String display` | Emitted when an activation is requested |
| `stateChange(module, data)` | `String module`, `Map data` | Emitted when the sidebar state changes |

## Development Interface (Plugin API)
Based on the Qt plugin framework, the sidebar provides a plugin interface for control center shortcut operations. The plugin system consists of two classes:

### UkuiShortcutPlugin (Plugin Entry Point)
```C++
class UkuiShortcutPlugin : public QObject
{
    Q_OBJECT
public:
    explicit UkuiShortcutPlugin(QObject *parent = nullptr);
    ~UkuiShortcutPlugin() override;

    // Unique plugin identifier
    virtual QString pluginId() = 0;

    // Translation file names for the shortcut button
    // e.g. return "auto-rotation-shortcut" for auto-rotation-shortcut_zh_CN.qm
    virtual QStringList translations() = 0;

    // Create the shortcut instance
    virtual Shortcut *createShortcut() = 0;
};
```

### Shortcut (Shortcut Button Interface)
```C++
class UKUISHORTCUT_EXPORT Shortcut : public QObject
{
    Q_OBJECT
public:
    explicit Shortcut(QObject *parent = nullptr) : QObject(parent) {}

    // Plugin identifier
    virtual QString pluginId() = 0;

    // Plugin type (style), specify buttons for different system modes
    virtual QMap<PluginMetaType::SystemMode, PluginMetaData> pluginMetaData() = 0;

    // Respond to front-end user actions
    virtual void active(PluginMetaType::Action action) = 0;

    // Override for progress bar style plugins
    virtual void setValue(int value) { Q_UNUSED(value) }

    // Return the current status information
    virtual const StatusInfo currentStatus() = 0;

    // Whether the plugin is visible
    virtual bool isEnable() { return true; }

    // Whether this plugin has been added to the shortcut panel
    virtual void setAddedState(bool added) { Q_UNUSED(added) }

Q_SIGNALS:
    void statusChanged(const StatusInfo &info);
    void enableStatusChanged(bool isEnable);
};
```

### Plugin Types
```C++
enum PluginType
{
    Icon = 0,        // Icon style
    ProgressBar,     // Progress bar style
    MenuButton       // Expandable menu button style
};
```

### System Modes
```C++
enum SystemMode {
    PC = 0,          // PC mode
    Tablet,          // Tablet mode (also used for VR, AR, Other)
};
```

### User Actions
```C++
enum Action {
    Click = 0,       // Click
    LongClick,       // Long press
    MenuRequest,     // Menu request
};
```

A shortcut panel plugin demo is available at https://gitee.com/qiqi49/shortcut-plugin-test.

### Use with CMake:
```cmake
find_package(PkgConfig)
pkg_check_modules(ukui-shortcut REQUIRED ukui-shortcut)
include_directories(${ukui-shortcut_INCLUDE_DIRS})
target_link_libraries(yourapp ukui-shortcut)
```

### Use with QMake:
```qmake
CONFIG += link_pkgconfig
PKGCONFIG += ukui-shortcut
```

## Debugging
After installation, run `ukui-sidebar` in the terminal to start the sidebar. Application logs are written to `~/.config/org.ukui/ukui-sidebar.log`.
