Proper Documentation for Beginners

[DibyaXPP]

I am writing detailed documentation for the end users of AUI, with the ultimate goal of achieving maximum developer friendliness.
Since the official documentation is somewhat scarce, I have started writing articles based on examples to document how to use AUI for specific tasks. My goal is to create an easy-to-read and understand guide that covers the entire AUI feature set within the next six months. This effort not only ensures that AUI becomes a practical choice for my future applications instead of Qt but also serves as a go-to guide for beginners. Thanks to @na2axl for helping me figure out certain macros.

I am attaching the first chapter of my documentation, which is still a work in progress. It will contain a [LibreOffice ODT file] for future edits and updates, allowing the community to contribute and improve it collaboratively.

Our First AUI Application.odt
Our First AUI Application.pdf

So far i have figure out
=> Clickable Buttons
=> Check Boxes
=> Radio Buttons
=> Combo Boxes [Done]
=> Text Field
=> List View

Chapters on the above GUI elements will be added within the next week. I still have many other things to figure out, and hopefully, I will get some help along the way. Regardless, the plan is to prevent others—including myself, given my less-than-perfect memory—from going through the same trials and errors I experienced.

[Alex2772]

Hi @DibyaXPP,

Thank you for interest in our project!

Our project definitely lacks good documentation. Unfortunately, I can't do this by myself because I personally will never experience learning curve of AUI, I have never had to learn it for obvious reasons. Thus I need a third party clean vision of AUI and I'm demanding here on growing AUI community.

AUI becomes a practical choice for my future applications instead of Qt

Glad to hear!

Thanks to @na2axl for helping me figure out certain macros.

When someone asks a question about AUI I immediately update documentation so it answers the question I was asked. So, can you share your questions about macros and other questions the documentation lacking answers on? I think it's a good idea to answer your questions in your documentation as well.

I read the attached pdf and I like it! Especially the part describing purpose of a event loop.

AUI's documentation written primarily using markdown, do you mind using markdown as well so we can easily upstream your documentation?

Can you share feedback on https://aui-framework.github.io/master/md_docs_Getting_started_with_AUI.html?

[DibyaXPP]

Hi @Alex2772,

Unfortunately i don't have much knowledge of Markdown, all MD file i wrote until now are very simple one, so don't know how to add level formatting i want.
Let me first complete the documentation, then we can work together upstream to official documentation.

Can you share feedback on https://aui-framework.github.io/master/md_docs_Getting_started_with_AUI.html? => Looks good.

[Alex2772]

I will get some help along the way

Feel free to open issues and ask questions!

[DibyaXPP]

Chapter 1: Covering GUI Builder and Layout Manager is Complete now,
Let me know if i stated any wrong fact after all i am reversing AUI Sample Application.
AUI_Introduction.odt
AUI_Introduction.pdf

[Alex2772]

Chapter 1: Covering GUI Builder and Layout Manager is Complete now, Let me know if i stated any wrong fact after all i am reversing AUI Sample Application. AUI_Introduction.odt AUI_Introduction.pdf

Good! I think the provided code snippets lack proper indentation. You might want to use clang-format to auto-format them.

[DibyaXPP]

I will run code through Clang format for next chapter. Thanks

[DibyaXPP]

@Alex2772 How to get textarea to work? How to capture it's content on a string?

[Alex2772]

@Alex2772 How to get textarea to work? How to capture it's content on a string?

https://aui-framework.github.io/master/classATextArea.html#a270fa624c5bb3301b00c6d5f1e8fc3ca

[DibyaXPP]

@Alex2772 How to get textarea to work? How to capture it's content on a string?

https://aui-framework.github.io/master/classATextArea.html#a270fa624c5bb3301b00c6d5f1e8fc3ca

I have seen that before, next time give me a sample code snippet , like this one but that work.
Plus proper explanation for Scroll Area builder is needed, documenting how to use it
AScrollArea::Builder().withContents(_new<ATextArea>() let { connect(it->textChanged, this, [this](const AString& changed) { std::cout << "Text changed: " << changed << std::endl; }); }).build()

With above code i am getting following error
'textChanged': is not a member of 'ATextArea'
'AObject::connect': no matching overloaded function found

[Alex2772]

Hm, it's strange because ATextArea does have textChanged member. Moreover, it's relatively old.

Which compiler do you use?

As for example, I took AScrollArea + ATextArea boilerplate from aui.example.views and slightly modified it:

AScrollArea::Builder()
        .withContents(_new<ATextArea>(
            "AUI Framework - Declarative UI toolkit for modern C++20\n"
            "Copyright (C) 2020-2024 Alex2772 and Contributors\n"
            "\n"
            "SPDX-License-Identifier: MPL-2.0\n"
            "\n"
            "This Source Code Form is subject to the terms of the Mozilla "
            "Public License, v. 2.0. If a copy of the MPL was not distributed with this "
            "file, You can obtain one at http://mozilla.org/MPL/2.0/.") let {
                connect(it->textChanged, this, [this](const AString& changed) {
                    std::cout << "Text changed: " << changed << std::endl;
                });
            })
        .build()
    with_style { ass::Expanding() } << ".input-field" ,

