Hey there, I've been working on adding tours to MuseScore to help teach new users the functionality of MuseScore. Below is a guide on how the tours work and how to add your own. Since this is still in development, these things are subject to change. Check out this YouTube video to see some example tours. To keep track of development, check out my blog.

Adding Tours

A tour is a guide to help showcase or further explain a feature in MuseScore. The tour will display message boxes and highlight components to show off the feature. In order to add a tour, you need to know how the tour mechanics work.

Under the Hood

The tours are stored in a folder located in "share/tours/". When MuseScore is started, the tours are loaded into a list for easy lookup.

There are three ways to activate a tour--one tour can be activated multiple ways:

1. Programatically: the tour starts when a specific point in the code is reached.
2. Attaching: the tour is attached to an object by an event. When the event occurs, the tour begins.
3. Using Shortcuts or Events: the tour is activated whenever the shortcut occurs or the event triggers.

Once the tour starts, it finds any widgets that were listed and creates a gray overlay around them. Next, it attempts to place the message box near the widgets in some way. It makes sure the message box does not go off the screen by "sliding" it back on until it is within the frame. Finally, it displays the message box.

The Steps

Adding a tour is a simple two (or one) step process. The first step is to create the XML for the tour. The second step is to add the tour to the code, if necessary.

Step 1: Create the XML

• Go to the folder "share/tours/"
• Add a file ending in .tour
• Follow the following XML syntax: (Subject to change)

<?xml version="1.0" encoding="UTF-8"?>
<Tour name="tourName"> <!-- Used as lookup for starting tours -->
  <Event objectName="object-name">eventType</Event> <!-- (Optional) Trigger the tour when the object recieves a "QEvent::Type" event -->
  <Event objectName="object-name2">eventType</Event>
  <Shortcut>shortcut-name</Shortcut> <!-- (Optional) Trigger the tour on the shortcut -->
  <Shortcut>shortcut-name2</Shortcut>
  <Message> <!-- Each message is a new msgbox in the tour -->
    <Text>Some message here</Text> <!-- Location of the main text -->
    <Widget>widget-name</Widget> <!-- (Optional) Widgets to highlight, searched via objectName -->
    <Widget>widget-name2</Widget>
    </Message>
  <Message>
    <Text>Another message here</Text>
    <Widget>widget-name3</Widget>
    <Widget>widget-name4</Widget>
    </Message>
  </Tour>

Step 2: Connect the Tour

(See "Under the Hood" for more explanation)

• Programatically
  • Find the spot in the code that should activate the tour
  • Add TourHandler::startTour(tourName) listing the tour name that you put in the XML.
• Attaching
  • Find the object you want to attach to.
  • Select the events you want to trigger the tour on.
  • Make sure you can access mscore
  • Add mscore->tourHandler()->attachTour(objectToAttachTo, event, tourName); listing the tour name that you put in the XML. This usually should be placed near the creation of the object.
    • Example: mscore->tourHanlder()->attachTour(w, QEvent::MouseButtonRelease, "note-input");
• Using Shortcuts or Events
  • You're done! Nothing needs to be added if you are only using shortcuts or events.

Let me know if you have any ideas, suggestions, etc!