MuseScore/mscore/widgets

Widgets

The files in this directory define drop-in replacements for Qt's built-in widgets. These can be used in QtCreator's Design mode (i.e. in .ui files) or in ordinary .h and .cpp source files.

When to use

Consider using or adapting these widgets if you can rather than creating your own. Doing this has the following benefits:

• Saves time and effort
• Easier to maintain
• Ensures consistency in design
• Reduces MuseScore's size and memory footprint
• Benefit from extra features that you may not know how to implement yourself (e.g. accessibility).

If none of the existing widgets suit your particular need then consider creating your own and adding it to this directory. You can use one of the existing ones as a template, and even inherit from it if appropriate. Try to give the functions and classes names that are as generic as possible. Make sure you add comments where appropriate to help other people understand how to use the widgets, and to provide any details about the implementation that are not immediately obvious from the code.

Example

searchbox.h defines SearchBox, a drop-in replacement for a QLineEdit, and filterabletreeview.h defines FilterableTreeView, which is a drop-in replacement for a QTreeView. When used together, these classes allow you to create a tree view to display hierarchical lists of items (e.g. books grouped by genre) and use the line edit to search in the view.

You can use SearchBox and FilterableTreeView inside any of MuseScore's .ui files like this:

1. Open the UI file (e.g. startcenter.ui) in Qt Creator's Design mode.
2. Drag an instance of each of the base classes (QLineEdit and QTreeView) onto the canvas (or find an existing instance).
3. Right-click the QLineEdit, choose "Promote to...", and enter the following:
   • Promoted class name: Ms::SearchBox (Ms is the namespace)
   • Header file: widgets/searchbox.h
4. Now do the same for the QTreeView:
   • Promoted class name: Ms::FilterableTreeView
   • Header file: widgets/filterabletreeview.h
5. Find the widgets' object names in the properties panel on the right.
   • These are the names you will use to refer to the widgets in the code.
   • Defaults are treeView and lineEdit. You might want to change them to something more easily identifiable (e.g. bookTree and bookSearch).

For many widgets that is all you need to do, but some will require additional setting-up to be done in the UI file's corresponding code files (in this case startcenter.h and startcenter.cpp). Look in those files for the line setupUi(this); and do whatever you have to do immediately after that line. The widget's source files (i.e. searchbox.h, searchbox.cpp, etc.) should tell you what you need to do. In this case, you just need to call the SearchBox's setFilterableView(*view) function with a pointer to the view that you want to search (i.e. bookSearch->setFilterableView(bookTree);).