fix: cleanup the Ribbon API and documentation

- change some property names for consistency
- load the recentFiles text label
- update the documentation

docs/API/script/ribbon.md

@@ -18,6 +18,17 @@ import Script 1.0
 |array<[RibbonContext](../script/ribboncontext.md)>|**[contexts](#contexts)**|
 |[RibbonMenu](../script/ribbonmenu.md)|**[menu](#menu)**|
 
+## Detailed Description
+
+A ribbon is made of multiple items:
+
+- a file menu, top/left, which displays a popup menu when clicking (see RibbonMenu)
+- multiple categories displayed as tabs
+    - each with multiple panels (displayed as group of actions)
+    - each panel contains multiple elements (displayed as buttons, separators...)
+- multiple contexts, a context showing another tab with it's name in the titlebar
+    - each context contains multiple categories
+
 ## Property Documentation
 
 #### <a name="categories"></a>array<[RibbonCategory](../script/ribboncategory.md)> **categories**

docs/API/script/ribboncategory.md

@@ -16,9 +16,9 @@ import Script 1.0
 |-|-|
 |string|**[keys](#keys)**|
 |string|**[largeImage](#largeImage)**|
-|string|**[name](#name)**|
 |array<[RibbonPanel](../script/ribbonpanel.md)>|**[panels](#panels)**|
 |string|**[smallImage](#smallImage)**|
+|string|**[text](#text)**|
 
 ## Property Documentation
 
@@ -30,14 +30,14 @@ This property holds the keys of the category.
 
 This property holds the image resource for large icons.
 
-#### <a name="name"></a>string **name**
-
-This property holds the name(text) of the category.
-
 #### <a name="panels"></a>array<[RibbonPanel](../script/ribbonpanel.md)> **panels**
 
 This property holds the children panels of this category.
 
 #### <a name="smallImage"></a>string **smallImage**
 
 This property holds the image resource for small icons.
+
+#### <a name="text"></a>string **text**
+
+This property holds the text title of the category.

docs/API/script/ribboncontext.md

@@ -15,7 +15,7 @@ import Script 1.0
 | | Name |
 |-|-|
 |array<[RibbonCategory](../script/ribboncategory.md)>|**[categories](#categories)**|
-|array<[RibbonElement](../script/ribbonelement.md)>|**[elements](#elements)**|
+|string|**[id](#id)**|
 |string|**[text](#text)**|
 
 ## Property Documentation
@@ -24,9 +24,9 @@ import Script 1.0
 
 This property holds the children categories of this context.
 
-#### <a name="elements"></a>array<[RibbonElement](../script/ribbonelement.md)> **elements**
+#### <a name="id"></a>string **id**
 
-This property holds the children elements of this menu.
+This property holds the id of the context.
 
 #### <a name="text"></a>string **text**
 

docs/API/script/ribbonelement.md

@@ -15,10 +15,8 @@ import Script 1.0
 | | Name |
 |-|-|
 |array<[RibbonElement](../script/ribbonelement.md)>|**[elements](#elements)**|
-|array<[RibbonElement](../script/ribbonelement.md)>|**[elements](#elements)**|
-|string|**[id](#id)**|
 |string|**[id](#id)**|
-|string|**[keys](#keys)**|
+|bool|**[isSeparator](#isSeparator)**|
 |string|**[keys](#keys)**|
 |int|**[largeIndex](#largeIndex)**|
 |int|**[smallIndex](#smallIndex)**|
@@ -31,26 +29,18 @@ import Script 1.0
 
 This property holds the children of this item, for creating menus.
 
-#### <a name="elements"></a>array<[RibbonElement](../script/ribbonelement.md)> **elements**
-
-This property holds the children elements of this panel.
-
 #### <a name="id"></a>string **id**
 
 This property holds the id of the element item.
 
-#### <a name="id"></a>string **id**
+#### <a name="isSeparator"></a>bool **isSeparator**
 
-This property holds the id of the context.
+This property returns `true` if the element is a separator.
 
 #### <a name="keys"></a>string **keys**
 
 This property holds the keys of the element item.
 
-#### <a name="keys"></a>string **keys**
-
-This property holds the keys of the panel.
-
 #### <a name="largeIndex"></a>int **largeIndex**
 
 This property holds the index for the large icon (32x32 generally) used for the item.

docs/API/script/ribbonmenu.md

@@ -14,25 +14,30 @@ import Script 1.0
 
 | | Name |
 |-|-|
+|array<[RibbonElement](../script/ribbonelement.md)>|**[elements](#elements)**|
 |string|**[largeImage](#largeImage)**|
-|string|**[name](#name)**|
-|bool|**[recentFiles](#recentFiles)**|
+|string|**[recentFilesText](#recentFilesText)**|
 |string|**[smallImage](#smallImage)**|
+|string|**[text](#text)**|
 
 ## Property Documentation
 
-#### <a name="largeImage"></a>string **largeImage**
+#### <a name="elements"></a>array<[RibbonElement](../script/ribbonelement.md)> **elements**
 
-This property holds the image resource for large icons.
+This property holds the children elements of this menu.
 
-#### <a name="name"></a>string **name**
+#### <a name="largeImage"></a>string **largeImage**
 
-This property holds the name(text) of the menu.
+This property holds the image resource for large icons.
 
-#### <a name="recentFiles"></a>bool **recentFiles**
+#### <a name="recentFilesText"></a>string **recentFilesText**
 
-This property is true if the menu shows recent files.
+This property holds the text for the recent files menu.
 
 #### <a name="smallImage"></a>string **smallImage**
 
 This property holds the image resource for small icons.
+
+#### <a name="text"></a>string **text**
+
+This property holds the text label of the menu.

docs/API/script/ribbonpanel.md

@@ -14,10 +14,20 @@ import Script 1.0
 
 | | Name |
 |-|-|
-|string|**[name](#name)**|
+|array<[RibbonElement](../script/ribbonelement.md)>|**[elements](#elements)**|
+|string|**[keys](#keys)**|
+|string|**[text](#text)**|
 
 ## Property Documentation
 
-#### <a name="name"></a>string **name**
+#### <a name="elements"></a>array<[RibbonElement](../script/ribbonelement.md)> **elements**
 
-This property holds the name(text) of the panel.
+This property holds the children elements of this panel.
+
+#### <a name="keys"></a>string **keys**
+
+This property holds the keys of the panel.
+
+#### <a name="text"></a>string **text**
+
+This property holds the text title of the panel.

src/rccore/ribbon.cpp

@@ -50,6 +50,10 @@ namespace RcCore {
  * \qmlproperty array<RibbonElement> RibbonElement::elements
  * This property holds the children of this item, for creating menus.
  */
+/*!
+ * \qmlproperty bool RibbonElement::isSeparator
+ * This property returns `true` if the element is a separator.
+ */
 
 /*!
  * \qmltype RibbonPanel
@@ -60,15 +64,15 @@ namespace RcCore {
  * \sa Ribbon
  */
 /*!
- * \qmlproperty string RibbonPanel::name
- * This property holds the name(text) of the panel.
+ * \qmlproperty string RibbonPanel::text
+ * This property holds the text title of the panel.
  */
 /*!
- * \qmlproperty string RibbonElement::keys
+ * \qmlproperty string RibbonPanel::keys
  * This property holds the keys of the panel.
  */
 /*!
- * \qmlproperty array<RibbonElement> RibbonElement::elements
+ * \qmlproperty array<RibbonElement> RibbonPanel::elements
  * This property holds the children elements of this panel.
  */
 
@@ -81,8 +85,8 @@ namespace RcCore {
  * \sa Ribbon
  */
 /*!
- * \qmlproperty string RibbonCategory::name
- * This property holds the name(text) of the category.
+ * \qmlproperty string RibbonCategory::text
+ * This property holds the text title of the category.
  */
 /*!
  * \qmlproperty string RibbonCategory::keys
@@ -110,7 +114,7 @@ namespace RcCore {
  * \sa Ribbon
  */
 /*!
- * \qmlproperty string RibbonElement::id
+ * \qmlproperty string RibbonContext::id
  * This property holds the id of the context.
  */
 /*!
@@ -131,8 +135,8 @@ namespace RcCore {
  * \sa Ribbon
  */
 /*!
- * \qmlproperty string RibbonMenu::name
- * This property holds the name(text) of the menu.
+ * \qmlproperty string RibbonMenu::text
+ * This property holds the text label of the menu.
  */
 /*!
  * \qmlproperty string RibbonMenu::smallImage
@@ -143,12 +147,12 @@ namespace RcCore {
  * This property holds the image resource for large icons.
  */
 /*!
- * \qmlproperty array<RibbonElement> RibbonContext::elements
+ * \qmlproperty array<RibbonElement> RibbonMenu::elements
  * This property holds the children elements of this menu.
  */
 /*!
- * \qmlproperty bool RibbonMenu::recentFiles
- * This property is true if the menu shows recent files.
+ * \qmlproperty string RibbonMenu::recentFilesText
+ * This property holds the text for the recent files menu.
  */
 
 /*!
@@ -158,6 +162,15 @@ namespace RcCore {
  * \ingroup RcDocument
  * \since 1.0
  * \sa RcFile
+ *
+ * A ribbon is made of multiple items:
+ *
+ * - a file menu, top/left, which displays a popup menu when clicking (see RibbonMenu)
+ * - multiple categories displayed as tabs
+ *     - each with multiple panels (displayed as group of actions)
+ *     - each panel contains multiple elements (displayed as buttons, separators...)
+ * - multiple contexts, a context showing another tab with it's name in the titlebar
+ *     - each context contains multiple categories
  */
 /*!
  * \qmlproperty RibbonMenu Ribbon::menu
@@ -200,18 +213,18 @@ static RibbonElement readElement(pugi::xml_node node)
 static RibbonMenu readMenu(pugi::xml_node node)
 {
     RibbonMenu menu;
-    menu.name = node.child("NAME").text().as_string();
+    menu.text = node.child("NAME").text().as_string();
     menu.smallImage = node.select_node("IMAGE_SMALL/ID/NAME").node().text().as_string();
     menu.largeImage = node.select_node("IMAGE_LARGE/ID/NAME").node().text().as_string();
     menu.elements = readItems<RibbonElement>(node.child("ELEMENTS"), readElement);
-    menu.recentFiles = !node.child("RECENT_FILE_LIST").empty();
+    menu.recentFilesText = node.select_node("RECENT_FILE_LIST/LABEL").node().text().as_string();
     return menu;
 }
 
 static RibbonPanel readPanel(pugi::xml_node node)
 {
     RibbonPanel panel;
-    panel.name = node.child("NAME").text().as_string();
+    panel.text = node.child("NAME").text().as_string();
     panel.keys = node.child("KEYS").text().as_string();
     panel.elements = readItems<RibbonElement>(node.child("ELEMENTS"), readElement);
     return panel;
@@ -220,7 +233,7 @@ static RibbonPanel readPanel(pugi::xml_node node)
 static RibbonCategory readCategory(pugi::xml_node node)
 {
     RibbonCategory category;
-    category.name = node.child("NAME").text().as_string();
+    category.text = node.child("NAME").text().as_string();
     category.keys = node.child("KEYS").text().as_string();
     category.smallImage = node.select_node("IMAGE_SMALL/ID/NAME").node().text().as_string();
     category.largeImage = node.select_node("IMAGE_LARGE/ID/NAME").node().text().as_string();

src/rccore/ribbon.h

@@ -25,6 +25,7 @@ struct RibbonElement
     Q_PROPERTY(int smallIndex MEMBER smallIndex)
     Q_PROPERTY(int largeIndex MEMBER largeIndex)
     Q_PROPERTY(QVector<RcCore::RibbonElement> elements MEMBER elements)
+    Q_PROPERTY(bool isSeparator READ isSeparator)
 
 public:
     QString type;
@@ -42,12 +43,12 @@ bool operator==(const RibbonElement &lhs, const RibbonElement &rhs);
 struct RibbonPanel
 {
     Q_GADGET
-    Q_PROPERTY(QString name MEMBER name)
+    Q_PROPERTY(QString text MEMBER text)
     Q_PROPERTY(QString keys MEMBER keys)
     Q_PROPERTY(QVector<RcCore::RibbonElement> elements MEMBER elements)
 
 public:
-    QString name;
+    QString text;
     QString keys;
     QVector<RibbonElement> elements;
 
@@ -57,14 +58,14 @@ struct RibbonPanel
 struct RibbonCategory
 {
     Q_GADGET
-    Q_PROPERTY(QString name MEMBER name)
+    Q_PROPERTY(QString text MEMBER text)
     Q_PROPERTY(QString keys MEMBER keys)
     Q_PROPERTY(QString smallImage MEMBER smallImage)
     Q_PROPERTY(QString largeImage MEMBER largeImage)
     Q_PROPERTY(QVector<RcCore::RibbonPanel> panels MEMBER panels)
 
 public:
-    QString name;
+    QString text;
     QString keys;
     QString smallImage;
     QString largeImage;
@@ -91,17 +92,17 @@ struct RibbonContext
 struct RibbonMenu
 {
     Q_GADGET
-    Q_PROPERTY(QString name MEMBER name)
+    Q_PROPERTY(QString text MEMBER text)
     Q_PROPERTY(QString smallImage MEMBER smallImage)
     Q_PROPERTY(QString largeImage MEMBER largeImage)
     Q_PROPERTY(QVector<RcCore::RibbonElement> elements MEMBER elements)
-    Q_PROPERTY(bool recentFiles MEMBER recentFiles)
+    Q_PROPERTY(QString recentFilesText MEMBER recentFilesText)
 public:
-    QString name;
+    QString text;
     QString smallImage;
     QString largeImage;
     QVector<RibbonElement> elements;
-    bool recentFiles = false;
+    QString recentFilesText;
 
     bool operator==(const RibbonMenu &other) const = default;
 };

test_data/tst_rcdocument.qml

@@ -112,22 +112,24 @@ TestCase {
         verify(rcDocument.valid)
 
         let ribbon = rcDocument.ribbon("IDR_RIBBON");
-        verify(ribbon.menu.recentFiles);
-        compare(ribbon.menu.name, "File");
+        compare(ribbon.menu.recentFilesText, "Recent Documents");
+        compare(ribbon.menu.text, "File");
         compare(ribbon.menu.elements.length, 9);
         let newButton = ribbon.menu.elements[1];
         compare(newButton.type, "Button");
         compare(newButton.id, "ID_FILE_NEW");
 
         compare(ribbon.categories.length, 2);
         let homeCategory = ribbon.categories[0];
-        compare(homeCategory.name, "Home");
+        compare(homeCategory.text, "Home");
 
         compare(homeCategory.panels.length, 5);
         let findPanel = homeCategory.panels[3];
-        compare(findPanel.name, "Find/Replace");
+        compare(findPanel.text, "Find/Replace");
         compare(findPanel.keys, "F");
         compare(findPanel.elements.length, 4);
+        let separator = findPanel.elements[1];
+        verify(separator.isSeparator);
 
         compare(ribbon.contexts.length, 1);
     }