### KXmlGuiWindow::setupGUI - Configure Window Options

Source: https://context7.com/frameworks/kxmlgui/llms.txt

Use setupGUI to configure window options with StandardWindowOption flags and an optional XML resource file path. It's a recommended replacement for manual GUI setup calls.

```cpp
// Use all defaults (toolbar menu, shortcut config, statusbar toggle,
// auto-save settings, and GUI creation):
setupGUI(KXmlGuiWindow::Default);

// With an explicit default window size overriding saved geometry:
setupGUI(QSize(900, 600), KXmlGuiWindow::Default, QStringLiteral("myappui.rc"));

// KParts host: skip Create because createGUI(part) is called separately:
setupGUI(KXmlGuiWindow::ToolBar | KXmlGuiWindow::Keys
         | KXmlGuiWindow::StatusBar | KXmlGuiWindow::Save);
```

--------------------------------

### KXmlGuiWindow::setupGUI

Source: https://context7.com/frameworks/kxmlgui/llms.txt

Configures window options using a bitwise OR of StandardWindowOption flags and an optional XML resource file path. This is the recommended replacement for manual GUI setup calls.

```APIDOC
## KXmlGuiWindow::setupGUI — configure window options

`setupGUI()` accepts a bitwise OR of `StandardWindowOption` flags and an optional path to the XML resource file. It is the recommended replacement for manually calling `createGUI()`, `setStandardToolBarMenuEnabled()`, `createStandardStatusBarAction()`, and `setAutoSaveSettings()`.

```cpp
// Use all defaults (toolbar menu, shortcut config, statusbar toggle,
// auto-save settings, and GUI creation):
setupGUI(KXmlGuiWindow::Default);

// With an explicit default window size overriding saved geometry:
setupGUI(QSize(900, 600), KXmlGuiWindow::Default, QStringLiteral("myappui.rc"));

// KParts host: skip Create because createGUI(part) is called separately:
setupGUI(KXmlGuiWindow::ToolBar | KXmlGuiWindow::Keys
         | KXmlGuiWindow::StatusBar | KXmlGuiWindow::Save);
```
```

--------------------------------

### Show KShortcutsDialog

Source: https://context7.com/frameworks/kxmlgui/llms.txt

Provides examples for showing the KShortcutsDialog, both with simple static invocation and with manual setup including callbacks for saving and adding multiple action collections.

```cpp
#include <KShortcutsDialog>
#include <KShortcutsEditor>

// --- Simple static invocation (recommended) ---
KShortcutsDialog::showDialog(
    actionCollection(),
    KShortcutsEditor::LetterShortcutsAllowed,
    this);

// --- Full manual usage with post-save callback ---
auto *dlg = new KShortcutsDialog(
    KShortcutsEditor::AllActions,
    KShortcutsEditor::LetterShortcutsAllowed,
    this);
dlg->setAttribute(Qt::WA_DeleteOnClose);

// Add multiple collections (e.g. host app + plugin):
dlg->addCollection(actionCollection(), i18n("Main Window"));
dlg->addCollection(pluginCollection,  i18n("My Plugin"));

// React after settings are written to disk:
connect(dlg, &KShortcutsDialog::saved, this, [this]() {
    qDebug() << "Shortcuts saved — reloading XML clients";
    for (auto *c : guiFactory()->clients())
        c->reloadXML();
});

// Import / export shortcut schemes:
dlg->exportConfiguration(QStringLiteral("/tmp/my_shortcuts.kksrc"));
dlg->importConfiguration(QStringLiteral("/tmp/my_shortcuts.kksrc"));

dlg->configure(/*saveSettings=*/true);
```

--------------------------------

### KXmlGuiWindow Example: Main Window Implementation

Source: https://context7.com/frameworks/kxmlgui/llms.txt

Demonstrates subclassing KXmlGuiWindow to load an application's .rc file, set up standard and custom actions, and build the GUI. Requires KActionCollection and KStandardAction for action management.

