New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Qt Quick Controls 2.0 chapter [WIP] #203

Open
wants to merge 33 commits into
base: master
from

Conversation

Projects
None yet
2 participants
@e8johan
Member

e8johan commented Sep 19, 2018

This is work in progress - do not merge!

I've outlined where to add Qt Quick Controls 2.0 references and a general outline for the main chapter on Qt Quick Controls 2.0 and am looking for feedback.

@mitchcurtis

Not sure what kind of review you're after at this stage... probably more high-level, I guess, but I pointed out some grammar issues just in case.

- What controls exist
- How do the styles look
- How to use them on desktop

This comment has been minimized.

@mitchcurtis

mitchcurtis Sep 19, 2018

What kind of content did you have planned for this section?

This comment has been minimized.

@e8johan

e8johan Sep 19, 2018

Member

This is an outline. The contents would answer these questions and introduce the topic.

This comment has been minimized.

@mitchcurtis

mitchcurtis Sep 20, 2018

Yes, I understand that it's an outline, I'm just curious about what you plan on putting here, on a high level.

This comment has been minimized.

@mitchcurtis

mitchcurtis Sep 20, 2018

So the "implementation for desktop" part of the example will cover the "How to use them on desktop" section?

This comment has been minimized.

@e8johan

e8johan Sep 25, 2018

Member

As this is the highlevel introduction, this will be showing how to do something that fits onto a desktop with the controls. E.g. menus and such, and try to contrast that with the next section which will focus more on a device/phone style UI (e.g. one main window vs one document window, stackview vs dialogs, etc).
This will be more of a whirlwind tour, so some code demonstrating the elements and screenshots showing the possibilities. The actual details will be covered more in depth further down.

Show resolved Hide resolved docs/controls/controls.rst Outdated
Introduction to Controls
========================
- What controls exist

This comment has been minimized.

@mitchcurtis

mitchcurtis Sep 19, 2018

I think this should say "Which controls exist". Or maybe "The list of controls" would be better.

This comment has been minimized.

@e8johan

e8johan Sep 19, 2018

Member

This bullet is more of a placeholder for the contents planned. I want to add a set of paragraphs answering this question.

- What controls exist
- How do the styles look
- How to use them on desktop
- How to use them on devices

This comment has been minimized.

@mitchcurtis

mitchcurtis Sep 19, 2018

What does this mean? What will the content be?

This comment has been minimized.

@e8johan

e8johan Sep 19, 2018

Member

Same here, the contents is supposed to address these questions.

- Document Windows (one window per document instance)
- Dialogs (and layouts)
- Nested screens with stack view
- Side-by-side screens with page view

This comment has been minimized.

@mitchcurtis

mitchcurtis Sep 19, 2018

What's this one? Do you have an example image/screenshot? Which concrete types would this use?

This comment has been minimized.

@e8johan

e8johan Sep 19, 2018

Member

These would probably be one sub-section each discussing best practices for setting up these common interaction patterns.

Show resolved Hide resolved docs/qmlstart/qmlstart.rst Outdated
@e8johan

This comment has been minimized.

Member

e8johan commented Sep 19, 2018

Good feedback - thanks!

I'm more after high level feedback on the flow. Does the high level story hold (answering all the bullet questions in this order) and have I covered all the key topics?

@e8johan e8johan changed the title from Qt Quick Controls 2.0 chapter [WIP) to Qt Quick Controls 2.0 chapter [WIP] Sep 19, 2018

@mitchcurtis

This comment has been minimized.

mitchcurtis commented Sep 20, 2018

Good feedback - thanks!

I'm more after high level feedback on the flow. Does the high level story hold (answering all the bullet questions in this order) and have I covered all the key topics?

I think it looks fine.

Some other things that may be worth mentioning when you get to the content stage:

  • Palette support, although not supported for each style yet, might be worth mentioning as the best solution for tweaking colours without overriding whole delegates and hence losing the style.
  • The imagine style would be worth mentioning as a designer-friendly solution for creating a style without having to code.
@e8johan

I introduced this in the Introduction section that I just pushed.

- What controls exist
- How do the styles look
- How to use them on desktop

This comment has been minimized.

@e8johan

e8johan Sep 25, 2018

Member

As this is the highlevel introduction, this will be showing how to do something that fits onto a desktop with the controls. E.g. menus and such, and try to contrast that with the next section which will focus more on a device/phone style UI (e.g. one main window vs one document window, stackview vs dialogs, etc).
This will be more of a whirlwind tour, so some code demonstrating the elements and screenshots showing the possibilities. The actual details will be covered more in depth further down.

.. literalinclude:: src/imageviewer-desktop/main.qml
:lines: 1-6, 10-13, 83-
The ``ApplicationWindow`` consists of four main areas as shown below. The menu bar, tool bar and status bar are usually populated by instances of ``MenuBar``, ``ToolBar`` and ``StatusBar`` controls respectively, while the contents area is where the children of the window goes. Notice that the image viewer application does not feature a status bar, that is why it is missing from the code show here, as well as from the figure above.

