Skip to content

Commit

Permalink
[example_powertoy] Remove example_powertoy (#3955)
Browse files Browse the repository at this point in the history 
* Remove example_powertoy

* Address PR comments
  • Loading branch information
@stefansjfw
stefansjfw committed Jun 4, 2020
1 parent e606004 commit f5dc197
Show file tree
Hide file tree
Showing 17 changed files with 11 additions and 744 deletions.
12 changes: 1 addition & 11 deletions PowerToys.sln
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,12 +34,7 @@ Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "runner", "src\runner\runner
EndProject
Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "common", "src\common\common.vcxproj", "{74485049-C722-400F-ABE5-86AC52D929B3}"
EndProject
Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "shortcut_guide", "src\modules\shortcut_guide\shortcut_guide.vcxproj", "{A46629C4-1A6C-40FA-A8B6-10E5102BB0BA}"
ProjectSection(ProjectDependencies) = postProject
{74485049-C722-400F-ABE5-86AC52D929B3} = {74485049-C722-400F-ABE5-86AC52D929B3}
EndProjectSection
EndProject
Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "example_powertoy", "src\modules\example_powertoy\example_powertoy.vcxproj", "{44CC9375-3E6E-4D99-8913-7FB748807EBD}"
Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "ShortcutGuide", "src\modules\shortcut_guide\shortcut_guide.vcxproj", "{A46629C4-1A6C-40FA-A8B6-10E5102BB0BA}"
ProjectSection(ProjectDependencies) = postProject
{74485049-C722-400F-ABE5-86AC52D929B3} = {74485049-C722-400F-ABE5-86AC52D929B3}
EndProjectSection
Expand Down Expand Up @@ -275,10 +270,6 @@ Global
{A46629C4-1A6C-40FA-A8B6-10E5102BB0BA}.Debug|x64.Build.0 = Debug|x64
{A46629C4-1A6C-40FA-A8B6-10E5102BB0BA}.Release|x64.ActiveCfg = Release|x64
{A46629C4-1A6C-40FA-A8B6-10E5102BB0BA}.Release|x64.Build.0 = Release|x64
{44CC9375-3E6E-4D99-8913-7FB748807EBD}.Debug|x64.ActiveCfg = Debug|x64
{44CC9375-3E6E-4D99-8913-7FB748807EBD}.Debug|x64.Build.0 = Debug|x64
{44CC9375-3E6E-4D99-8913-7FB748807EBD}.Release|x64.ActiveCfg = Release|x64
{44CC9375-3E6E-4D99-8913-7FB748807EBD}.Release|x64.Build.0 = Release|x64
{07C389E3-6BC8-41CF-923E-307B1265FA2D}.Debug|x64.ActiveCfg = Debug|x64
{07C389E3-6BC8-41CF-923E-307B1265FA2D}.Debug|x64.Build.0 = Debug|x64
{07C389E3-6BC8-41CF-923E-307B1265FA2D}.Release|x64.ActiveCfg = Release|x64
Expand Down Expand Up @@ -506,7 +497,6 @@ Global
GlobalSection(NestedProjects) = preSolution
{74485049-C722-400F-ABE5-86AC52D929B3} = {1AFB6476-670D-4E80-A464-657E01DFF482}
{A46629C4-1A6C-40FA-A8B6-10E5102BB0BA} = {4574FDD0-F61D-4376-98BF-E5A1262C11EC}
{44CC9375-3E6E-4D99-8913-7FB748807EBD} = {BEEAB7F2-FFF6-45AB-9CDB-B04CC0734B88}
{3BB8493E-D18E-4485-A320-CB40F90F55AE} = {4574FDD0-F61D-4376-98BF-E5A1262C11EC}
{D1D6BC88-09AE-4FB4-AD24-5DED46A791DD} = {4574FDD0-F61D-4376-98BF-E5A1262C11EC}
{F9C68EDF-AC74-4B77-9AF1-005D9C9F6A99} = {D1D6BC88-09AE-4FB4-AD24-5DED46A791DD}
Expand Down
5 changes: 0 additions & 5 deletions doc/devdocs/modules/example_powertoy.md
View file

This file was deleted.

175 changes: 4 additions & 171 deletions doc/devdocs/modules/interface.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,18 +67,6 @@ The returned PowerToy should be in the disabled state. The runner will call the

In case of errors returns `nullptr`.

Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.cpp):

