Add support for stretchable spaces to wxToolBar.

Stretchable spaces consume all extra toolbar space not allocated to the fixed
size items. They can in particular be used to right-align (some) toolbar tools.

Add and document the new API, change the sample to show it and implement it
for MSW, GTK and OS X/Cocoa.

Also refactor MSW background erasing/repainting code to avoid duplicated calls
to DrawThemeBackground(), call it from a new helper MSWEraseRect() function.

Note that we may want to add support for "invisible" separators, IOW
non-stretchable spaces. This could be easily done for MSW after the changes in
this commit and is supported natively by GTK+ and Cocoa so implementing this
would be trivial if there is any interest.

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

src/common/tbarbase.cpp

@@ -259,11 +259,29 @@ wxToolBarToolBase *wxToolBarBase::AddSeparator()
 
 wxToolBarToolBase *wxToolBarBase::InsertSeparator(size_t pos)
 {
-    return DoInsertNewTool(pos, CreateTool(wxID_SEPARATOR,
-                                           wxEmptyString,
-                                           wxNullBitmap, wxNullBitmap,
-                                           wxITEM_SEPARATOR, NULL,
-                                           wxEmptyString, wxEmptyString));
+    return DoInsertNewTool(pos, CreateSeparator());
+}
+
+wxToolBarToolBase *wxToolBarBase::AddStretchableSpace()
+{
+    return InsertStretchableSpace(GetToolsCount());
+}
+
+wxToolBarToolBase *wxToolBarBase::InsertStretchableSpace(size_t pos)
+{
+    wxToolBarToolBase * const tool = CreateSeparator();
+    if ( tool )
+    {
+        // this is a hack but we know that all the current implementations
+        // don't really use the tool when it's created, they will do it
+        // InsertTool() at earliest and maybe even in Realize() much later
+        //
+        // so we can create the tool as a plain separator and mark it as being
+        // a stretchable space later
+        tool->MakeStretchable();
+    }
+
+    return DoInsertNewTool(pos, tool);
 }
 
 wxToolBarToolBase *wxToolBarBase::RemoveTool(int id)