diff --git a/docs/doxygen/mainpages/const_cpp.h b/docs/doxygen/mainpages/const_cpp.h
index 87fbb66a24..e519d217e5 100644
--- a/docs/doxygen/mainpages/const_cpp.h
+++ b/docs/doxygen/mainpages/const_cpp.h
@@ -194,8 +194,13 @@ Currently the following symbols exist:
 @itemdef{wxHAS_NATIVE_WINDOW, Defined if wxNativeWindow class is available.}
 @itemdef{wxHAS_NOEXCEPT, Defined if the currently used compiler supports C++11 @c noexcept. @c wxNOEXCEPT is defined as this keyword in this case, and as nothing otherwise.}
 @itemdef{wxHAS_NULLPTR_T, Defined if the currently used compiler supports C++11 @c nullptr.}
+@itemdef{wxHAS_IMAGE_RESOURCES, Defined if images can be embedded into the
+    program as resources, i.e. without being defined in the program text
+    itself. This is currently the case for MSW and Mac platforms. This constant
+    is available since wxWidgets 3.1.6.}
 @itemdef{wxHAS_IMAGES_IN_RESOURCES, Defined if <a href="http://en.wikipedia.org/wiki/Resource_(Windows)">
-    Windows resource files</a> or OS/2 resource files are available on the current platform.}
+    Windows resource files</a> resource files are available on the current platform.
+    Usually wxHAS_IMAGE_RESOURCES should be used instead.}
 @itemdef{wxHAS_POWER_EVENTS, Defined if wxPowerEvent are ever generated on the current platform.}
 @itemdef{wxHAS_RADIO_MENU_ITEMS,
         Defined if the current port supports radio menu items (see wxMenu::AppendRadioItem).}
diff --git a/include/wx/gdicmn.h b/include/wx/gdicmn.h
index e29a77627c..a7c3877327 100644
--- a/include/wx/gdicmn.h
+++ b/include/wx/gdicmn.h
@@ -183,10 +183,19 @@ enum wxEllipsizeMode
 // macros
 // ---------------------------------------------------------------------------
 
+// The difference between wxHAS_IMAGES_IN_RESOURCES and wxHAS_IMAGE_RESOURCES
+// is that the former is, historically, only defined under MSW while the latter
+// is also defined under macOS, which uses a different resource concept, and
+// may be also defined for any other ports where images don't need to be
+// embedded into the program text in order to be available during run-time.
 #if defined(__WINDOWS__) && wxUSE_WXDIB
     #define wxHAS_IMAGES_IN_RESOURCES
 #endif
 
+#if defined(wxHAS_IMAGES_IN_RESOURCES) || defined(__WXOSX__)
+    #define wxHAS_IMAGE_RESOURCES
+#endif
+
 /* Useful macro for creating icons portably, for example:
 
     wxIcon *icon = new wxICON(sample);
@@ -256,7 +265,7 @@ enum wxEllipsizeMode
 // resource type and under OS X the PNG file with the specified name must be
 // available in the resource subdirectory of the bundle. Elsewhere, this is
 // exactly the same thing as wxBITMAP_PNG_FROM_DATA() described above.
-#if (defined(__WINDOWS__) && wxUSE_WXDIB) || defined(__WXOSX__)
+#ifdef wxHAS_IMAGE_RESOURCES
     #define wxBITMAP_PNG(name) wxBitmap(wxS(#name), wxBITMAP_TYPE_PNG_RESOURCE)
 #else
     #define wxBITMAP_PNG(name) wxBITMAP_PNG_FROM_DATA(name)
diff --git a/samples/toolbar/toolbar.cpp b/samples/toolbar/toolbar.cpp
index a719a68a1c..f636352703 100644
--- a/samples/toolbar/toolbar.cpp
+++ b/samples/toolbar/toolbar.cpp
@@ -44,12 +44,15 @@
 // resources
 // ----------------------------------------------------------------------------
 
-// Under Windows, PNG files are embedded as resources, see toolbar.rc, but
-// elsewhere we embed them in the program itself. We could also load them
-// during run-time.
+// We don't embed this item in the resources under Mac, so we need to still use
+// the XPM there.
 #ifndef wxHAS_IMAGES_IN_RESOURCES
     #include "../sample.xpm"
+#endif // !wxHAS_IMAGES_IN_RESOURCES
 
+// If PNG files are not available in resources, we need to embed them in the
+// program itself. We could also load them during run-time.
+#ifndef wxHAS_IMAGE_RESOURCES
     #include "bitmaps/new_png.c"
     #include "bitmaps/open_png.c"
     #include "bitmaps/save_png.c"
@@ -67,7 +70,7 @@
     #include "bitmaps/paste_2x_png.c"
     #include "bitmaps/print_2x_png.c"
     #include "bitmaps/help_2x_png.c"
-#endif // !wxHAS_IMAGES_IN_RESOURCES
+#endif // !wxHAS_IMAGE_RESOURCES
 
 enum Positions
 {