```cpp
extern "C" __declspec(dllexport) PowertoyModuleIface* __cdecl powertoy_create() {
return new ExamplePowertoy();
}

ExamplePowertoy::ExamplePowertoy() {
init_settings();
}
```

## get_name

```cpp
Expand All @@ -87,13 +75,6 @@ virtual const wchar_t* get_name()

Returns the name of the PowerToy, it will be cached by the runner.

Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.cpp):
```cpp
virtual const wchar_t* get_name() override {
return L"Example Powertoy";
}
```
## get_events

```cpp
Expand All @@ -106,17 +87,6 @@ Returns a null-terminated table of the names of the events the PowerToy wants to

A nullptr can be returned to signal that the PowerToy does not want to subscribe to any event.

Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.cpp):

```cpp
virtual const wchar_t** get_events() override {
static const wchar_t* events[] = { ll_keyboard,
win_hook_event,
nullptr };
return events;
}
```
## get_config

```
Expand All @@ -129,44 +99,6 @@ If `buffer` is a null pointer or the buffer size is not large enough sets the re
Returns true if successful.
Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.cpp):
```cpp
virtual bool get_config(wchar_t* buffer, int* buffer_size) override {
HINSTANCE hinstance = reinterpret_cast<HINSTANCE>(&__ImageBase);
// Create a Settings object.
PowerToysSettings::Settings settings(hinstance, get_name());
settings.set_description(L"Serves as an example powertoy, with example settings.");
// Add an overview link to show in the Settings.
settings.set_overview_link(L"https://github.com/microsoft/PowerToys");
// Add a video link to show in the Settings.
settings.set_video_link(L"https://www.youtube.com/watch?v=d3LHo2yXKoY&t=21462");
// Add a bool property with a toggle editor.
settings.add_bool_toggle(
L"test_bool_toggle", // property name.
L"This is what a BoolToggle property looks like", // description or resource id of the localized string.
test_bool_prop // property value.
);
// More settings
...
// Add a custom action property. When using this settings type, the "call_custom_action()" method should be overridden as well.
settings.add_custom_action(
L"test_custom_action", // action name.
L"This is what a CustomAction property looks like", // label above the field.
L"Call a custom action", // button text.
L"Press the button to call a custom action in the Example PowerToy" // display values / extended info.
);
return settings.serialize_to_buffer(buffer, buffer_size);
}
```

## set_config
```cpp
Expand All @@ -175,31 +107,6 @@ virtual void set_config(const wchar_t* config)

After the user has changed the module settings in the Settings editor, the runner calls this method to pass to the module the updated values. It's a good place to save the settings as well.

Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.cpp):
```cpp
virtual void set_config(const wchar_t* config) override {
try {
// Parse the PowerToysValues object from the received json string.
PowerToysSettings::PowerToyValues _values =
PowerToysSettings::PowerToyValues::from_json_string(config);
// Update the bool property.
if (_values.is_bool_value(L"test bool_toggle")) {
test_bool_prop = _values.get_bool_value(L"test bool_toggle");
}
// More settings
...
save_settings();
}
catch (std::exception ex) {
// Improper JSON.
}
}
```

## call_custom_action

```cpp
Expand All @@ -209,31 +116,6 @@ Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.
Calls a custom action in response to the user pressing the custom action button in the Settings editor.
This can be used to spawn custom editors defined by the PowerToy.
Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.cpp):
```cpp
virtual void call_custom_action(const wchar_t* action) override {
try {
// Parse the action values, including name.
PowerToysSettings::CustomActionObject action_object =
PowerToysSettings::CustomActionObject::from_json_string(action);
if (action_object.get_name() == L"test_custom_action") {
// Custom action code to increase and show a counter.
++this->test_custom_action_num_calls;
std::wstring msg(L"I have been called ");
msg += std::to_wstring(this->test_custom_action_num_calls);
msg += L" time(s).";
MessageBox(NULL, msg.c_str(), L"Custom action call.", MB_OK | MB_TOPMOST);
}
}
catch (std::exception ex) {
// Improper JSON.
}
}
```

## enable
```cpp
Expand All @@ -242,14 +124,6 @@ Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.

