Document restrictions on icon names in the resources in wxMSW.

Make it more clear that application icon must precede "wx" in alphabetical
order.

Closes #3529.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@76450 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/doxygen/mainpages/platdetails.h

@@ -152,6 +152,23 @@ MinGW32 tool chain.
 
 For further information, please see the files in docs/msw in the distribution.
 
+@subsection page_port_wxmsw_resources Resources and Application Icon
+
+All applications using wxMSW should have a Windows resource file (@c .rc
+extension) and this file should include @c include/wx/msw/wx.rc file which
+defines resources used by wxWidgets itself.
+
+Among other things, @c wx.rc defines some standard icons, all of which have
+names starting with the "wx" prefix. This normally ensures that any icons
+defined in the application's own resource file come before them in alphabetical
+order which is important because Explorer (Windows shell) selects the first
+icon in alphabetical order to use as the application icon which is displayed
+when viewing its file in the file manager. So if all the icons defined in your
+application start with "x", "y" or "z", they won't be used by Explorer. To
+avoid this, ensure that the icon which is meant to be used as the main
+application icon has a name preceding "wxICON" in alphabetical order.
+
+
 @subsection page_port_wxmsw_themedborders Themed Borders
 
 Starting with wxWidgets 2.8.5, you can specify the @c wxBORDER_THEME style to

include/wx/msw/wx.rc

@@ -57,8 +57,12 @@ WXCURSOR_CROSS          CURSOR  DISCARDABLE     "wx/msw/cross.cur"
 // Default Icons
 //
 
-// First wx icon in alphabetical order, so it will be used by Explorer if the
+// First wx icon in alphabetical order.
-// application doesn't have any icons of its own
+//
+// Notice that it also may be used by Explorer as the application icon if the
+// main program doesn't define any icons preceding this one in alphabetical
+// order (i.e. any icons defined by it start with "wy", "x", "y"  or "z") in
+// 16*16 or 32*32 sizes.
 wxICON_AAA                      ICON "wx/msw/std.ico"
 
 //wxDEFAULT_FRAME               ICON "wx/msw/std.ico"