```cpp
// mainwindow.h
#include <KXmlGuiWindow>
#include <KActionCollection>
#include <KStandardAction>
#include <QTextEdit>

class MainWindow : public KXmlGuiWindow
{
    Q_OBJECT
public:
    explicit MainWindow(QWidget *parent = nullptr);

private Q_SLOTS:
    void newDocument();
    void clearDocument();

private:
    QTextEdit *m_editor;
};

// mainwindow.cpp
#include "mainwindow.h"
#include <QAction>
#include <QIcon>
#include <KLocalizedString>

MainWindow::MainWindow(QWidget *parent)
    : KXmlGuiWindow(parent)
{
    setObjectName(QStringLiteral("MainWindow"));

    m_editor = new QTextEdit(this);
    setCentralWidget(m_editor);

    // --- Standard actions (quit, new, etc.) ---
    KStandardAction::quit(qApp, &QCoreApplication::quit, actionCollection());
    KStandardAction::openNew(this, &MainWindow::newDocument, actionCollection());

    // --- Custom action ---
    QAction *clearAction = new QAction(QIcon::fromTheme(QStringLiteral("edit-clear")),
                                       i18n("&Clear"), this);
    KActionCollection::setDefaultShortcut(clearAction, Qt::CTRL | Qt::Key_W);
    actionCollection()->addAction(QStringLiteral("edit_clear"), clearAction);
    connect(clearAction, &QAction::triggered, m_editor, &QTextEdit::clear);

    // Loads appnameui.rc, sets up toolbar/shortcut menus,
    // restores saved window geometry (Save flag) and builds the GUI (Create flag).
    setupGUI(Default, QStringLiteral("myappui.rc"));
    // Equivalent to: setupGUI(ToolBar | Keys | StatusBar | Save | Create)
}

void MainWindow::newDocument()  { m_editor->clear(); }
void MainWindow::clearDocument() { m_editor->clear(); }

```

--------------------------------

### KXmlGui XML Resource File Example (myappui.rc)

Source: https://context7.com/frameworks/kxmlgui/llms.txt

Defines the GUI structure for a KXmlGui application, including toolbars and menus, referencing actions by name. This XML file is loaded by setupGUI() in KXmlGuiWindow.

```xml
// myappui.rc  (installed to ${KDE_INSTALL_KXMLGUIDIR}/myapp/)
// <?xml version="1.0" encoding="UTF-8"?>
// <!DOCTYPE gui SYSTEM "kpartgui.dtd">
// <gui name="myapp" version="1">
//   <ToolBar name="mainToolBar"><text>Main Toolbar</text>
//     <Action name="file_new"/>
//     <Action name="edit_clear"/>
//   </ToolBar>
//   <MenuBar>
//     <Menu name="file"><text>&amp;File</text>
//       <Action name="file_new"/>
//       <Separator/>
//       <Action name="file_quit"/>
//     </Menu>
//     <Menu name="edit"><text>&amp;Edit</text>
//       <Action name="edit_clear"/>
//     </Menu>
//   </MenuBar>
// </gui>

```

--------------------------------

### KXmlGui Application Entry Point

Source: https://context7.com/frameworks/kxmlgui/llms.txt

Sets up the QApplication, KAboutData, and the main window for a KXmlGui application. Ensures the application runs correctly with KDE Frameworks initialization.

```cpp
// main.cpp
#include <QApplication>
#include <KAboutData>
#include <KLocalizedString>
#include "mainwindow.h"

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
    KAboutData about(QStringLiteral("myapp"), i18n("My App"), QStringLiteral("1.0"));
    KAboutData::setApplicationData(about);

    MainWindow *window = new MainWindow;
    window->show();
    return app.exec();
}

```

--------------------------------

### Create and Configure KToolBar

Source: https://context7.com/frameworks/kxmlgui/llms.txt

Demonstrates manual creation of KToolBar instances, setting icon dimensions, and saving/restoring toolbar configurations using KConfig.

