add documents

Change-Id: I94eb2be8d6d977ed01357465079a25e4c81c681f

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<DockItem *> 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<DockItem *> 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<DockItem *>(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)

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,

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;
 };
 

interfaces/pluginsiteminterface.h

@@ -6,52 +6,167 @@
 #include <QIcon>
 #include <QtCore>
 
+///
+/// \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<Dock::DisplayMode>();
     }
 
+    ///
+    /// \brief position
+    /// get current dock position
+    /// \return
+    ///
     inline Dock::Position position() const
     {
         return qApp->property(PROP_POSITION).value<Dock::Position>();
     }
 
 protected:
+    ///
+    /// \brief m_proxyInter
+    /// NEVER delete this object.
+    ///
     PluginProxyInterface *m_proxyInter;
 };