Preferences Code Hints

[sprintr]

This PR implements code hints for the preferences we use in brackets. Additionally it also shows a little description of the active preference to the user.

CC:
@redmunds @ryanstewart @MiguelCastillo

[rroshan1]

Glad to see it ready!! 😃

[petetnt]

This is pretty awesome 👍

The data.json and it's description field should be localization/internationalization-enabled and it would be nice if extensions could extend that (most likely by adding an optional description-value for PreferencesManager.definePreference)

PreferencesManager.definePreference("some.preferenceHere", "boolean", true, Strings.some.preferenceHere.description);

edit: Actually, going with the PreferencesManager.definePreference route and baking the values into src/nls/lang/Strings.js would make localization and updating extensions to support PrefsCodeHints a breeze. If the PreferenceManager supplies the descriptions and types, data.json wouldn't be needed at all provided that the descriptions would be added to all the built-in definePreferences.

edit 2: CodeFolding already does this but it's not visibile to UI so the variables are just in the Prefs.js

brackets/src/extensions/default/CodeFolding/Prefs.js

Lines 12 to 41 in 9dfbebe

	var ProjectManager = brackets.getModule("project/ProjectManager"),
	PreferencesManager = brackets.getModule("preferences/PreferencesManager"),
	prefs = PreferencesManager.getExtensionPrefs("code-folding"),
	FOLDS_PREF_KEY = "code-folding.folds",
	// preference key strings are here for now since they are not used in any UI
	ENABLE_CODE_FOLDING = "Enable code folding",
	MIN_FOLD_SIZE = "Minimum fold size",
	MIN_FOLD_SIZE_HELP = "Minimum number of lines to allow in a foldable range",
	SAVE_FOLD_STATES = "Save fold states",
	SAVE_FOLD_STATES_HELP = "Save fold states to disk when editor is closed and restore the folds when reopened",
	ALWAYS_USE_INDENT_FOLD = "Always use indent fold",
	ALWAYS_USE_INDENT_FOLD_HELP = "Fall back to using level of indentation as a folding guideline if no range finder is found for the current mode.",
	HIDE_FOLD_BUTTONS = "Hide fold triangles",
	HIDE_FOLD_BUTTONS_HELP = "Hide fold triangles unless the mouse is over the gutter",
	MAX_FOLD_LEVEL = "Max fold level",
	MAX_FOLD_LEVEL_HELP = "Used to limit the number of nested folds to find and collapse when View -> Collapse All is called or Alt is held down when collapsing. Should improve performance for large files.";
	//default preference values
	prefs.definePreference("enabled", "boolean", true,
	{name: ENABLE_CODE_FOLDING, description: ENABLE_CODE_FOLDING});
	prefs.definePreference("minFoldSize", "number", 2,
	{name: MIN_FOLD_SIZE, description: MIN_FOLD_SIZE_HELP});
	prefs.definePreference("saveFoldStates", "boolean", true,
	{name: SAVE_FOLD_STATES, description: SAVE_FOLD_STATES_HELP});
	prefs.definePreference("alwaysUseIndentFold", "boolean", false,
	{name: ALWAYS_USE_INDENT_FOLD, description: ALWAYS_USE_INDENT_FOLD_HELP});
	prefs.definePreference("hideUntilMouseover", "boolean", false,
	{name: HIDE_FOLD_BUTTONS, description: HIDE_FOLD_BUTTONS_HELP});
	prefs.definePreference("maxFoldLevel", "number", 2,
	{name: MAX_FOLD_LEVEL, description: MAX_FOLD_LEVEL_HELP});

[abose]

refactoring candidate with a for loop.

[abose]

Cancel that, i see that this is just a test file 👍

[abose]

+1
@sprintr Why is this marked as review only?

[sprintr]

@abose Wanted to get some input on this so I marked it review only.

@petetnt Going to add i18n support today. Some preferences have got their own UI, so we don't want to have each and every pref in the code hints. I was thinking about providing an API to extension devs, so they can plug in their hints. Something like PreferencesManager.setHints() and PreferencesManager.getHints() should do the job.

As far as the core brackets preferences, we should use data.json, so translators (who are encouraged to commit on the web) can easily translate descriptions in a single file.

@rroshan1 Glad you liked it. :)

[sprintr]

Added internationalization support, moved all the descriptions to nls/root/strings.js

[marcelgerber]

I'm not too set about adding all these strings to the core nls file, as it's quite a lot of new strings.
Maybe we should consider creating another nls file for this?