```cpp
#include <KToolBar>
#include <KMainWindow>
#include <KConfigGroup>

// Typically toolbars are created via XML-GUI, but can also be created manually:
KMainWindow *win = new KMainWindow;

// Get or create the named toolbar (creates "mainToolBar" if absent):
KToolBar *mainBar = win->toolBar();                           // default "mainToolBar"
KToolBar *extraBar = win->toolBar(QStringLiteral("extraBar")); // named toolbar

// Adjust icon size programmatically:
mainBar->setIconDimensions(32);

// Save / restore toolbar config to a KConfig group:
KConfigGroup grp = KSharedConfig::openConfig()->group(QStringLiteral("MainToolBar"));
mainBar->saveSettings(grp);
// …
mainBar->applySettings(grp);

// Lock all toolbars application-wide (e.g. in kiosk mode):
KToolBar::setToolBarsLocked(true);

// Notify all running KDE applications of style changes via D-Bus:
KToolBar::emitToolbarStyleChanged();
```

--------------------------------

### KHelpMenu

Source: https://context7.com/frameworks/kxmlgui/llms.txt

KHelpMenu provides a standard KDE help menu, including entries for application handbook, 'What's This?', 'Report Bug', 'About Application', 'About KDE', and 'Donate'. It can be used standalone or is managed by KXmlGuiWindow.

```APIDOC
## KHelpMenu

### Description
Provides the standardised "Help" menu with entries for the application handbook, "What's This?", "Report Bug…", "About Application", "About KDE", and "Donate". It is created automatically by `KXmlGuiWindow` but can be used standalone.

### Usage
```cpp
#include <KHelpMenu>
#include <KAboutData>

// KXmlGuiWindow creates and manages KHelpMenu internally — use it standalone:
KHelpMenu *helpMenu = new KHelpMenu(this);   // uses KAboutData::applicationData()

// Add to a custom menu bar:
menuBar()->addMenu(helpMenu->menu());

// Override "About Application" with a custom dialog:
connect(helpMenu, &KHelpMenu::showAboutApplication,
        this, &MyWidget::showCustomAboutDialog);

// Disable the help menu entirely in a KXmlGuiWindow:
setHelpMenuEnabled(false);

// Access individual actions to disable or reorder them:
QAction *reportBugAction = helpMenu->action(KHelpMenu::menuReportBug);
reportBugAction->setVisible(false);

// Custom about data for a plugin or secondary window:
KAboutData pluginAbout(QStringLiteral("myplugin"), i18n("My Plugin"), QStringLiteral("2.0"));
KHelpMenu *pluginHelp = new KHelpMenu(this, pluginAbout);
```
```

--------------------------------

### Use KHelpMenu Standalone

Source: https://context7.com/frameworks/kxmlgui/llms.txt

Shows how to use KHelpMenu independently of KXmlGuiWindow, including adding it to a menu bar, overriding the 'About Application' action, and customizing its visibility or content.

```cpp
#include <KHelpMenu>
#include <KAboutData>

// KXmlGuiWindow creates and manages KHelpMenu internally — use it standalone:
KHelpMenu *helpMenu = new KHelpMenu(this);   // uses KAboutData::applicationData()

// Add to a custom menu bar:
menuBar()->addMenu(helpMenu->menu());

// Override "About Application" with a custom dialog:
connect(helpMenu, &KHelpMenu::showAboutApplication,
        this, &MyWidget::showCustomAboutDialog);

// Disable the help menu entirely in a KXmlGuiWindow:
setHelpMenuEnabled(false);

// Access individual actions to disable or reorder them:
QAction *reportBugAction = helpMenu->action(KHelpMenu::menuReportBug);
reportBugAction->setVisible(false);

// Custom about data for a plugin or secondary window:
KAboutData pluginAbout(QStringLiteral("myplugin"), i18n("My Plugin"), QStringLiteral("2.0"));
KHelpMenu *pluginHelp = new KHelpMenu(this, pluginAbout);
```

--------------------------------

### KXmlGuiWindow::createGUI

Source: https://context7.com/frameworks/kxmlgui/llms.txt

Builds the GUI from an XML file by parsing it and populating menus and toolbars. Use this directly for more control or when using KParts.

```APIDOC
## KXmlGuiWindow::createGUI — build GUI from XML file

`createGUI()` is the lower-level function that actually parses the XML file and populates menus and toolbars. Use it directly when you need more control, or when using KParts where the part provides its own XML.

```cpp
// In a KParts host, called whenever the active part changes:
void MyWindow::createGUI(KParts::Part *part)
{
    // KXmlGuiWindow::createGUI(xmlfile) is protected; use factory() API for KParts:
    KXmlGuiWindow::createGUI(QString()); // builds from appnameui.rc
}

// Build from an absolute path (e.g. user-writable custom RC):
createGUI(QStringLiteral("/home/user/.local/share/myapp/myappui.rc"));
```
```

--------------------------------

### KXmlGuiWindow::createGUI - Build GUI from XML

Source: https://context7.com/frameworks/kxmlgui/llms.txt

createGUI parses an XML file to populate menus and toolbars. Use it directly for more control or when a KPart provides its own XML. For KParts hosts, use the factory() API.

```cpp
// In a KParts host, called whenever the active part changes:
void MyWindow::createGUI(KParts::Part *part)
{
    // KXmlGuiWindow::createGUI(xmlfile) is protected; use factory() API for KParts:
    KXmlGuiWindow::createGUI(QString()); // builds from appnameui.rc
}

// Build from an absolute path (e.g. user-writable custom RC):
createGUI(QStringLiteral("/home/user/.local/share/myapp/myappui.rc"));
```

--------------------------------

### Add KXmlGui Test Suite 1

Source: https://github.com/frameworks/kxmlgui/blob/master/autotests/CMakeLists.txt

Configures a test suite using the ecm_add_tests macro, specifying the source files and linking against Qt6::Test and KF6::XmlGui libraries.

```cmake
ecm_add_tests(
   kactioncategorytest.cpp
   kactioncollectiontest.cpp
   LINK_LIBRARIES Qt6::Test KF6::XmlGui
)
```

--------------------------------

### Dynamically Update Action Lists with KXMLGUIClient

Source: https://context7.com/frameworks/kxmlgui/llms.txt

Use plugActionList and unplugActionList to dynamically replace named <ActionList> placeholders in .rc files with custom QAction lists. This enables context-sensitive menus without GUI rebuilding. State changes can also be managed using stateChanged.

```cpp
// In myappui.rc — declare the placeholder:
// <Menu name="file">
//   <Action name="file_open"/>
//   <ActionList name="recent_files_list"/>
// </Menu>

void MyWindow::updateRecentFiles(const QStringList &paths)
{
    // Always unplug before re-plugging:
    unplugActionList(QStringLiteral("recent_files_list"));

    QList<QAction *> recentActions;
    for (const QString &path : paths) {
        auto *a = new QAction(path, this);
        connect(a, &QAction::triggered, this, [this, path]() { openFile(path); });
        recentActions.append(a);
    }

    plugActionList(QStringLiteral("recent_files_list"), recentActions);
}

// State-based enable/disable — declare in .rc:
// <State name="has_selection">
//   <enable><Action name="edit_copy"/></enable>
//   <enable><Action name="edit_cut"/></enable>
//   <disable><Action name="edit_paste"/></disable>
// </State>

void MyWindow::onSelectionChanged(bool hasSelection)
{
    stateChanged(QStringLiteral("has_selection"),
                 hasSelection ? KXMLGUIClient::StateNoReverse
                              : KXMLGUIClient::StateReverse);
}
```

--------------------------------

### Implement KXMLGUIClient for Plugin UI

Source: https://context7.com/frameworks/kxmlgui/llms.txt

Subclass KXMLGUIClient to contribute XML-described UI elements like menus and toolbars to a KXMLGUIFactory. Load UI definitions from resource files and manage actions dynamically.

