diff --git a/doc/devdocs/guidance.md b/doc/devdocs/guidance.md new file mode 100644 index 0000000000..329297cbc5 --- /dev/null +++ b/doc/devdocs/guidance.md @@ -0,0 +1,71 @@ +# Coding Guidance + +## Working With Strings + +In order to support localization **YOU SHOULD NOT** have hardcoded UI display strings in your code. Instead, use resource files to consume strings. + +### For CPP +Use [`StringTable` resource][String Table] to store the strings and resource header file(`resource.h`) to store Id's linked to the UI display string. Add the strings with Id's referenced from the header file to the resource-definition script file. You can use [Visual Studio Resource Editor][VS Resource Editor] to create and manage resource files. + +- `resource.h`: + +XXX must be a unique int in the list (mostly the int ID of the last string id plus one): + +```cpp +#define IDS_MODULE_DISPLAYNAME XXX +``` + +- `StringTable` in resource-definition script file `validmodulename.rc`: + +``` +STRINGTABLE +BEGIN + IDS_MODULE_DISPLAYNAME L"Module Name" +END +``` + +- Use the `GET_RESOURCE_STRING(UINT resource_id)` method to consume strings in your code. +```cpp +#include + +extern "C" IMAGE_DOS_HEADER __ImageBase; + +std::wstring GET_RESOURCE_STRING(IDS_MODULE_DISPLAYNAME) +``` + +### For C# +Use [XML resource file(.resx)][Resx Files] to store the UI display strings and [`Resource Manager`][Resource Manager] to consume those strings in the code. You can use [Visual Studio][Resx Files VS] to create and manage XML resources files. + +- `Resources.resx` + +```xml + + Description to be displayed on UI. + This text is displayed when XYZ button clicked. + +``` + +- Use [`Resource Manager`][Resource Manager] to consume strings in code. +```csharp +System.Resources.ResourceManager manager = new System.Resources.ResourceManager(baseName, assembly); +string validUIDisplayString = manager.GetString("ValidUIDisplayString", resourceCulture); +``` + +In case of Visual Studio is used to create the resource file. Simply use the `Resources` class in auto-generated `Resources.Designer.cs` file to access the strings which encapsulate the [`Resource Manager`][Resource Manager] logic. + +```csharp +string validUIDisplayString = Resources.ValidUIDisplayString; +``` + +## More On Coding Guidance +Please review these brief docs below relating to our coding standards etc. + +* [Coding Style](./style.md) +* [Code Organization](./readme.md) + + +[VS Resource Editor]: https://docs.microsoft.com/en-us/cpp/windows/resource-editors?view=vs-2019 +[String Table]: https://docs.microsoft.com/en-us/windows/win32/menurc/stringtable-resource +[Resx Files VS]: https://docs.microsoft.com/en-us/dotnet/framework/resources/creating-resource-files-for-desktop-apps#resource-files-in-visual-studio +[Resx Files]: https://docs.microsoft.com/en-us/dotnet/framework/resources/creating-resource-files-for-desktop-apps#resources-in-resx-files +[Resource Manager]: https://docs.microsoft.com/en-us/dotnet/api/system.resources.resourcemanager?view=netframework-4.8 \ No newline at end of file diff --git a/doc/images/preview_pane/demo.gif b/doc/images/preview_pane/demo.gif new file mode 100644 index 0000000000..42c9ac8c41 Binary files /dev/null and b/doc/images/preview_pane/demo.gif differ diff --git a/doc/images/preview_pane/markdown.gif b/doc/images/preview_pane/markdown.gif deleted file mode 100644 index 1c0d13549d..0000000000 Binary files a/doc/images/preview_pane/markdown.gif and /dev/null differ diff --git a/src/modules/previewpane/README.md b/src/modules/previewpane/README.md index a1220b8392..ea6855a9ad 100644 --- a/src/modules/previewpane/README.md +++ b/src/modules/previewpane/README.md @@ -1,28 +1,25 @@ -
- -# PowerPreview +# File Explorer + +File Explorer add-ons, right now are just limited to Preview Pane additions for File Explorer. + + +## Preview Pane + +Preview Pane is an existing feature in the File Explorer which shows a lightweight, rich, read-only preview of the file's contents in the view's reading pane. To enable it, you just click the View tab in the ribbon and then click `Preview Pane`. Below is an example of Markdown and Svg files previews in File Explorer with PowerToys. + +![PowerToys Preview Pane Demo](../../../doc/images/preview_pane/demo.gif) + > Adding Custom Preview Handlers to Windows File Explorer Preview Pane. [**Overview**](#overview) · [**Developing**](#Developing) · -[**MSIX Integration**](#Install-With-MSIX) · -[**Contributing »**](#Contributing) -
+[**Installation**](#Installation) · ## Overview -Preview handlers are called when an item is selected to show a lightweight, rich, read-only preview of the file's contents in the view's reading pane. This is done without launching the file's associated application. Figure 1 shows an example of a preview handler that preview a .md file type. Please follow this [documentation](https://docs.microsoft.com/en-us/archive/msdn-magazine/2007/january/windows-vista-and-office-writing-your-own-preview-handlers) to start developing a preview handler, when done, continue with this documentation to learn how to integrate a preview handler into PowerToys. - -
- -
- Mark Down Preview Handler Demo -
Figure 1 : Mark Down Preview Handler Demo
-
- -
+Preview handlers are called when an item is selected to show a lightweight, rich, read-only preview of the file's contents in the view's reading pane. This is done without launching the file's associated application. Please follow this [documentation](https://docs.microsoft.com/en-us/archive/msdn-magazine/2007/january/windows-vista-and-office-writing-your-own-preview-handlers) to start developing a preview handler, when done, continue with this documentation to learn how to integrate a preview handler into PowerToys. ## Developing @@ -215,44 +212,4 @@ In the general settings of the Settings UI, you should be able to disable and en
Figure 3 : Settings UI - General Settings Tab
- - -## Contributing - -### Coding Guidance - -#### Working With Strings - -**YOU SHOULD NOT** have hardcoded strings in your C++ code. Instead, use the following guidelines to add strings to your code. Add the ID of your string to the resource file. XXX must be a unique int in the list (mostly the int ID of the last string id plus one): - -- `resource.h`: - -```cpp -#define IDS_PREVPANE_XYZ_SETTINGS_DISPLAYNAME XXX -``` - -- `powerpreview.rc` under strings table: - -```cpp -IDS_PREVPANE_XYZ_SETTINGS_DISPLAYNAME L"XYZ Preview Handler" -``` - -- Use the `GET_RESOURCE_STRING(UINT resource_id)` method to consume strings in your code. -```cpp -#include - -extern "C" IMAGE_DOS_HEADER __ImageBase; - -std::wstring GET_RESOURCE_STRING(IDS_PREVPANE_XYZ_SETTINGS_DISPLAYNAME) -``` - -#### More On Coding Guidance -Please review these brief docs below relating to our coding standards etc. - -> 👉 If you find something missing from these docs, feel free to contribute to any of our documentation files anywhere in the repository (or make some new ones\!) - - - -* [Coding Style](../../../doc/devdocs/style.md) -* [Code Organization](../../../doc/devdocs/readme.md) - + \ No newline at end of file