GSoC 2018 - Beginner Mode and Tutorial Creation - Week 9

Posted 1 year ago

This is my weekly update on my Google Summer of Code project. There will be three parts of this blog post: what I did, what had issues, and what is next. Then, I will end it with a question that I need answered for part of the project.

Video example

Take a look at an example of the tours on YouTube.

What I did

  • Added overlay

    • As shown in the video above, I added a gray overlay around the important items. Also, I made the message box appear near the important items. Eventually when the message box is replaced with something that looks better, it should fit in nicely.
  • Add methods of object lookup

    • Before, objects had to be hard-coded in order to be referenced. Now, the objects can be looked up via their object name. Also, the tours can be started by activating specific shortcuts. Depending on how much you want the tour to do, you can create it without every touching the code, only the xml file.
  • Fix the xml

    • I have changed how the xml is handled. It now allows for adding multiple shortcuts, object name references, and event triggers. Below is an example of a tour in xml:
  <Tour name="note-input">
    <Event objectName="note-entry-methods">MouseButtonRelease</Event>
    <Event objectName="pad-note-128">MouseButtonRelease</Event>
    <Event objectName="pad-note-64">MouseButtonRelease</Event>
    <Event objectName="pad-note-32">MouseButtonRelease</Event>
    <Event objectName="pad-note-16">MouseButtonRelease</Event>
    <Event objectName="pad-note-8">MouseButtonRelease</Event>
    <Event objectName="pad-note-4">MouseButtonRelease</Event>
    <Event objectName="pad-note-2">MouseButtonRelease</Event>
    <Event objectName="pad-note-1">MouseButtonRelease</Event>
    <Event objectName="note-breve">MouseButtonRelease</Event>
    <Event objectName="note-longa">MouseButtonRelease</Event>
    <Event objectName="pad-dot">MouseButtonRelease</Event>
    <Event objectName="pad-dotdot">MouseButtonRelease</Event>
    <Event objectName="pad-dot3">MouseButtonRelease</Event>
    <Event objectName="pad-dot4">MouseButtonRelease</Event>
    <Event objectName="tie">MouseButtonRelease</Event>
    <Event objectName="pad-rest">MouseButtonRelease</Event>
    <Event objectName="flip">MouseButtonRelease</Event>
    <Event objectName="sharp2">MouseButtonRelease</Event>
    <Event objectName="sharp">MouseButtonRelease</Event>
    <Event objectName="nat">MouseButtonRelease</Event>
    <Event objectName="flat">MouseButtonRelease</Event>
    <Event objectName="flat2">MouseButtonRelease</Event>
    <Event objectName="voice">MouseButtonRelease</Event>
    <Message>
      <Text>This is the note input toolbar</Text>
      <Widget>entry-tools</Widget>
      </Message>
    <Message>
      <Text>To get started, click the note input icon. Or you can press "N".</Text>
      <Widget>note-entry-methods</Widget>
      </Message>
    <Message>
      <Text>You can select a duration to add by clicking one of these icons.</Text>
      <Widget>pad-note-128</Widget>
      <Widget>pad-note-64</Widget>
      <Widget>pad-note-32</Widget>
      <Widget>pad-note-16</Widget>
      <Widget>pad-note-8</Widget>
      <Widget>pad-note-4</Widget>
      <Widget>pad-note-2</Widget>
      <Widget>pad-note-1</Widget>
      <Widget>note-breve</Widget>
      <Widget>note-longa</Widget>
      <Widget>pad-dot</Widget>
      <Widget>pad-dotdot</Widget>
      <Widget>pad-dot3</Widget>
      <Widget>pad-dot4</Widget>
      </Message>
    <Message>
      <Text>To enter rests, select this icon and a duration.</Text>
      <Widget>pad-rest</Widget>
      </Message>
    <Message>
      <Text>Accidentals can be added to notes by selecting these icons.</Text>
      <Widget>sharp2</Widget>
      <Widget>sharp</Widget>
      <Widget>nat</Widget>
      <Widget>flat</Widget>
      <Widget>flat2</Widget>
      </Message>
    <Message>
      <Text>To change voices, click these number icons.</Text>
      <Widget>voice</Widget>
      </Message>
    </Tour>

What had issues

  • Overlay displaying over hidden widgets
    • The overlay will occasionally highlight objects that can't be seen by the user. While I tried using a "visibleRegion" method, it didn't work for selecting higher level widgets like QDockWidgets because it doesn't highlight any child widgets.

What is next

  • Writing up a forum post
    • I was going to for this blog post create a full guide to create a tour but decided it made more sense to use the forums for that. I will have that up shortly.
  • Moving tourList out of the compiled files
    • Currently, tourList.xml is compiled into the file. Instead, it should be referenced somewhere else. This way, people who want to make tests don't have to recompile the code every time. See the question for the week for more information.
  • Clean up and PR
    • Self explanatory

Question for the Week

I have to move the tourList out of the compiled files. I was wondering at the same time:
Should the tours be one giant file "tourList.xml"? Or should I create a directory to put individual tour files in? So, multiple named tours (e.g. "noteEntryTour.xml", "paletteTour.xml", etc.) in one folder.

Thanks,

Joshua Bonn
Github: JoshuaBonn1
Current Branch: startup-tour


Comments

This is great!

I wouldn't spend too much time on a user guide because the syntax may yet change, but definitely, let's get this in front of some more eyes via the forum.

As for the XML file, I do like the idea of splitting it into separate files, seems more manageable. Maybe we should consider adding a "help" folder to the distribution, and placing the files there, along with perhaps any other online help we end up providing.