```cpp
#include <KXMLGUIClient>
#include <KActionCollection>

class MyPlugin : public QObject, public KXMLGUIClient
{
    Q_OBJECT
public:
    explicit MyPlugin(KXMLGUIClient *parent)
        : QObject(parent->actionCollection()),
          KXMLGUIClient(parent)   // auto-inserts as child client
    {
        setComponentName(QStringLiteral("myplugin"),
                         i18n("My Plugin"));
        // Loads :/kxmlgui5/myplugin/mypluginui.rc from Qt resources:
        setXMLFile(QStringLiteral("mypluginui.rc"));

        QAction *act = actionCollection()->addAction(
            QStringLiteral("plugin_do_something"),
            this, &MyPlugin::doSomething);
        act->setText(i18n("Do Something"));
    }

    void doSomething() { /* … */ }

    // Dynamic action list — called when the selection changes:
    void updateSelectionActions(const QList<QObject *> &items)
    {
        QList<QAction *> acts;
        for (auto *item : items) {
            auto *a = new QAction(item->objectName(), this);
            connect(a, &QAction::triggered, this, [item]() { /* handle item */ });
            acts.append(a);
        }
        unplugActionList(QStringLiteral("selection_actions"));
        plugActionList(QStringLiteral("selection_actions"), acts);
    }
};

// In the host window, add/remove the plugin client:
guiFactory()->addClient(plugin);
// …
guiFactory()->removeClient(plugin);
delete plugin;
```

--------------------------------

### Add KXmlGui Test Suite 2

Source: https://github.com/frameworks/kxmlgui/blob/master/autotests/CMakeLists.txt

Configures another test suite with different source files and links against Qt6::Test, KF6::IconThemes, and KF6::XmlGui. It also specifies a target name 'GUI'.

```cmake
ecm_add_tests(
   kmainwindow_unittest.cpp
   ktoolbar_unittest.cpp
   ktooltiphelper_unittest.cpp
   kxmlgui_unittest.cpp
   GUI
   LINK_LIBRARIES Qt6::Test KF6::IconThemes KF6::XmlGui
)
```

--------------------------------

### Create Session-Managed KMainWindow

Source: https://context7.com/frameworks/kxmlgui/llms.txt

Extend KMainWindow for top-level windows with KDE session management, auto-saving of UI state, and per-instance D-Bus export. Use KXmlGuiWindow for XML-GUI, or KMainWindow directly for manual GUI construction.

```cpp
#include <KMainWindow>
#include <KSharedConfig>
#include <KConfigGroup>

class MyWindow : public KMainWindow
{
    Q_OBJECT
public:
    explicit MyWindow(QWidget *parent = nullptr) : KMainWindow(parent)
    {
        setObjectName(QStringLiteral("MyWindow"));
        // Auto-save window size + toolbar/statusbar state:
        setAutoSaveSettings(QStringLiteral("MainWindow"), /*saveWindowSize=*/true);
    }

protected:
    // Called by session manager — save document state:
    void saveProperties(KConfigGroup &config) override
    {
        config.writeEntry(QStringLiteral("currentFile"), m_fileName);
    }

    // Called by restore() — reload document state:
    void readProperties(const KConfigGroup &config) override
    {
        m_fileName = config.readEntry(QStringLiteral("currentFile"));
        if (!m_fileName.isEmpty())
            loadFile(m_fileName);
    }

    // Prompt before close:
    bool queryClose() override
    {
        if (!isModified())
            return true;
        // Use KMessageBox for KDE-compliant prompt
        return false;
    }

private:
    QString m_fileName;
    bool isModified() const { return false; }
    void loadFile(const QString &) {}
};

// main.cpp — session restore:
int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
    if (app.isSessionRestored()) {
        kRestoreMainWindows<MyWindow>();
    } else {
        (new MyWindow)->show();
    }
    return app.exec();
}
```

--------------------------------

### Manually Open KEditToolBar Dialog

