[vtk-developers] Re: API Change

[Brad King]

Lorensen, William E (Research) wrote:
> I guess we have different philosophies. I would prefer to protect the large installed base of VTK users and keep the ugliness within VTK itself.

I need to make this more clear.  In the case of a virtual method like 
GetProp that ugliness must be implemented in every subclass that wishes 
to override the method, even in user code!  There is nothing besides 
documentation that tells them they need it, and if they forget it they 
will get strange bugs because sometimes the virtual will be overriden 
and sometimes not depending on whether windows.h was included in the 
calling translation unit.  This API change protects those users from 
such ugliness.  Few people understand how the preprocessor trick works 
but most people understand

#if ...
  ...
#else
  ...
#endif

-Brad

> -----Original Message-----
> From: Brad King [mailto:brad.king at kitware.com]
> Sent: Sunday, September 04, 2005 12:21 PM
> To: Bill Lorensen
> Cc: Sebastien BARRE; will Schroeder; Lorensen, William E (Research)
> Subject: Re: API Change
> 
> 
> Bill Lorensen wrote:
> 
>>I can't follow the reasoning in that thread. Why couldn't AddProp be 
>>retained, just calling AddViewProp? Seems like an arbitrary API change.
> 
> 
> A full explanation of the windows.h change is here:
> 
> http://www.vtk.org/cgi-bin/viewcvs.cgi/Utilities/Upgrading/README.WindowsMangling.txt?rev=HEAD&view=auto
> 
> If AddProp is retained then RemoveProp should be retained too.  In order 
> to retain RemoveProp and work with sources that include windows.h the 
> definition must look like this:
> 
> #ifdef VTK_WORKAROUND_WINDOWS_MANGLE
> # define RemovePropA RemoveProp
> # define RemovePropW RemoveProp
> #endif
>    void RemoveProp(vtkProp*);
> #ifdef VTK_WORKAROUND_WINDOWS_MANGLE
> # undef RemovePropA
> # undef RemovePropW
>    //BTX
>    void RemovePropA(vtkProp*);
>    void RemovePropW(vtkProp*);
>    //ETX
> #endif
> 
> This ugliness is the reason the "Prop" API was deprecated and replaced 
> with the "ViewProp" API.
> 
>  >
>  > I noticed that Viewport's API changed recently. For example AddProp 
> no longer exists. Why was it removed?
>  >  We have code now that needs lines like this:
>  >
>  > #if (VTK_MAJOR_VERSION == 4 && VTK_MINOR_VERSION <= 5)
>  >  foo->AddProp( volume );
>  > #else
>  >  foo->AddViewProp( volume );
>  > #endif
> 
> Unfortunately this is inevitable when an API is deprecated and you want 
> to write code that works with both the old and new version.  You can 
> reduce the number of places that look like that by writing a header with 
> code like this:
> 
> template <class L, class R>
> void myprojAddProp(L l, R r)
> {
> #if VTK_MAJOR_VERSION > 4 || \
>     (VTK_MAJOR_VERSION == 4 && VTK_MINOR_VERSION >= 5)
>   l->AddViewProp(r);
> #else
>   l->AddProp(r);
> #endif
> }
> 
> and then everywhere else just replace
> 
> foo->AddProp(volume)
> 
> with
> 
> myprojAddProp(foo, volume)
> 
> It is up to you whether this is more readable or easier to maintain than 
> your current solution.
> 
> -Brad