This comment has been minimized.

@mitchcurtis

mitchcurtis Sep 27, 2018

StatusBar is a Controls 1 type, so we should leave it out.

Imagine .. image:: assets/style-imagine.png
========= =====================================
.. todo:: Pick a better UI to grab the example screenshot from.

This comment has been minimized.

@mitchcurtis

mitchcurtis Sep 27, 2018

You could probably use the screenshots from the docs if you wanted. E.g.: https://doc.qt.io/qt-5/qtquickcontrols2-material.html

This comment has been minimized.

@e8johan

e8johan Oct 17, 2018

Member

That would imply that the CLA applies to the Qt resources, so I'll leave it for now.

@@ -0,0 +1,86 @@
import QtQuick 2.0
import QtQuick.Controls 2.4
import QtQuick.Dialogs 1.2

This comment has been minimized.

@mitchcurtis

mitchcurtis Sep 27, 2018

I wonder if we should use the dialogs from Qt.labs.platform instead?

This comment has been minimized.

@e8johan

e8johan Oct 17, 2018

Member

I wanted a pure QML solution first, since the labs module requires QtWidgets. I've added a note about this, and there is a separate section on the labs module.

@e8johan

This comment has been minimized.

Member

e8johan commented Oct 14, 2018

I just pushed a final draft. I've not incorporated @mitchcurtis 's comments above - will do so tomorrow. As you can see, the Documentation Window section does not work. I'm considering dropping it for now and reporting a bug on Qt (at least the dialog issues is a bug - the rest has to be fixed in the example).

When using the image viewer you will notice that it uses a non-standard file selector dialog. This makes it look out of place.
The ``Qt.labs.platform`` module can help us solve this. It provides QML bindings to native dialogs such as the file selector, font selector and colour selector. It also provides APIs to create system tray icons, as well as system global menus that sits on top of the screen (e.g. as in OS X). The cost of this is a dependency on the ``QtWidgets`` module.

This comment has been minimized.

@mitchcurtis

mitchcurtis Oct 16, 2018

I think the widgets dependency is only for the fallback dialogs where native support is missing. That doesn't change the fact that it's required, but will help explain why it's necessary.

"Current" -> "Your Statistics"
"Your Statistics" -> "Community Statistics"
The illustration below shows how the *Current* page looks in the application. The title and text come from the page, while the ``PageIndicator`` (the three dots at the bottom) come from ``main.qml``. The page indicator shows the user which page that is currently active, helping when navigating.

This comment has been minimized.

@mitchcurtis

mitchcurtis Oct 16, 2018

Maybe this is just me, but based on the format in the StackView section, I was expecting to see the type of control used mentioned by this point. It would make it nice and consistent, and give it a more.. natural flow. :)

The *Back* button in the side-by-side app.
The back button explicitly sets the ``currentIndex`` of the ``SwipeView``, returning the user directly to the *Current* page. During each transition between pages the ``SwipeView`` provides a transition, so even when explicitly changing the ``currentIndex`` the user is given a sense of direction.

This comment has been minimized.

@mitchcurtis

mitchcurtis Oct 16, 2018

Based on this section in the docs, we should probably encourage the use of setCurrentIndex() over setting the property directly.

Show resolved Hide resolved docs/controls/controls.rst Outdated
1. File -> New
2. Close new window
3. Opt so save changes (click Yes)
4. The dialog fails to show and the window closes, losing all changes

This comment has been minimized.

@mitchcurtis

mitchcurtis Oct 16, 2018

The save dialog shows for me, but I get lots of errors. Let's switch to labs platform dialogs and I'll try it again.

This comment has been minimized.

@e8johan

e8johan Oct 17, 2018

Member

This works - completing the example and typing more text!

@e8johan

This comment has been minimized.

Member

e8johan commented Oct 17, 2018

@mitchcurtis - thank you for all your review comments. I believe that I've addressed all of them (some with comments). The only discussion that I'm not sure if we can close is the one about using QtQuick.Dialogs before Qt.labs.platform. The text explains why, but it does introduce a Qt Quick Controls 1 dependency, to avoid a QtWidgets dependency.

My proposal is that we merge this as a version 1.0 and improve it later on.

I propose is that we insert this as a new chapter 7, i.e. after Model-View-Delegate but before Canvas Element. The chapter does use models and views, so the order makes sense. It also uses dynamic element instantiations (chapter 13) but I think that we have to treat that as an advanced topic.

Do you agree?

@mitchcurtis

This comment has been minimized.

mitchcurtis commented Oct 17, 2018

Sounds good. I'm not 100% sure how to view the diff with my comments inline so I haven't reviewed the latest changes thoroughly, but we (The Qt Company) can always send pull requests afterwards if something needs fixing.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment