{"id":105961,"date":"2021-11-24T07:00:00","date_gmt":"2021-11-24T15:00:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/oldnewthing\/?p=105961"},"modified":"2021-11-24T06:52:55","modified_gmt":"2021-11-24T14:52:55","slug":"20211124-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20211124-00\/?p=105961","title":{"rendered":"Appending additional payload to a PROPSHEETPAGE<\/CODE> structure"},"content":{"rendered":"

A not-well-known feature of the common controls property sheet is that you can append your own custom data to the end of the PROPSHEETPAGE<\/code> structure, and the system will carry it around for you.<\/p>\n

The traditional way of setting up a PROPSHEETPAGE<\/code> is to use the lParam<\/code> member to point to a structure containing additional data that is used by the property sheet:<\/p>\n

struct WidgetNameData\r\n{\r\n    HWIDGET widget;\r\n    bool uppercaseOnly;\r\n    int renameCount;\r\n};\r\n\r\nvoid ShowWidgetProperties(HWIDGET widget, HWND hwndOwner)\r\n{\r\n    WidgetNameData nameData;\r\n    nameData.widget = widget;\r\n    nameData.uppercaseOnly = IsPolicyEnabled(Policy::UppercaseNames);\r\n    nameData.renameCount = 0;\r\n\r\n    PROPSHEETPAGE pages[1] = {};\r\n\r\n    pages[0].dwSize = sizeof(pages[0]);\r\n    pages[0].hInstance = g_hinstThisDll;\r\n    pages[0].pszTemplate = MAKEINTRESOURCE(IDD_WIDGETNAMEPROP);\r\n    pages[0].pfnDlgProc = WidgetNameDlgProc;\r\n    pages[0].lParam = (LPARAM)&nameData;\r\n\r\n    PROPSHEETHEADER psh = { sizeof(psh) };\r\n    psh.dwFlags = PSH_WIZARD | PSH_PROPSHEETPAGE;\r\n    psh.hInstance = g_hinstThisDll;\r\n    psh.hwndParent = hwndOwner;\r\n    psh.pszCaption = MAKEINTRESOURCE(IDS_WIDGETPROPTITLE);\r\n    psh.nPages = ARRAYSIZE(pages);\r\n    psh.ppsp = pages;\r\n    PropertySheet(&psh);\r\n}\r\n<\/pre>\n
For simplicity, this property sheet has only one page. This page needs a WidgetData<\/code> worth of extra state, so we allocate that state (on the stack, in this case) and put a pointer to int in the PROPSHEETPAGE<\/code>‘s lParam<\/code> for the dialog procedure to fish out:<\/p>\n
INT_PTR CALLBACK WidgetNameDlgProc(\r\n    HWND hdlg, UINT uMsg, WPARAM wParam, LPARAM lParam)\r\n{\r\n    auto pageData = (WidgetNameData*)GetWindowLongPtr(\r\n        hdlg, DWLP_USER);\r\n    switch (uMsg)\r\n    {\r\n    case WM_INITDIALOG:\r\n        {\r\n            auto page = (PROPSHEETPAGE*)lParam;\r\n            pageData = (WidgetNameData*)page->lParam;\r\n            SetWindowLongPtr(hdlg, DWLP_USER, (LONG_PTR)pageData);\r\n\r\n            ... initialize the page ...\r\n            return TRUE;\r\n        }\r\n\r\n    ... other message handlers ...\r\n    }\r\n    return FALSE;\r\n}\r\n<\/pre>\n
For a property sheet dialog procedure, the lParam<\/code> of the WM_INIT\u00adDIALOG<\/code> points to a PROPSHEETPAGE<\/code> structure, and you can pull out the lParam<\/code> to access your private data.<\/p>\n
Now, this gets kind of complicated if the property sheet page was created via Create\u00adProp\u00adSheet\u00adPage<\/code>, say, because it is a plug-in that is added dynamically into an existing widget property sheet.<\/p>\n
HPROPSHEETPAGE CreateWidgetNamePage(HWIDGET widget)\r\n{\r\n    PROPSHEETPAGE page = {};\r\n\r\n    page.dwSize = sizeof(page);\r\n    page.hInstance = g_hinstThisDll;\r\n    page.pszTemplate = MAKEINTRESOURCE(IDD_WIDGETNAMEPROP);\r\n    page.pfnDlgProc = WidgetNameDlgProc;\r\n    page.lParam = (LPARAM)&(what goes here?);\r\n\r\n    return CreatePropertySheetPage(&page);\r\n}\r\n<\/pre>\n
You can’t use a stack-allocated Widget\u00adName\u00adData<\/code> because that will disappear once the Create\u00adWidget\u00adName\u00adPage<\/code> function returns. You probably have to create a separate heap allocation for it, and pass a pointer to the heap allocation as the lParam<\/code>, but now you also need to add a property sheet callback so you can remember to free the data when you get a PSPCB_RELEASE<\/code> callback.<\/p>\n
Exercise<\/b>: Why is WM_DESTROY<\/code> the wrong place to free the data? (Answer below.)<\/p>\n
To avoid this extra hassle, you can use this one weird trick: Append your private data to the PROPSHEETPAGE<\/code>, and the system will carry it around for you.<\/p>\n
struct WidgetNameData : PROPSHEETPAGE<\/span>\r\n{\r\n    HWIDGET widget;\r\n    bool uppercaseOnly;\r\n    int renameCount;\r\n};\r\n\r\nHPROPSHEETPAGE CreateWidgetNamePage(HWIDGET widget)\r\n{\r\n    WidgetNameData<\/span> page = {};\r\n\r\n    page.dwSize = sizeof(page);\r\n    page.hInstance = g_hinstThisDll;\r\n    page.pszTemplate = MAKEINTRESOURCE(IDD_WIDGETNAMEPROP);\r\n    page.pfnDlgProc = WidgetNameDlgProc;\r\n\r\n    \/\/ store the extra data in the extended page\r\n    page.widget = widget;\r\n    page.uppercaseOnly = IsWidgetPolicyEnabled(WidgetPolicy::UppercaseNames);\r\n    page.renameCount = 0;<\/span>\r\n\r\n    return CreatePropertySheetPage(&page);\r\n}\r\n<\/pre>\n
We append the data to the PROPSHEETPAGE<\/code> by deriving from PROPSHEETPAGE<\/code> and adding our extra data to it. The trick is that by setting the page.dwSize<\/code> to the size of the entire larger structure, we tell the property sheet manager that our private data is part of the page. When the property sheet manager creates a page, it copies all of the bytes described by the dwSize<\/code> member into its private storage (referenced by the returned HPROPSHEETPAGE<\/code>), and by increasing the value of page.dwSize<\/code>, we get our data copied there too.<\/p>\n
Recall that the lParam<\/code> parameter to the WM_INIT\u00adDIALOG<\/code> message is a pointer to a PROPSHEETPAGE<\/code>. In our case, it’s a pointer to our custom PROPSHEETPAGE<\/code> structure, and we can downcast to the specific type to access the extra data.<\/p>\n
INT_PTR CALLBACK WidgetNameDlgProc(\r\n    HWND hdlg, UINT uMsg, WPARAM wParam, LPARAM lParam)\r\n{\r\n    auto pageData = (WidgetNameData*)GetWindowLongPtr(\r\n        hdlg, DWLP_USER);\r\n    switch (uMsg)\r\n    {\r\n    case WM_INITDIALOG:\r\n        {\r\n            \/\/ the lParam points to our extended page\r\n            pageData = (WidgetNameData*)lParam;<\/span>\r\n            SetWindowLongPtr(hdlg, DWLP_USER, (LONG_PTR)pageData);\r\n\r\n            ... initialize the page ...\r\n            return TRUE;\r\n        }\r\n\r\n    ... other message handlers ...\r\n    }\r\n    return FALSE;\r\n}\r\n<\/pre>\n
In pictures: The traditional way creates a separate allocation that the PROPSHEETPAGE<\/code>‘s lParam<\/code> points to. When the system copies the PROPSHEETPAGE<\/code> into private storage, the lParam<\/code> is copied with it.<\/p>\n
<\/p>\n\n\n\n\n\n\n\n
 <\/td>\n <\/td>\npassed to Create-<\/code>
\nProp\u00adSheet\u00adPage<\/code><\/td>\n		 <\/td>\n <\/td>\n <\/td>\ncopy passed to
\nWM_INITDIALOG<\/code><\/td>\n<\/tr>\n
dwSize<\/code><\/span><\/td>\n <\/td>\nPROPSHEETPAGE<\/code><\/span><\/td>\ndwSize<\/code>
\ndwFlags<\/code>
\n\u22ee<\/td>\n		 <\/td>\n <\/td>\n <\/td>\nPROPSHEETPAGE<\/code><\/span><\/td>\ndwSize<\/code>
\ndwFlags<\/code>
\n\u22ee<\/td>\n		 <\/td>\ndwSize<\/code><\/span><\/td>\n<\/tr>\n
 <\/td>\nlParam<\/code><\/td>\n\u2192<\/td>\nwidget<\/code><\/td>\n\u2190<\/td>\nlParam<\/code><\/td>\n<\/tr>\n
 <\/td>\n\u22ee<\/td>\n <\/td>\nuppercaseOnly<\/code><\/td>\n <\/td>\n\u22ee<\/td>\n<\/tr>\n
 <\/td>\n <\/td>\n <\/td>\n <\/td>\n <\/td>\nrenameCount<\/code><\/td>\n <\/td>\n <\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
The new way makes the whole thing a giant Widget\u00adName\u00adData<\/code> with a PROPSHEETPAGE<\/code> at the top and bonus data at the bottom.<\/p>\n\n\n\n\n\n
 <\/td>\n <\/td>\npassed to Create-<\/code>
\nProp\u00adSheet\u00adPage<\/code><\/td>\n		\u00a0<\/td>\ncopy passed to
\nWM_INITDIALOG<\/code><\/td>\n<\/tr>\n
dwSize<\/code><\/span><\/td>\n <\/td>\nPROPSHEETPAGE<\/code><\/span><\/td>\ndwSize<\/code>
\ndwFlags<\/code>
\n\u22ee
\nlParam<\/code>
\n\u22ee<\/td>\n		 <\/td>\nPROPSHEETPAGE<\/code><\/span><\/td>\ndwSize<\/code>
\ndwFlags<\/code>
\n\u22ee
\nlParam<\/code>
\n\u22ee<\/td>\n		 <\/td>\ndwSize<\/code><\/span><\/td>\n<\/tr>\n
 <\/td>\n <\/td>\nwidget<\/code>
\nuppercaseOnly<\/code>
\nrenameCount<\/code><\/td>\n		 <\/td>\n <\/td>\nwidget<\/code>
\nuppercaseOnly<\/code>
\nrenameCount<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
The catch here is that the bonus data is copied to the internal storage via memcpy<\/code>, so it must be something like a POD type which can be safely copied byte-by-byte.<\/p>\n
If you didn’t know about this trick, you would wonder why the lParam<\/code> of the WM_INIT\u00adDIALOG<\/code> message points to the full PROPSHEETPAGE<\/code>. After all, without this trick, the only thing you could do with the PROPSHEETPAGE<\/code> pointer was access the lParam<\/code>; all the other fields are explicitly documented as off-limits\u00b9 during the handling of the WM_INIT\u00adDIALOG<\/code> message. Why bother giving you a pointer to a structure where you’re allowed to access only one member? Why not just pass that one member?<\/p>\n
And now you know why: Because you actually can access more than just the lParam<\/code>. If you hung extra data off the end of the PROPSHEETPAGE<\/code>, then that data is there for you too.<\/p>\n
Extending the PROPSHEETPAGE<\/code> structure means that each PROPSHEETPAGE<\/code> can be a different size, which makes it tricky to pass an array of them, which is something you need to do if you’re using the PSH_PROP\u00adSHEET\u00adPAGE<\/code> flag. We’ll look at that problem next time.<\/p>\n
Bonus chatter<\/b>: This is an expansion of  a previous discussion of the same topic<\/a>. In that earlier topic, I said that the array technique requires all of the elements to be the same size. But next time, I’ll show how to create an array of heterogeneous types.<\/p>\n
Bonus bonus chatter<\/b>: This is similar to, but not the same as, the trick of  adding extra information to the end of the OVERLAPPED<\/code> structure<\/a>. In the case of overlapped I\/O, the same OVERLAPPED<\/code> pointer is used; there is no copying. You can therefore put arbitrary complex data after the OVERLAPPED<\/code>; they don’t have to be POD types. Of course, you have to be careful to destruct them properly when the I\/O is complete.<\/p>\n
In the case of a PROPSHEETPAGE<\/code>, the memory is copied, so the data needs to be memcpy<\/code>-safe. You could still use it to hold non-POD types, though, by treating it as uninitialized memory that the system conveniently preallocates for you. You’ll have to placement-construct the objects in their copied location, and manually destruct them when the property sheet page is destroyed.<\/p>\n
Answer to exercise<\/b>: If the property sheet page is never created (because the user never clicks on the tab for the page), then the dialog is never created, and therefore is never destroyed either. In that case, you don’t get any WM_DESTROY<\/code> message, and the memory ends up leaked.<\/p>\n
\u00b9 The documentation cheats a bit and says that you cannot modify anything except for the lParam<\/code>, when what it’s really saying is that you cannot modify any system-defined<\/i> things except for the lParam<\/code>. Your private things are yours, and you can modify them at will.<\/p>\n","protected":false},"excerpt":{"rendered":"
Taking it along for the ride.<\/p>\n","protected":false},"author":1069,"featured_media":111744,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[25],"class_list":["post-105961","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"
Taking it along for the ride.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/105961","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/users\/1069"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/comments?post=105961"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/105961\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media\/111744"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media?parent=105961"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=105961"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=105961"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}