Source: https://context7.com/frameworks/kxmlgui/llms.txt

Illustrates how to manually open the KEditToolBar dialog for user configuration of toolbar layouts, including setting a default toolbar and handling the new configuration signal.

```cpp
#include <KEditToolBar>

// KXmlGuiWindow provides configureToolbars() and saveNewToolbarConfig() automatically.
// To open the dialog manually:
void MyWindow::onConfigureToolbars()
{
    // Inform the factory that a programmatic change is about to happen:
    // (KXmlGuiWindow::configureToolbars() does this internally)
    KEditToolBar dlg(guiFactory(), this);
    dlg.setDefaultToolBar(QStringLiteral("mainToolBar"));

    connect(&dlg, &KEditToolBar::newToolBarConfig,
            this, &MyWindow::saveNewToolbarConfig);

    dlg.exec();
}

// Called after the user accepts the dialog:
void MyWindow::saveNewToolbarConfig()
{
    KXmlGuiWindow::saveNewToolbarConfig(); // re-merges XML
    // Re-plug any dynamic action lists:
    plugActionList(QStringLiteral("dynamic_list"), m_dynamicActions);
}
```

--------------------------------

### KToolBar

Source: https://context7.com/frameworks/kxmlgui/llms.txt

KToolBar extends QToolBar with KDE-specific features like reading global settings, supporting drag-and-drop reconfiguration, and respecting Kiosk restrictions. It can be created manually or via XML-GUI.

```APIDOC
## KToolBar

### Description
Extends `QToolBar` with KDE-specific features, reading icon-size and button-style from global KDE settings, supporting drag-and-drop reconfiguration when `KEditToolBar` is active, and respecting Kiosk restrictions on toolbar movement.

### Usage
```cpp
#include <KToolBar>
#include <KMainWindow>
#include <KConfigGroup>

// Typically toolbars are created via XML-GUI, but can also be created manually:
KMainWindow *win = new KMainWindow;

// Get or create the named toolbar (creates "mainToolBar" if absent):
KToolBar *mainBar = win->toolBar();                           // default "mainToolBar"
KToolBar *extraBar = win->toolBar(QStringLiteral("extraBar")); // named toolbar

// Adjust icon size programmatically:
mainBar->setIconDimensions(32);

// Save / restore toolbar config to a KConfig group:
KConfigGroup grp = KSharedConfig::openConfig()->group(QStringLiteral("MainToolBar"));
mainBar->saveSettings(grp);
// …
mainBar->applySettings(grp);

// Lock all toolbars application-wide (e.g. in kiosk mode):
KToolBar::setToolBarsLocked(true);

// Notify all running KDE applications of style changes via D-Bus:
KToolBar::emitToolbarStyleChanged();
```
```

--------------------------------

### Create Undo/Redo Actions with KUndoActions

Source: https://context7.com/frameworks/kxmlgui/llms.txt

Use KUndoActions to create standard undo and redo QAction objects. These actions are automatically wired to a QUndoStack and registered in a KActionCollection with default KDE icons and shortcuts. Custom action names can also be provided.

```cpp
#include <KUndoActions>
#include <QUndoStack>

void MyWindow::setupUndoActions()
{
    m_undoStack = new QUndoStack(this);

    // Creates actions with KDE defaults and adds them to the collection:
    KUndoActions::createUndoAction(m_undoStack, actionCollection());
    KUndoActions::createRedoAction(m_undoStack, actionCollection());

    // Custom action names (must match the names in your .rc file):
    KUndoActions::createUndoAction(m_undoStack, actionCollection(),
                                   QStringLiteral("my_undo"));
    KUndoActions::createRedoAction(m_undoStack, actionCollection(),
                                   QStringLiteral("my_redo"));

    // Use the undo stack normally — the actions update automatically:
    QUndoCommand *cmd = new MyCommand(document);
    m_undoStack->push(cmd);   // triggers undo action enabled state update
    m_undoStack->undo();      // Ctrl+Z equivalent
    m_undoStack->redo();      // Ctrl+Shift+Z equivalent
}
```

