New Shortcut Names

• Dec 29, 2018 - 16:37

This is the followup thread for New Shortcut Names. In that thread was the suggestion for the new shortcut names for more readability and efficacy of use. This thread will discuss the solution both from a programmatic and data storage perspective, and is intended for current and future devs.

Thanks to neGjodsbol, he has begun the code that will take a list of the old names with their linked actions, and assign the new shortcut names that we've agreed to be made more user-friendly.
For my part i have re-organized the "list-modules", for lack of a better term, into an Excel spreadsheet, with two goals in mind. First, i wanted to make it easy for the devs to edit and add MuseScore actions and their corresponding shortcuts during ongoing development. When the spreadsheet is saved in the right way, the resulting shortcut.txt file is not very editable, but ready for use by Qt.
Secondly, i wanted to make it easy for the devs to save it in the format Qt expects to find the data. Each list-module in the original file is surrounded by curly braces { } , each enclosed list-module separated by commas, and each item within each list-module also separated by commas. At present there are 11 items (lines) in each list-module.

The workbook which i have attached will make it much easier to add more items in each module as well as add more list-modules, and the devs should understand the syntax that must be followed. I encourage the devs to use this as a data construction aid, but i wanted to explain the spreadsheets in more detail for clarity.
I encourage you to open the attached RenameShortcuts.xls file with Excel, or any of the open-source spreadsheet applications. I know LibreOffice Calc works, and i'm sure OpenOffice Calc will work. The XLS file has no macros, so it is safe. If you have no idea how to use spreadsheets, it might be intimidating, but believe me, it's easy to view and use.

THE WORKSHEETS
The first worksheet ("Latest Revision") is the new one that the devs will edit as changes are made.
The second worksheet — "Original" — is the sheet translated directly from the shortcuts(0).txt file, just for posterity.
The third sheet i've labeled "Future Additions," a compilation of shortcuts i've seen requested on the forums, or shortcuts that may be necessary due to recent changes in MuseScore. These are only suggestions; don't bring these in to the first worksheet as-is because they've not been properly formatted.
The fourth worksheet is basically a help file for future devs who want to edit the shortcuts list.

THE MAIN WORKSHEET
The "Latest Revision" sheet has some easy highlighting, with headings on a frozen row, so you can easily see what each column refers to in each list-module. Each list-module contains the elements of each shortcut and the linked Action. I have hidden the delimiter columns so you easily read the setup.
After listing the .txt file in this spreadsheet, sorting alphabetically, and doing some more testing, i tweaked the new shortcut names a little and altered a couple of categories. I found some errors in my original spreadsheet and corrected those. (I still don't understand the Real-Time edit mode, so those lines may need to be updated.)
I added a category called NOTE_CHORD, and refer to note-chords quite a bit in the Help descriptions. This term was necessary because i needed a reference to the note OR chord segment. I used "note" when referring to a single note within a chord segment. The problem is, "chord" could mean the stemmed series of notes, OR what we call a chord symbol, OR even a fretboard diagram showing how the chord is played. So to avoid confusion for new users, a "note-chord" refers to the stemmed series of notes as a single item.

Now let's look at the lines in the worksheet.
The first line is a header row, but is set with double slashes, so Qt will ignore it. It provides the labels of each column so you can see what they represent.
All delimiters and constants are already set in their own columns in each line. One just needs to set the proper values in each value-driven column. Here is a list of the lettered columns.

B. Scope: The scope that the Action belongs to. I've noticed that there are only 3 — MsWidget::SCORE_TAB, MsWidget:: MAIN_WINDOW, and Ms::MAIN_WINDOW.
D. States: The sublist (delimited by the vertical line | ) of states that the shortcut may be called from (i believe). There are quite a few, but they would be put into this one column.
F. Function name: I believe this is the label of the subroutine that the shortcut will activate. They are all unique and must be defined in code before the shortcut will work, of course.
H. Category: The new field which categorizes the Actions.
J. New name: The new field which names the Action. I believe the QT_TRANSLATE_NOOP function commands Qt to look up the term in the appropriate localized table.
L. Menu label: According to the original table, this field would be the translatable menu item of the Action. But i believe not all of the Actions have a corresponding Menu item.
N. KBSC list: This is the old name that the shortcut was called before the new implementation. It may need to be kept to link the old with the new.
P. What's This?: According to the original module list, this field was supposed to be the help description or perhaps tooltip that would appear when the Help button (What's This) was clicked. But as of 2.3.2 as well as 3.0 beta, i have not found where this help button is, nor have i seen any implementation of this text, even in the Shortcut tab of the Preferences. However, i have included a brief help description for future development (see the Wishlist at the end of this post). For Actions that require an internet connection, the Help field starts with an asterisk, which of course can be modified by the devs later. Furthermore, the developers want to make sure these remarks are perfectly defined (and perfectly translatable) should they implement this text later.
R. Icon: This is the formal label of the picture that's shown on the left of the Action name. This label does not to be present, but if it is, all preceding fields have to be comma-delimited.
T. Shortcut type: This seems to be a label for the scope of the shortcut, either Qt::ApplicationShortcut or Qt::WindowShortcut, if at all.
V. Flags: These are the scope and flag labels (enums?) of the Action. I'm not a Qt programmer; i'm not sure what each flag does.
W and X. Reserved Parameters: These can be used for future shortcut parameters. There are no delimiters while they're not being used.
Z. This field can be used for comments; make sure they start with the double-slash.

