\nToolButton {\n WalkerItem.description: qsTr("Description of the element")\n WalkerItem.weight: 104\n}\n<\/pre><\/div>\n\n\nAdd the UI walker<\/h2>\n\n\n\n Currently, you have to add one item. It should have the size of the whole window.\nThis item provides several properties in order to help you manage the output. <\/p>\n\n\n\n
Properties:<\/p>\n\n\n\nname<\/th> description<\/th> type<\/th><\/tr><\/thead> count<\/td> Total number of highlighted Item<\/td> int<\/td><\/tr> current<\/td> Index of the current highlighted item<\/td> int<\/td><\/tr> currentDesc<\/td> Description of the current item<\/td> QString<\/td><\/tr> dimColor<\/td> Color which hides the rest of the application<\/td> QColor<\/td><\/tr> dimOpacity<\/td> Opacity of the dim<\/td> qreal<\/td><\/tr> availableRect<\/td> Biggest Rectangle (where text can be displayed).<\/td> QRectF<\/td><\/tr> borderRect<\/td> Rect of the current highlighted item<\/td> QRectF<\/td><\/tr> interval<\/td> Define the time interval on each highlighted item<\/td> int<\/td><\/tr> active<\/td> True when the Walker is displayed<\/td> bool<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\nHere is an example:<\/p>\n\n\n
\n WalkerItem {\n id: walker\n anchors.fill: parent\n visible: false\n dimOpacity: 0.8\n\n onActiveChanged: {\n \/\/walker.active\n }\n \n Label {\n id: label\n\n \n text: walker.currentDesc \/\/ text from walker\n x: walker.availableRect.x \/\/ calculated position\n y: walker.availableRect.y \/\/ calculated position\n width: walker.availableRect.width \/\/ calculated position\n height: walker.availableRect.height \/\/ calculated position\n }\n \n Rectangle {\n x: walker.borderRect.x-2\n y: walker.borderRect.y-2\n width: walker.borderRect.width+4\n height: walker.borderRect.height+4\n border.color: "red"\n color: "transparent"\n radius: 10\n border.width: 4\n }\n\n ToolButton {\n icon.source: walker.current + 1 === walker.count ? "qrc:\/finish.svg" : "qrc:\/next.svg"\n \n onClicked:{\n if(walker.current +1 === walker.count)\n walker.skip()\n else\n walker.next()\n } \n }\n}\n\n<\/pre><\/div>\n\n\nReact on Highlight event<\/h3>\n\n\n\n Highlighted items get notified through two signals: enter<\/code> and exit<\/code>. \nDefining signal handlers allow you to react. So you can show the full workflow to add new data.<\/p>\n\n\n\nTextField {\n id: nameField\n \/\/ \u2026\n WalkerItem.description: qsTr("Set macro name.")\n WalkerItem.weight: 30\n WalkerItem.onEnter: {\n nameField.text = qsTr("Skill Roll")\n }\n}\n\n<\/pre><\/div>\n\n\nStart it !<\/h3>\n\n\n\n In order, to start the UI tour, you simply have to call the function: start()<\/code> of the Item.\nOf course, it is up to you to trigger it automatically when it’s the first start of the application or if the user asked for the tour.<\/p>\n\n\n\nHere you have an example:<\/p>\n\n\n
\nComponent.onCompleted: {\n if(DiceMainController.uiTour === DiceMainController.UnDone) {\n walker.start()\n }\n}\n\n<\/pre><\/div>\n\n\nI have a CPP controller with property UiTour<\/code> which gives the current status of the tour.\nHere, I call directly the walker function. But it may be safer to call a function to reset the state of the window.<\/p>\n\n\n\nNavigation<\/h3>\n\n\n\n The walker provides two important function next()<\/code> and previous()<\/code> to navigate. \nBasically on the walker, you can add buttons in the available Rect<\/strong> to manage the navigation. <\/p>\n\n\n\nOther option, you can define an interval in milliseconds which will call the next()<\/code> function.<\/p>\n\n\n\nYou have to make sure the item is visible while the walker highlight it. It could be tricky to make the path from the end to be beginning. In some case, it is easier to never use the previous<\/code> function. <\/p>\n\n\n\nFinish it!<\/h3>\n\n\n\n Calling the function skip()<\/code>, close the walker. Then the application is displayed normally.\nIt can be called at any time. <\/p>\n\n\n\nCheat code<\/h3>\n\n\n\nFunction<\/th> description<\/th><\/tr><\/thead> start()<\/td> The walker becomes visible, and the first item is highligthed<\/td><\/tr> next()<\/td> Highlight the next item, trigger appropriated signals<\/td><\/tr> previous()<\/td> Highlight the previous item, trigger appropriated signals<\/td><\/tr> skip()<\/td> Hide the walker<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\nHow it works ?<\/h2>\n\n\n\nThe attached properties<\/h3>\n\n\n\n In order to harvest all data from the QML, I had to define attached property. <\/p>\n\n\n\n
This is the definition of QObject which will be attached, each time a QML item has defined any Walker property.<\/p>\n\n\n
\nclass WalkerAttachedType : public QObject\n{\n Q_OBJECT\n Q_PROPERTY(QString description READ description WRITE setDescription NOTIFY descriptionChanged FINAL)\n Q_PROPERTY(int weight READ weight WRITE setWeight NOTIFY weightChanged FINAL)\n QML_ANONYMOUS\npublic:\n explicit WalkerAttachedType(QObject* parent= nullptr);\n \/\/\u2026\nsignals:\n void enter();\n void exit();\n \/\/\u2026\n};\n\n<\/pre><\/div>\n\n\nIn the WalkerItem.h, I have to create this static function.<\/p>\n\n\n
\n \/\/ \u2026\n Q_OBJECT\n QML_ATTACHED(WalkerAttachedType)\n \/\/ \u2026\n static WalkerAttachedType* qmlAttachedProperties(QObject* object)\n {\n QQuickItem* item= qobject_cast<QQuickItem*>(object);\n if(!item)\n qDebug() << "Walker must be attached to an Item";\n s_items.append(item);\n return new WalkerAttachedType(object);\n }\n\n<\/pre><\/div>\n\n\nQSceneGraph and Nodes<\/h3>\n\n\n\n WalkreItem<\/code> defines a QML item, written in cpp<\/strong> to be light-weighted. \nI used QSGNode<\/code> to draw it on screen. The item code manages the logic of the walkthrough and the update of the geometry.<\/p>\n\n\n\nTo make it short, the SceneGraph is the rendering engine of QML. QSGNode<\/strong> defines an API to communicate with it directly.<\/p>\n\n\n\nFirst, I create the QML item in cpp, using QSGNode to be rendered.<\/p>\n\n\n
\n\/\/walkeritem.h\nclass WalkerItem : public QQuickItem\n{\n Q_OBJECT\n QML_ATTACHED(WalkerAttachedType)\n QML_ELEMENT\n Q_PROPERTY(QString currentDesc READ currentDesc NOTIFY currentChanged FINAL)\n Q_PROPERTY(QColor dimColor READ dimColor WRITE setDimColor NOTIFY dimColorChanged FINAL)\n Q_PROPERTY(qreal dimOpacity READ dimOpacity WRITE setDimOpacity NOTIFY dimOpacityChanged FINAL)\n Q_PROPERTY(QRectF availableRect READ availableRect NOTIFY availableRectChanged FINAL)\n Q_PROPERTY(QRectF borderRect READ borderRect NOTIFY borderRectChanged FINAL)\n Q_PROPERTY(int interval READ interval WRITE setInterval NOTIFY intervalChanged FINAL)\n Q_PROPERTY(bool active READ active NOTIFY activeChanged FINAL)\npublic:\n WalkerItem();\n \n \/\/ accessors, signals, slots\u2026\n\nprotected:\n QSGNode* updatePaintNode(QSGNode*, UpdatePaintNodeData*) override;\/\/ update scenegraph\n};\n\n\n\n\/\/walkeritem.cpp\nWalkerItem::WalkerItem()\/\/ in the constructor\n{\n setFlag(QQuickItem::ItemHasContents);\/\/ must be called\n connect(child, &QQuickItem::widthChanged, this, &WalkerItem::updateComputation);\n connect(child, &QQuickItem::heightChanged, this, &WalkerItem::updateComputation);\n}\n\nvoid WalkerItem::updateComputation()\n{\n \/\/ compute geometry and list any changes that must be sync with the SceneGraph.\n m_change|= WalkerItem::ChangeType::GeometryChanged;\n update();\/\/ call to paint the item\n}\n\nQSGNode* WalkerItem::updatePaintNode(QSGNode* node, UpdatePaintNodeData*)\n{\n auto wNode= static_cast<WalkerNode*>(node);\n if(!wNode)\n {\n wNode= new WalkerNode();\/\/first time\n }\n\n if(m_change & WalkerItem::ChangeType::ColorChanged)\n wNode->updateColor(m_dimColor);\n if(m_change & WalkerItem::ChangeType::GeometryChanged)\n wNode->update(boundingRect(), m_targetRect);\n if(m_change & WalkerItem::ChangeType::OpacityChanged)\n wNode->updateOpacity(m_dimOpacity);\n\n m_change= WalkerItem::ChangeType::NoChanges;\n return wNode;\n}\n\n<\/pre><\/div>\n\n\nWe have here an item with a geometry like any other item (x,y,width, height), we also have a dimColor<\/em> and dimOpacity<\/em>.\nAny time one of these properties change. I have to sync with the QSceneGraph to update either the geometry, the dimColor<\/em> or the dimOpacity<\/em>.\nEach time, one property changes, I stored the type of change in the m_change<\/code> member and I call update()<\/code>.<\/p>\n\n\n\nThe render engine will call my item with the QSGNode reprenting it on the SceneGraph side. \nThen I can call function on my SGNode. When sync is finished I reset the change to NoChange and return the node.<\/p>\n\n\n\n
The updatePaintNode<\/code> can be called with a null node. In this case, you have to create it. It will be the case, the first time. And it could happen later in some cases for optimalization reason.<\/p>\n\n\n\nNow, let see the code of the QSGNode. You have to see the QSGNode as the root item of a tree. Where each node is in charge of representing one aspect of the item: its geometry, its color and its opacity.<\/p>\n\n\n
\n\/\/ header\nclass WalkerNode : public QSGNode\n{\npublic:\n WalkerNode();\n virtual ~WalkerNode();\n void update(const QRectF& outRect, const QRectF& inRect);\n void updateColor(const QColor& dim);\n void updateOpacity(qreal opacity);\n\nprivate:\n QSGOpacityNode m_opacity;\n QSGFlatColorMaterial m_dimMat;\n QSGGeometryNode m_dim;\n};\n\n<\/pre><\/div>\n\n\nIn the constructor, I create each node, and then I define the hierarchy.<\/p>\n\n\n
\nWalkerNode::WalkerNode()\n{\n auto dimGeo= new QSGGeometry(QSGGeometry::defaultAttributes_Point2D(), 0);\n dimGeo->setDrawingMode(QSGGeometry::DrawTriangles);\n dimGeo->allocate(triangleCount * 3);\n\n m_dim.setGeometry(dimGeo);\n m_dim.setMaterial(&m_dimMat);\n m_dimMat.setColor(Qt::black);\n\n m_opacity.setOpacity(0.6);\n\n m_opacity.appendChildNode(&m_dim);\n appendChildNode(&m_opacity);\n\n markDirty(QSGNode::DirtyMaterial | QSGNode::DirtyGeometry | QSGNode::DirtyOpacity);\n}\n\n<\/pre><\/div>\n\n\nHere the final tree:<\/p>\n\n\n\nDefine or Update the geometry<\/h4>\n\n\n\nvoid WalkerNode::update(const QRectF& out, const QRectF& in)\n{\n \/\/ out is the geometry of the window\n \/\/ in is the geometry of the highlighted item\n const auto a= out.topLeft();\n const auto b= in.topLeft();\n const auto c= in.topRight();\n const auto d= out.topRight();\n const auto e= in.bottomRight();\n const auto f= out.bottomRight();\n const auto g= in.bottomLeft();\n const auto h= out.bottomLeft();\n\n {\n auto gem= m_dim.geometry();\n auto vertices= gem->vertexDataAsPoint2D();\n QList<std::array<QPointF, 3>> triangles{{a, b, d}, {b, d, c}, {d, c, f}, {c, f, e},\n {f, e, h}, {e, g, h}, {h, g, a}, {g, a, b}};\n int i= 0;\n for(auto t : triangles)\n {\n vertices[i + 0].set(t[0].x(), t[0].y());\n vertices[i + 1].set(t[1].x(), t[1].y());\n vertices[i + 2].set(t[2].x(), t[2].y());\n i+= 3;\n }\n\n m_dim.markDirty(QSGNode::DirtyGeometry | QSGNode::DirtyMaterial);\n }\n\n markDirty(QSGNode::DirtyGeometry | QSGNode::DirtyMaterial);\n}\n\n<\/pre><\/div>\n\n\nWe split the surface we have to cover in triangles.<\/p>\n\n\n\nTodo<\/h2>\n\n\n\n\nAnimations: Smooth animation while transiting from one item to another.<\/li>\n\n\n\n Test on bigger apps<\/li>\n\n\n\n Find a logic to allow previous<\/li>\n\n\n\n Use shader effect to make it better.<\/li>\n\n\n\n Other\u2026<\/li>\n<\/ol>\n\n\n\nConclusion:<\/h2>\n\n\n\n UiWalker is already in production. It works like a charm. I hope to use it elsewhere. Then, I will add some new features. Contributions and comments are welcomed.<\/p>\n\n\n\n
Hope you find this article interesting.<\/p>\n","protected":false},"excerpt":{"rendered":"
The problem At the first start of an application, user can be a bit confused in front of all of these features, buttons and data. In response to that, we often have a short presentation of each element on the screen. This also presents a typical workflow with the application. First, You need to create […]<\/p>\n","protected":false},"author":1,"featured_media":5072,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_import_markdown_pro_load_document_selector":0,"_import_markdown_pro_submit_text_textarea":"","footnotes":""},"categories":[81],"tags":[88,34,87,89,90,91],"class_list":["post-5115","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-en","tag-cpp","tag-qml","tag-qt6","tag-ui","tag-walker","tag-walkthrough"],"_links":{"self":[{"href":"http:\/\/renaudguezennec.eu\/index.php\/wp-json\/wp\/v2\/posts\/5115","targetHints":{"allow":["GET"]}}],"collection":[{"href":"http:\/\/renaudguezennec.eu\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"http:\/\/renaudguezennec.eu\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"http:\/\/renaudguezennec.eu\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"http:\/\/renaudguezennec.eu\/index.php\/wp-json\/wp\/v2\/comments?post=5115"}],"version-history":[{"count":1,"href":"http:\/\/renaudguezennec.eu\/index.php\/wp-json\/wp\/v2\/posts\/5115\/revisions"}],"predecessor-version":[{"id":5120,"href":"http:\/\/renaudguezennec.eu\/index.php\/wp-json\/wp\/v2\/posts\/5115\/revisions\/5120"}],"wp:featuredmedia":[{"embeddable":true,"href":"http:\/\/renaudguezennec.eu\/index.php\/wp-json\/wp\/v2\/media\/5072"}],"wp:attachment":[{"href":"http:\/\/renaudguezennec.eu\/index.php\/wp-json\/wp\/v2\/media?parent=5115"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"http:\/\/renaudguezennec.eu\/index.php\/wp-json\/wp\/v2\/categories?post=5115"},{"taxonomy":"post_tag","embeddable":true,"href":"http:\/\/renaudguezennec.eu\/index.php\/wp-json\/wp\/v2\/tags?post=5115"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}