[sprintr]

@marcelgerber We can also move it to its own strings.js file. I didn't see any other core extension doing it.

[abose]

I think it would be ok; if not easier to manage in the core file itself. adding js translation files for separate features would eventually decrease the maintainability of translations[as i saw in several other large projects]. For instance you would have to search over several files to find a string const; but with just one file, they are generally easy to locate; also people would need to go through several files to see if some strings changed to figure out translations.

[sprintr]

• Added a new API PreferencesManager.getAllPreferences to return all the preferences defined.
• Added support for preference hinting by third-party extensions using the preferences they have defined. Here is a tiny extension to demonstrate how it can be done.

@abose Is there anything else remaining to cover in this PR?

[petetnt]

Nice 👍

[TomMalbran]

Instead of $.extend for cloning you can use _.clone and _.cloneDeep from lowdash which is already included in the core.

[sprintr]

@abose Can you give this PR a review.

[abose]

@sprintr will do some test with the changes and update by tomorrow 👍
Also if you feel that this PR is good to go, You could remove the [review only] tag .

[abose]

Could this file be moved to the /test/ folder?

[sprintr]

This is a standard practice that most of the core extensions do.

[nethip]

@sprintr Thanks for putting up this PR 👍 Really appreciate it!

I had a small suggestion. I think right now one has to manually go about editing the json file to make sure the preference name, along with its values kind of popup in code hints, while editing the preference file. How about adding another parameter to PreferencesManager.definePreference() that would take the list of preference values, along with the description, as an optional value.

This way extension writers can make sure their extension's preference names and values popup in the code hint.

Also we need to clearly document what needs to be done, going forward, to create a new preference in Brackets core. I was thinking if we can automate the job, but I might sound crazy 😼

[sprintr]

@nethip I wrote a tiny extension to demonstrate how extension authors can plugin their hints. Just modified PreferencesManager.definePreference.

[abose]

@sprintr
250px works very well now :)
I still think that all the preferences that can be configured using the preferences file can be hinted. Maybe we could specify in the wiki or in the hints itself that some preferences need a relaunch of brackets to take effect.

[sprintr]

@abose I am going to do two things tomorrow.

1. Allow all the preferences in code hints.
2. Move the descriptions of preferences to the files where they are defined. So we won't need updating data.json with new prefs in future.

[abose]

@sprintr Right now the scroll-bar fix truncates long code hints. Instead of truncating, if we change the css for .brackets-pref-hints .hint-obj from width: 250px; to min-width 250px ; Then instead of truncating the hint; the popup will take the size of the largest preference variable. The hint description will be wrapped at 250px. This would avoid any truncation and also resolve the layout problems. I think this might be more suited than truncating variable names.

[marcelgerber]

@sprintr LanguageManager actually defines its preferences, so you can modify the code there instead of including them in data.json:

brackets/src/language/LanguageManager.js

Lines 1147 to 1152 in 5d4269c

	pm.definePreference(_EXTENSION_MAP_PREF, "object", {}).on("change", function () {
	_updateFromPrefs(_EXTENSION_MAP_PREF);
	});
	pm.definePreference(_NAME_MAP_PREF, "object", {}).on("change", function () {
	_updateFromPrefs(_NAME_MAP_PREF);
	});

With #11197, pretty much all preferences (except the meta language and path) will be defined.

[sprintr]

@marcelgerber You can now check marquee and exclusion of code hints. for exclusion add exclude: true in the options.

@abose We now have a marquee animation to show code hints longer than the box.

[marcelgerber]

Very nice! I also love the marquee effect

[marcelgerber]

Maybe something more distinct, like excludeFromHints?

[sprintr]

@marcelgerber Removed the width of hint object and it seems we don't need marquee anymore. Can you check it.

[abose]

@sprintr some width jumps are there with just width. If you change it to min-width it will work i think .

[sprintr]

@abose Yeah, it works that way. It only happens where no description is available.

[abose]

Verified. All unit tests passing. Merging.

[abose]

@sprintr Thanks for this awesome contribution 🎉

[sprintr]

@abose Awesome!

[busykai]

@sprintr, great! this is really helpful!

[nethip]

Great collaboration work on this PR! @sprintr @abose Does it make sense to update our existing documentation with the updated usage of definePreference() and also share this as an example?

[abose]

Issue #11200 tracks the doc changes required and hints for the new preferences API
@ryanstewart is reviewing the code hints being shown for preferences.

[nethip]

🆒