diff --git a/frame/panel/mainpanel.cpp b/frame/panel/mainpanel.cpp index a4ea37fa7..a5e604b3a 100644 --- a/frame/panel/mainpanel.cpp +++ b/frame/panel/mainpanel.cpp @@ -87,6 +87,10 @@ MainPanel::MainPanel(QWidget *parent) setLayout(m_itemLayout); } +/// +/// \brief MainPanel::updateDockPosition change panel layout with spec position. +/// \param dockPosition +/// void MainPanel::updateDockPosition(const Position dockPosition) { m_position = dockPosition; @@ -102,6 +106,10 @@ void MainPanel::updateDockPosition(const Position dockPosition) m_itemAdjustTimer->start(); } +/// +/// \brief MainPanel::updateDockDisplayMode change panel style with spec mode. +/// \param displayMode +/// void MainPanel::updateDockDisplayMode(const DisplayMode displayMode) { m_displayMode = displayMode; @@ -109,6 +117,7 @@ void MainPanel::updateDockDisplayMode(const DisplayMode displayMode) const QList itemList = m_itemController->itemList(); for (auto item : itemList) { + // we need to hide container item at fashion mode. if (item->itemType() == DockItem::Container) item->setVisible(displayMode == Dock::Efficient); } @@ -117,11 +126,19 @@ void MainPanel::updateDockDisplayMode(const DisplayMode displayMode) setStyleSheet(styleSheet()); } +/// +/// \brief MainPanel::displayMode interface for Q_PROPERTY, never use this func. +/// \return +/// int MainPanel::displayMode() { return int(m_displayMode); } +/// +/// \brief MainPanel::position interface for Q_PROPERTY, never use this func. +/// \return +/// int MainPanel::position() { return int(m_position); @@ -287,6 +304,10 @@ void MainPanel::dropEvent(QDropEvent *e) } } +/// +/// \brief MainPanel::manageItem manage a dock item, all dock item should be managed after construct. +/// \param item +/// void MainPanel::manageItem(DockItem *item) { connect(item, &DockItem::dragStarted, this, &MainPanel::itemDragStarted, Qt::UniqueConnection); @@ -295,6 +316,11 @@ void MainPanel::manageItem(DockItem *item) connect(item, &DockItem::requestWindowAutoHide, this, &MainPanel::requestWindowAutoHide, Qt::UniqueConnection); } +/// +/// \brief MainPanel::itemAt get a dock item which placed at spec point, +/// \param point +/// \return if no item at spec point, return nullptr +/// DockItem *MainPanel::itemAt(const QPoint &point) { const QList itemList = m_itemController->itemList(); @@ -315,6 +341,11 @@ DockItem *MainPanel::itemAt(const QPoint &point) return nullptr; } +/// +/// \brief MainPanel::adjustItemSize adjust all dock item size to fit panel size, +/// for optimize cpu usage, DO NOT call this func immediately, you should use m_itemAdjustTimer +/// to delay do this operate. +/// void MainPanel::adjustItemSize() { Q_ASSERT(sender() == m_itemAdjustTimer); @@ -480,6 +511,13 @@ void MainPanel::adjustItemSize() update(); } +/// +/// \brief MainPanel::itemInserted insert dock item into index position. +/// the new inserted item will be hideen first, and then shown after size +/// adjust finished. +/// \param index +/// \param item +/// void MainPanel::itemInserted(const int index, DockItem *item) { // hide new item, display it after size adjust finished @@ -491,6 +529,11 @@ void MainPanel::itemInserted(const int index, DockItem *item) m_itemAdjustTimer->start(); } +/// +/// \brief MainPanel::itemRemoved take out spec item from panel, this function +/// will NOT delete item, and NOT disconnect any signals between item and panel. +/// \param item +/// void MainPanel::itemRemoved(DockItem *item) { m_itemLayout->removeWidget(item); @@ -498,6 +541,12 @@ void MainPanel::itemRemoved(DockItem *item) m_itemAdjustTimer->start(); } +/// +/// \brief MainPanel::itemMoved move item to spec index. +/// the index is start from 0 and counted before remove spec item. +/// \param item +/// \param index +/// void MainPanel::itemMoved(DockItem *item, const int index) { // remove old item @@ -506,6 +555,9 @@ void MainPanel::itemMoved(DockItem *item, const int index) m_itemLayout->insertWidget(index, item); } +/// +/// \brief MainPanel::itemDragStarted handle managed item draging +/// void MainPanel::itemDragStarted() { DragingItem = qobject_cast(sender()); @@ -517,6 +569,10 @@ void MainPanel::itemDragStarted() DragingItem->setVisible(rect.contains(QCursor::pos())); } +/// +/// \brief MainPanel::itemDropped handle managed item dropped. +/// \param destnation +/// void MainPanel::itemDropped(QObject *destnation) { if (m_displayMode == Dock::Fashion) diff --git a/interfaces/constants.h b/interfaces/constants.h index affbf127a..f0494546a 100644 --- a/interfaces/constants.h +++ b/interfaces/constants.h @@ -8,6 +8,10 @@ namespace Dock { #define DOCK_PLUGIN_MIME "dock/plugin" #define PROP_DISPLAY_MODE "DisplayMode" +/// +/// \brief The DisplayMode enum +/// spec dock display mode +/// enum DisplayMode { Fashion = 0, @@ -17,6 +21,10 @@ enum DisplayMode }; #define PROP_HIDE_MODE "HideMode" +/// +/// \brief The HideMode enum +/// spec dock hide behavior +/// enum HideMode { KeepShowing = 0, @@ -25,6 +33,11 @@ enum HideMode }; #define PROP_POSITION "Position" +/// +/// \brief The Position enum +/// spec dock position, dock always placed at primary screen, +/// so all position is the primary screen edge. +/// enum Position { Top = 0, @@ -34,6 +47,11 @@ enum Position }; #define PROP_HIDE_STATE "HideState" +/// +/// \brief The HideState enum +/// spec current dock should hide or shown. +/// this argument works only HideMode is SmartHide +/// enum HideState { Unknown = 0, diff --git a/interfaces/pluginproxyinterface.h b/interfaces/pluginproxyinterface.h index aac5acf6a..7aabaec40 100644 --- a/interfaces/pluginproxyinterface.h +++ b/interfaces/pluginproxyinterface.h @@ -9,9 +9,38 @@ class PluginsItemInterface; class PluginProxyInterface { public: + /// + /// \brief itemAdded + /// add a new dock item + /// if itemkey of this plugin inter already exist, the new item + /// will be ignored, so if you need to add multiple item, you need + /// to ensure all itemKey is different. + /// \param itemInter + /// your plugin interface + /// \param itemKey + /// your item unique key + /// virtual void itemAdded(PluginsItemInterface * const itemInter, const QString &itemKey) = 0; + /// + /// \brief itemUpdate + /// update(repaint) spec item + /// \param itemInter + /// \param itemKey + /// virtual void itemUpdate(PluginsItemInterface * const itemInter, const QString &itemKey) = 0; + /// + /// \brief itemRemoved + /// remove spec item, if spec item is not exist, dock will to nothing. + /// dock will NOT delete your object, you should manage memory by your self. + /// \param itemInter + /// \param itemKey + /// virtual void itemRemoved(PluginsItemInterface * const itemInter, const QString &itemKey) = 0; + /// + /// \brief requestRefershWindowVisible + /// tell dock refersh window visible state, + /// its useful because sometimes you could force disable auto-hide. + /// virtual void requestRefershWindowVisible() = 0; }; diff --git a/interfaces/pluginsiteminterface.h b/interfaces/pluginsiteminterface.h index 6cac24d30..214439f48 100644 --- a/interfaces/pluginsiteminterface.h +++ b/interfaces/pluginsiteminterface.h @@ -6,52 +6,167 @@ #include #include +/// +/// \brief The PluginsItemInterface class +/// the dock plugins item interface, all dock plugins should +/// inheirt this class and override all pure virtual function. +/// class PluginsItemInterface { public: + /// + /// \brief ~PluginsItemInterface + /// DONT try to delete m_proxyInter. + /// virtual ~PluginsItemInterface() {} - // the unique plugin id + /// + /// \brief pluginName + /// tell dock the unique plugin id + /// \return + /// virtual const QString pluginName() const = 0; - // init plugins + /// + /// \brief init + /// init your plugins, you need to save proxyInter to m_proxyInter + /// member variable. but you shouldn't free this pointer. + /// \param proxyInter + /// DONT try to delete this pointer. + /// virtual void init(PluginProxyInterface *proxyInter) = 0; - // plugin item widget + /// + /// \brief itemWidget + /// your plugin item widget, each item should have a unique key. + /// \param itemKey + /// your widget' unqiue key. + /// \return + /// virtual QWidget *itemWidget(const QString &itemKey) = 0; + /// + /// \brief itemTipsWidget + /// override this function if your item want to have a tips. + /// the tips will shown when user hover your item. + /// nullptr will be ignored. + /// \param itemKey + /// \return + /// virtual QWidget *itemTipsWidget(const QString &itemKey) {Q_UNUSED(itemKey); return nullptr;} + /// + /// \brief itemPopupApplet + /// override this function if your item wants to have an popup applet. + /// the popup applet will shown when user click your item. + /// + /// Tips: + /// dock should receive mouse press/release event to check user mouse operate, + /// if your item filter mouse event, this function will not be called. + /// so if you override mouse event and want to use popup applet, you + /// should pass event to your parent use QWidget::someEvent(e); + /// \param itemKey + /// \return + /// virtual QWidget *itemPopupApplet(const QString &itemKey) {Q_UNUSED(itemKey); return nullptr;} + /// + /// \brief itemCommand + /// execute spec command when user clicked your item. + /// ensure your command do not get user input. + /// + /// empty string will be ignored. + /// \param itemKey + /// \return + /// virtual const QString itemCommand(const QString &itemKey) {Q_UNUSED(itemKey); return QString();} - // item sort key + /// + /// \brief itemSortKey + /// tell dock where your item wants to put on. + /// + /// this index is start from 1 and + /// 0 for left side + /// -1 for right side + /// \param itemKey + /// \return + /// virtual int itemSortKey(const QString &itemKey) {Q_UNUSED(itemKey); return 1;} - // reset sort key when plugins order changed + /// + /// \brief setSortKey + /// save your item new position + /// sort key will be changed when plugins order + /// changed(by user drag-drop) + /// \param itemKey + /// \param order + /// virtual void setSortKey(const QString &itemKey, const int order) {Q_UNUSED(itemKey); Q_UNUSED(order);} - // item allow to move to container + /// + /// \brief itemAllowContainer + /// tell dock is your item allow to move into container + /// + /// if your item placed into container, popup tips and popup + /// applet will be disabled. + /// \param itemKey + /// \return + /// virtual bool itemAllowContainer(const QString &itemKey) {Q_UNUSED(itemKey); return false;} - // item is in container + /// + /// \brief itemIsInContainer + /// tell dock your item is in container, this function + /// called at item init and if your item enable container. + /// \param itemKey + /// \return + /// virtual bool itemIsInContainer(const QString &itemKey) {Q_UNUSED(itemKey); return false;} - // set item status + /// + /// \brief setItemIsInContainer + /// save your item new state. + /// this function called when user drag out your item from + /// container or user drop item into container(if your item + /// allow drop into container). + /// \param itemKey + /// \param container + /// virtual void setItemIsInContainer(const QString &itemKey, const bool container) {Q_UNUSED(itemKey); Q_UNUSED(container);} - // dock display mode changed + /// + /// \brief displayModeChanged + /// override this function to receive display mode changed signal + /// \param displayMode + /// virtual void displayModeChanged(const Dock::DisplayMode displayMode) {Q_UNUSED(displayMode);} - // dock position changed + /// + /// \brief positionChanged + /// override this function to receive dock position changed signal + /// \param position + /// virtual void positionChanged(const Dock::Position position) {Q_UNUSED(position);} protected: + /// + /// \brief displayMode + /// get current dock display mode + /// \return + /// inline Dock::DisplayMode displayMode() const { return qApp->property(PROP_DISPLAY_MODE).value(); } + /// + /// \brief position + /// get current dock position + /// \return + /// inline Dock::Position position() const { return qApp->property(PROP_POSITION).value(); } protected: + /// + /// \brief m_proxyInter + /// NEVER delete this object. + /// PluginProxyInterface *m_proxyInter; };