The "odd-lettered" columns hold not only the delimiters of each element of the list-module, but also any words found in the same position in each field. Notice the ending delimiter in column Y (25) — the curly brace and the comma , except for the last line, which does not get an ending comma.
By the way, comma delimiters have been added to all rows where columns are not filled in, so that every row has the same number of comma-delimited fields before its ending curly brace. I'm hoping Qt is not going to have a problem with null fields between commas.

Any rows in red are those Actions i found to be problematic. Either i couldn't get them to work or they are obsolete. Any dev that knows how they're supposed to work can still include these in the final save, and modify the help message. Otherwise they should be deleted before saving.

BTW, comments can be saved at the end of each line to which they pertain, in column Z.
Also, some #ifdef directives will need to be added to the final TXT file in their place if you wish to maintain these.

SAVING THE CHANGES
Now of course Qt needs a properly formatted and delimited text file that it can use, so it's important to know what needs to be done after making any edits.

Each row of the spreadsheet holds a single list-module, enclosed in curly braces and each line row (list-module) ending with a comma (except the last one), with all of its elements delimited by commas between each field. The text identifiers (quotes "" ) are part of the delimiting columns, NOT the columns of the text they hold. If you want to get a better view of their syntax, expand these columns.

So, when saving, the spreadsheet editor must save the entire spreadsheet as is, without any additional delimiters, like tabs, spaces, etc. — all the fields in each row, and the ending carriage return of each row, and that's it. I edit my simple spreadsheets with MS Excel 2000 out of habit, but this application can't save it in the way i described.
So you have to use a more modern spreadsheet editor, which can save or export in this way. I did not immediately find the proper save method in Excel 2016. I'm sure there are others, but i use LibreOffice's Calc to open the spreadsheet, then follow these instructions:

  1. Click on File >> Save As...
  2. In the resulting window, click the Save as Type dropdown and choose "Text CSV". This will change the extension, but i believe Qt is expecting to find a file that ends in .txt — you'll need to make sure you have the correct extension as well as filename.
  3. After choosing "Text CSV", the "Edit Filter Settings" checkbox will become enabled. Make sure this is checked, and then click "Save".
  4. You'll receive a warning that you're about to save it outside of the ODF format (unless you've disabled this warning); go ahead and choose "Use Text CSV format".
  5. In the resulting "Export Text File" window, clear the contents of the Field Delimiter; DON'T choose anything from the dropdown — it must be empty.
  6. In the String Delimiter field, clear the contents; make sure you leave it empty.
  7. Make sure only "Save cell content as shown" is checked, then click the OK button.

No matter what spreadsheet editing application you use, the object is to make sure that you save or export it without field or text delimiters, but without a fixed column width. It's advisable to do a cursory check of the resulting shortcut file to make sure it was saved in the proper format.

USING THE SHORTCUTS.TXT FILE
Don't! You won't need to. All shortcut development from now on can be made with this spreadsheet, and exported the proper way for use by Qt. The only thing you need to add are the #ifdef directives at the line they belong to.
If you open the resulting shortcut.txt file (which i've attached as well), you'll see each line has all the components of each linked Action-shortcut, but you will also see no whitespace. This will make it difficult to edit the shortcut file efficiently. That's why you should use the worksheet.

WISHLIST
Here is what i hope can be developed in the near future to further the development of the shortcut list.

  1. I would love for the Shortcut tab in the Preferences window to have a message box that shows the Help descriptions i've included in this worksheet. This would make it easy for new and intermediate users to know exactly what each shortcut does before they set their own keyboard shortcut (KBSC). The text i've set up in the "What's This?" column can be accessed directly, and would be perfect for this feature request.

  2. It would be great to be able to call the Shortcuts tab with a custom shortcut of its own.

  3. The Future Additions worksheet has some very usable Action-shortcuts that can be added. I've included some Help descriptions so the devs can see what i'm thinking about.

  4. Shortcuts could be definable within the Cell Properties window, as well as a chosen Category, so that any palette item can be called with a custom shortcut. Even more, this shortcut will show up in the Shortcut Table along with the other standard shortcuts in the Category that was selected by the user for it (and of course editable from there too).

  5. Others have requested this too, and i'd like to second it (or maybe hundred-and-second it!): Shortcut conflicts should be able to be resolved right in the Shortcut Definition window, or maybe altogether prevented. The same shortcut should be allowed if called in completely different edit modes. For example, you'd be able to use Ctrl-Up to raise an upstem length, and then Ctrl-Up to raise a selected note by one octave, because the edit modes are exclusive and should not step on each other.

    1. Shortcut lists should be saveable, loadable, and maintained for easy transferral between even major MuseScore versions in the future. Several can be included with MuseScore in the download package, so new users can load an entire list without having to customize everything.

CONCLUSION
I hope this helps the developers achieve this Feature Request and as always, discussion is fervently welcome. If any changes need to be made to the workbook, let me know here.

Attachment Size
RenameShortcuts.xls 367 KB
shortcuts.txt 139.41 KB
Categories.txt 220 bytes

Comments

I shouldn't forget to thank the other users/devs for their assistance in understanding some of the facets of MuseScore that i was unsure of.

First I must thank you for the huge work you have done. I can see what your vision is, but I would not be too optimistic on seeing the devs. adopting it.
Most of the information in the shortcut list is really related to the definition of Actions, and to the devs. it may seem much more cumbersome to enter this information into a spreadsheet, rather than just typing it into the source file.

Maybe it has not been clear, but the shortcut.txt file is not used as-is. It is an extract from a C++ source file - shortcut.cpp, so it has to be copy-pasted into that, and replace the existing list.

A more serious problem is the formating. The coding rules for MuseScore requires very specific indentation. In this case the opening curly braces must be indented by 6 blanks, the item lines and the closing brace by a furter 3 blanks.
This is part of the standard, that help devs. to more easily understand the structure of the code.
I hope you may be able to come up with an easy solution for this.

The What's this line is wrongly described in the comment. It is in fact the 'Tool tip'. For those actions that are used in the command lines, you should see it when you hover the mouse over the buttons.
Using this for a 'help text' does not seem the right way forward.
I have considered if the existing description (column N) could be replaces by a help text, but right now I think we should keep it because it wil be shown in the local language, and this will be a help to users until the new names have been translated. Instead we should add an extra item for the 'help text' (a new line 6 just after the new name).

In reply to by neGjodsbol

Good to know. Actually adding extra spaces is not difficult when using a spreadsheet, so that's easy to correct. If all the elements of one Action-Shortcut module must be on different lines, that may be a problem. I'll have to see how that can easily be done.

Concerning the 'Help' text, i looked for these tooltips as well, but i didn't see it when i hovered the mouse. I'll check that again. I can revert those fields to what was in the original file if needed.

Also, i will check the couple of #ifdef directives and add those back in on the spreadsheet. Those can still be included in the spreadsheet before saving. The format we're saving in will not disrupt the spreadsheet's efficiency.

Do you still have an unanswered question? Please log in first to post your question.