Enables the PowerToy.

Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.cpp):

```cpp
virtual void enable() {
m_enabled = true;
}
```
## disable

```cpp
Expand All @@ -258,14 +132,6 @@ Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.

Disables the PowerToy, should free as much memory as possible.

Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.cpp):

```cpp
virtual void disable() {
m_enabled = false;
}
```
## is_enabled

```cpp
Expand All @@ -274,13 +140,6 @@ Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.

Returns the PowerToy state.

Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.cpp):

```cpp
virtual bool is_enabled() override {
return m_enabled;
}
```
## signal_event

```cpp
Expand All @@ -294,24 +153,6 @@ The data argument and return value meaning are event-specific:
Please note that some of the events are currently being signalled from a separate thread.
Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.cpp):

```cpp
virtual intptr_t signal_event(const wchar_t* name, intptr_t data) override {
if (wcscmp(name, ll_keyboard) == 0) {
auto& event = *(reinterpret_cast<LowlevelKeyboardEvent*>(data));
// Return 1 if the keypress is to be suppressed (not forwarded to Windows),
// otherwise return 0.
return 0;
} else if (wcscmp(name, win_hook_event) == 0) {
auto& event = *(reinterpret_cast<WinHookEvent*>(data));
// Return value is ignored
return 0;
}
return 0;
}
```
## register_system_menu_helper
```cpp
Expand All @@ -338,14 +179,6 @@ Item name is passed as an argument, so that module can distinguish between diffe
```
Destroy the PowerToy and free all memory.

Sample code from [`the example PowerToy`](/src/modules/example_powertoy/dllmain.cpp):

```cpp
virtual void destroy() override {
delete this;
}
```
## Powertoys system menu helper interface

Interface for helper class responsible for handling all system menu related actions.
Expand Down Expand Up @@ -393,15 +226,15 @@ Process action taken on specific system menu item.

# Code organization

### [`powertoy_module_interface.h`](/src/modules/example_powertoy/powertoy_module_interface.h)
### [`powertoy_module_interface.h`](/src/modules/interface/powertoy_module_interface.h)
Contains the PowerToys interface definition.

### [`powertoy_system_menu.h`](/src/modules/example_powertoy/powertoy_system_module.h)
### [`powertoy_system_menu.h`](/src/modules/interface/powertoy_system_module.h)
Contains the PowerToys system menu helper interface definition.

### [`lowlevel_keyboard_event_data.h`](/src/modules/example_powertoy/lowlevel_keyboard_event_data.h)
### [`lowlevel_keyboard_event_data.h`](/src/modules/interface/lowlevel_keyboard_event_data.h)
Contains the `LowlevelKeyboardEvent` structure that's passed to `signal_event` for `ll_keyboard` events.

### [`win_hook_event_data.h`](/src/modules/example_powertoy/win_hook_event_data.h)
### [`win_hook_event_data.h`](/src/modules/interface/win_hook_event_data.h)
Contains the `WinHookEvent` structure that's passed to `signal_event` for `win_hook_event` events.

5 changes: 0 additions & 5 deletions doc/devdocs/readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -134,11 +134,6 @@ PowerRename is a Windows Shell Context Menu Extension for advanced bulk renaming
### [`Shortcut Guide`](modules/shortcut_guide.md)
The Windows Shortcut Guide, displayed when the WinKey is held for some time.

### _obsolete_ [`example_powertoy`](modules/example_powertoy.md)
An example PowerToy, that demonstrates how to create new ones. Please note, that this is going to become a Visual Studio project template soon.

This PowerToy serves as a sample to show how to implement the [PowerToys interface](/src/modules/interface/) when creating a PowerToy. It also showcases the currently implemented settings.

#### Options

This module has a setting to serve as an example for each of the currently implemented settings property:
Expand Down
0 doc/images/example_powertoy/settings.png → doc/images/settings/example_settings.png
View file
File renamed without changes

0 comments on commit f5dc197

Please sign in to comment.