• textChanged emits signal when ATextArea loses focus. To receive on per-key-press basis, use textChanging signal.
• both ATextArea and AScrollArea don't have visual appearance by default. I have added ".input-field" on scroll area (not text area!) in order to make it appear like a text field.
• I've set it->setExpanding(); on a scroll area. Without it, AScrollArea will occupy space by its contents, i.e., it basically would not work. This behaviour is intentional, however.
• You can use ass::MaxSize(300_dp) instead of ass::Expanding() to cap the size of AScrollArea to 300dp. If its contents are smaller, it would shrink.

[DibyaXPP]

Which compiler do you use? => Microsoft Visual Studio Community 2022 (64-bit) - Current
Version 17.12.2
set C++ version to 20, but same problem

One more will you in future allow using CLang CL in Visual Studio? [Have better C++ 23 Support]
I need textChanged or something equivalent of that working.
I want to make a Notepad Clone as a demo

Update: with your boilar plate code i am getting same error
Thanks for detailed reply

[Alex2772]

Can you update to the latest version?

using CLang CL in Visual Studio?

I will not make any restrictions on using it, however, there's should be proper support from aui.boot side.

[DibyaXPP]

Can you update to the latest version? => I will

[Alex2772]

@DibyaXPP hi, any updates?

[DibyaXPP]

@Alex2772

Still same error,
'textChanged': is not a member of 'ATextArea'
'AObject::connect': no matching overloaded function found

I will make a new fresh project. don't know what happening, updated to latest Visual Studio 2022

[Alex2772]

@Alex2772

Still same error, 'textChanged': is not a member of 'ATextArea' 'AObject::connect': no matching overloaded function found

I will make a new fresh project. don't know what happening, updated to latest Visual Studio 2022

Just curious, do you use aui.boot? Which version have you specified?

[DibyaXPP]

I just uused official CMAKE Script

# Standard routine
cmake_minimum_required(VERSION 3.16)
project(aui_app)


# Tip: in a production project don't use branch name, use a specific name tag (i.e. v1.1.1),
# but for a sandbox project branch name is perfectly enough
set(AUI_VERSION master)

# Use AUI.Boot
file(
        DOWNLOAD
        https://raw.githubusercontent.com/aui-framework/aui/${AUI_VERSION}/aui.boot.cmake
        ${CMAKE_CURRENT_BINARY_DIR}/aui.boot.cmake)
include(${CMAKE_CURRENT_BINARY_DIR}/aui.boot.cmake)

# import AUI
auib_import(aui https://github.com/aui-framework/aui
        COMPONENTS core views
        VERSION ${AUI_VERSION})


# Create the executable. This function automatically links all sources from the src/ folder,
# creates CMake target and places the resulting executable to bin/ folder.
aui_executable(${PROJECT_NAME})

# Link required libs
aui_link(${PROJECT_NAME} PRIVATE aui::core aui::views)

[Alex2772]

Can you specify latest release, i.e. v6.2.0 instead of master?

set(AUI_VERSION v6.2.1)

auib_import can't track updates on branch, so it's generally recommended to use tags instead.

[Alex2772]

@DibyaXPP hi 👋

How it's going? Have you tried the suggested version?

[DibyaXPP]

This time it compiled but failed to run

        .withContents(_new<ATextArea>(
            "AUI Framework - Declarative UI toolkit for modern C++20\n"
            "Copyright (C) 2020-2024 Alex2772 and Contributors\n"
            "\n"
            "SPDX-License-Identifier: MPL-2.0\n"
            "\n"
            "This Source Code Form is subject to the terms of the Mozilla "
            "Public License, v. 2.0. If a copy of the MPL was not distributed with this "
            "file, You can obtain one at http://mozilla.org/MPL/2.0/.") let {
                connect(it->textChanged, this, [this](const AString& changed) {
                    std::cout << "Text changed: " << changed << std::endl;
                });
            })
        .build()
    with_style { ass::Expanding() } << ".input-field" 

With your code, now it compiles but got error

Similar error with my old simple text area code

Sorry for Being late, i was busy with my University

[Alex2772]

This time it compiled but failed to run

        .withContents(_new<ATextArea>(
            "AUI Framework - Declarative UI toolkit for modern C++20\n"
            "Copyright (C) 2020-2024 Alex2772 and Contributors\n"
            "\n"
            "SPDX-License-Identifier: MPL-2.0\n"
            "\n"
            "This Source Code Form is subject to the terms of the Mozilla "
            "Public License, v. 2.0. If a copy of the MPL was not distributed with this "
            "file, You can obtain one at http://mozilla.org/MPL/2.0/.") let {
                connect(it->textChanged, this, [this](const AString& changed) {
                    std::cout << "Text changed: " << changed << std::endl;
                });
            })
        .build()
    with_style { ass::Expanding() } << ".input-field" 

With your code, now it compiles but got error

Similar error with my old simple text area code

Sorry for Being late, i was busy with my University

Please cleanup dlls in build directory.

[DibyaXPP]

what you mean by cleanup? Delete them?

[Alex2772]

what you mean by cleanup? Delete them?

Exactly. Looks like aui.boot didn’t update them.

[DibyaXPP]

It is working now Thanks,

[Alex2772]

@DibyaXPP hi 👋,

Do you have any updates? Please let me know if you encounter issues.

[DibyaXPP]

Sorry i am bit busy with my academic affairs, once done i will be back documenting, please wait till 20th of feb