--------------------------------

### Find Qt6 and Required Packages

Source: https://github.com/frameworks/kxmlgui/blob/master/autotests/CMakeLists.txt

Finds the Qt6 package with the specified version and required components like Xml and Test. Ensures the package is required for the build.

```cmake
find_package(Qt6 ${REQUIRED_QT_VERSION} CONFIG REQUIRED Xml Test)
```

--------------------------------

### Merge GUI from KXMLGUIClient objects with KXMLGUIFactory

Source: https://context7.com/frameworks/kxmlgui/llms.txt

Use KXMLGUIFactory to build and merge GUIs from multiple KXMLGUIClient objects. It manages container widgets, dispatches build calls, and owns the DOM tree for merging.

```cpp
#include <KXMLGUIFactory>
#include <KXMLGUIClient>

// Retrieve a container widget by its XML "name" attribute after setupGUI():
QMenu *popupMenu = qobject_cast<QMenu *>(
    guiFactory()->container(QStringLiteral("my_context_menu"), this));
if (popupMenu) {
    popupMenu->exec(QCursor::pos());
}

// Iterate all currently registered clients:
const auto clients = guiFactory()->clients();
for (KXMLGUIClient *client : clients) {
    qDebug() << "Client component:" << client->componentName();
}

// Wire up the configure-shortcuts action from the factory:
KStandardAction::keyBindings(
    guiFactory(),
    &KXMLGUIFactory::showConfigureShortcutsDialog,
    actionCollection());

// React after shortcuts are saved (e.g. reload XML in cloned clients):
connect(guiFactory(), &KXMLGUIFactory::shortcutsSaved,
        this, [this]() {
            for (auto *c : guiFactory()->clients())
                c->reloadXML();
        });
```

--------------------------------

### KShortcutsDialog

Source: https://context7.com/frameworks/kxmlgui/llms.txt

KShortcutsDialog provides a tree-based editor for keyboard shortcuts from KActionCollection objects, supporting primary/alternate assignments, scheme import/export, and global shortcuts.

```APIDOC
## KShortcutsDialog

### Description
Presents a tree-based editor of all actions in one or more `KActionCollection` objects, with per-action primary/alternate shortcut assignment, scheme import/export, and optional global shortcut support.

### Usage
```cpp
#include <KShortcutsDialog>
#include <KShortcutsEditor>

// --- Simple static invocation (recommended) ---
KShortcutsDialog::showDialog(
    actionCollection(),
    KShortcutsEditor::LetterShortcutsAllowed,
    this);

// --- Full manual usage with post-save callback ---
auto *dlg = new KShortcutsDialog(
    KShortcutsEditor::AllActions,
    KShortcutsEditor::LetterShortcutsAllowed,
    this);
dlg->setAttribute(Qt::WA_DeleteOnClose);

// Add multiple collections (e.g. host app + plugin):
dlg->addCollection(actionCollection(), i18n("Main Window"));
dlg->addCollection(pluginCollection,  i18n("My Plugin"));

// React after settings are written to disk:
connect(dlg, &KShortcutsDialog::saved, this, [this]() {
    qDebug() << "Shortcuts saved — reloading XML clients";
    for (auto *c : guiFactory()->clients())
        c->reloadXML();
});

// Import / export shortcut schemes:
dlg->exportConfiguration(QStringLiteral("/tmp/my_shortcuts.kksrc"));
dlg->importConfiguration(QStringLiteral("/tmp/my_shortcuts.kksrc"));

dlg->configure(/*saveSettings=*/true);
```
```

--------------------------------

### Link Libraries

Source: https://github.com/frameworks/kxmlgui/blob/master/tests/krichtexteditor/CMakeLists.txt

Links the necessary Qt6 and KF6 libraries to the krichtexteditor target.

```cmake
target_link_libraries(krichtexteditor Qt6::Test KF6::ConfigWidgets KF6::TextWidgets KF6::XmlGui)
```

--------------------------------

### Set Include Directories

Source: https://github.com/frameworks/kxmlgui/blob/master/tests/krichtexteditor/CMakeLists.txt

Specifies the include directories for the krichtexteditor target.

```cmake
target_include_directories(krichtexteditor PRIVATE
    ${CMAKE_CURRENT_SOURCE_DIR}/..
    ${CMAKE_CURRENT_BINARY_DIR}/..
)
```

--------------------------------

### Define Executable and Sources

Source: https://github.com/frameworks/kxmlgui/blob/master/tests/krichtexteditor/CMakeLists.txt

Defines the krichtexteditor executable and lists its source files.

```cmake
add_executable(krichtexteditor)

target_sources(krichtexteditor PRIVATE
    main.cpp
    krichtexteditor.cpp
)
```

--------------------------------

### KActionCollection - Manage Named Actions and Shortcuts

Source: https://context7.com/frameworks/kxmlgui/llms.txt

KActionCollection is a named registry for QAction objects, handling shortcut assignments, authorization, and widget association. It's typically used within KXmlGuiWindow or KXMLGUIClient subclasses.

```cpp
#include <KActionCollection>
#include <KStandardAction>
#include <KStandardActions>
#include <QUndoStack>

// Inside a KXmlGuiWindow or KXMLGUIClient subclass:
void MyWindow::setupActions()
{
    // 1. Standard action — ownership transferred to the collection:
    KStandardAction::save(this, &MyWindow::saveFile, actionCollection());

    // 2. Standard action with a custom registered name:
    actionCollection()->addAction(KStandardAction::Undo,
                                  QStringLiteral("my_undo"),
                                  this, &MyWindow::undo);

    // 3. Typed custom action (KToggleAction, KSelectAction, …):
    auto *boldAction = actionCollection()->add<KToggleAction>(
        QStringLiteral("format_bold"),
        this, &MyWindow::toggleBold);
    boldAction->setText(i18n("&Bold"));
    boldAction->setIcon(QIcon::fromTheme(QStringLiteral("format-text-bold")));
    KActionCollection::setDefaultShortcut(boldAction, Qt::CTRL | Qt::Key_B);

    // 4. Plain QAction with lambda slot:
    actionCollection()->addAction(QStringLiteral("view_refresh"),
                                  this, [this]() { refresh(); });

    // 5. Retrieve by name later:
    QAction *s = actionCollection()->action(QStringLiteral("file_save"));
    Q_ASSERT(s != nullptr);

    // 6. Persist custom shortcuts to the app config:
    KConfigGroup grp = KSharedConfig::openConfig()->group(QStringLiteral("Shortcuts"));
    actionCollection()->writeSettings(&grp);
    // Reload on next start:
    actionCollection()->readSettings(&grp);
}
```

--------------------------------

### Manage Toolbar Visibility with KToggleToolBarAction

Source: https://context7.com/frameworks/kxmlgui/llms.txt

KToggleToolBarAction synchronizes a QAction's checked state with a KToolBar's visibility. Toggling the action shows or hides the toolbar, and vice-versa. This is often created automatically but can be managed manually.

```cpp
#include <KToggleToolBarAction>
#include <KToolBar>

// Typically created automatically by KXmlGuiWindow::setStandardToolBarMenuEnabled(true).
// Manual creation:
KToolBar *bar = toolBar(QStringLiteral("extraBar"));

auto *toggleAction = new KToggleToolBarAction(
    bar,
    i18n("Show Extra Toolbar"),
    actionCollection());

actionCollection()->addAction(QStringLiteral("show_extra_toolbar"), toggleAction);

// Initial checked state mirrors current visibility:
toggleAction->setChecked(bar->isVisible());

// Connect for additional side-effects:
connect(toggleAction, &KToggleToolBarAction::toggled,
        this, [](bool visible) {
            qDebug() << "Extra toolbar is now" << (visible ? "visible" : "hidden");
        });
```