Re: [Gtk2hs-devel] analysis of api changes since 0.9.10

[Duncan C. <dun...@wo...>]

On Fri, 2006-11-24 at 13:19 +0000, Axel Simon wrote:
> Duncan,
> 
> with respect to my other mail, I should have said as well that releasing
> with the new TreeList API bit without new Signals means that it reduces
> the effort for a release considerably as we'd hardly change anything.

Yes, I think there should be very little to do either way.

> On Thu, 2006-11-23 at 17:31 +0000, Duncan Coutts wrote:
> > Folks,
> > 
> > I wrote a GHC/Haskell Api diff program some time ago for the 0.9.7 ->
> > 0.9.8 release to give us an overview of the changes. I've updated that
> > slightly so that it still produces sensible output with ghc-6.4.2.
> > 
> > I should get the tool into the darcs repo really.
> 
> Yup! 

:-)

> [..]
> > Some is related to experimental changes with the new tree view api. That
> > needs a bit more thought. I expect that we should revert some of the
> > changes to widgets like the combo box and entry. We can come back to
> > that stuff when we're happy with the new tree list stuff in general.
> 
> Following from my previous message about keeping the new API, I think
> there are a few convenience functions in ComboBox and Entry that don't
> work anymore since we're using our own store. Either we
> 
> a) put them back in using the old store
> b) adapt them to the new store
> c) break user's programs and tell them to wait for next release

I think we've got somewhere between a) and b) currently. We never fully
converted that stuff and tested it I think.

> I think we have b) already, so for instance, I see
> 
> entryCompletionSetTextModel
> :: (TreeModelClass (model String),
> TypedTreeModelClass model)
> 
> => EntryCompletion
> 
> which uses the new TreeList modules. I should check a bit more
> thoroughly, but I think this is already working.

Ok, I've never checked if it actually works.


> > This is internal. I think this was removed during the GInitiallyOwned
> > changes.
> > 
> > Functions removed:
> > buttonXalign
> > buttonYalign
> > 
> > -- Similar renaming, this change could be punted.
> 
> In the light of breaking the API now, we would keep these.

I'm not sure I've actually included this into the darcs repo yet. They
may have only been local changes. In which case I'll not commit them
yet. It's easy to add that later as these are the function names that
the code gen no produces. So we'll spot these changes when next merging
with the code gen output.

> > Functions removed:
> > cairoFontMapNew
> > 
> > -- I think this turned out that it couldn't be bound properly due to
> > memory management issues.
> 
> Yes, I could bind it and leak the memory. That seems to be a reasonable
> compromise.

Na, leave it. If it can't be done sensibly leave it. If someone really
needs it then we can rethink.

> > entryCompletionSetMatchFunc changed from
> >    :: EntryCompletion -> (String -> TreeIter -> IO ()) -> IO ()
> > to :: EntryCompletion -> (String -> TreeIter -> IO Bool) -> IO ()
> > 
> > -- not sure about this generalisation.
> 
> I think this change was due to a bug report. The first function is
> totally useless.

Sure ok. Keep the change.

> > Functions removed:
> > drawingAreaGetDrawWindow
> > drawingAreaGetSize
> 
> > -- Hmm, note sure what's going on here. Perhaps they should be
> > deprecated in favour of the more general versions though not removed.
> > Perhaps this is just because the moved module so the api diff shows it
> > as removed from the original module.
> 
> Yes, I think this is now in Widget. Let's define deprecated substitutes.

Actually these names are still exported from
Graphics.UI.Gtk.Misc.DrawingArea and are just aliases of the widget
versions. We could add deprecated messages.

So the apidiff made it look like they had been removed because they used
to be exported from the Structs.hsc module.

> > comboBoxModel changed from
> >    :: (ComboBoxClass self, TreeModelClass model) => ReadWriteAttr self (Maybe TreeModel) (Maybe model)
> > to :: (ComboBoxClass self, TreeModelClass model) => Attr self (Maybe model)
> > 
> > -- Hmm. Dodgy, this looks like unchecked downcasting to me.
> 
> Isn't this old API? If so, it's all dynamically typed anyway.

But it allows us to cast any TreeModelClass to a specific type. That's a
downcast. The old type was right. You can put in any TreeModelClass
instance but what you get back is just a TreeModel.

> > Functions changed:
> > menuPopup changed from
> >    :: MenuClass self => self -> Event -> IO ()
> > to :: MenuClass self => self -> Maybe (MouseButton, Word32) -> IO ()
> > 
> > -- dunno, not that significant probably.
> 
> This was a change triggered by a bug report. Could probably keep it
> without breaking much.

Sure, keep it.

> > Functions removed:
> > afterInsertText
> > onInsertText
> > 
> > -- dunno which module this is referring to.
> 
> Multiline.TextBuffer maybe? I think these are called to instruct the
> model, so they are not user-land functions.

It got renamed to onBufferInsertText apparently because it clashed with
Entry.onInsertText. Not sure this is ideal.

It might be better to leave it as ambiguous rather than changing the
name. One can use fully qualified names to specify which. We can address
signal naming properly when we do the new signals.

> > -- Axel's change to use Double consistently rather than PangoUnit /
> > PANGO_SCALE. We should definitely keep this change. It's not likely to
> > break that many apps anyway.
> 
> Agreed.

Ok.

> > Functions removed:
> > cellRendererGet
> > cellRendererSet
> > Functions removed:
> > cellBackground
> > cellForeground
> > 
> > -- related to the tree view changes, needs more review.
> 
> I don't know if I finished these for the new TreeList API.

Oh, yes. Sigh. There's all that cell renderer attribute stuff.

> > Functions changed:
> > onEdited changed from
> >    :: TreeModelClass tm => CellRendererText -> tm -> (TreeIter -> String -> IO ()) -> IO (ConnectId CellRendererText)
> > to :: CellRendererTextClass cr => cr -> (TreePath -> String -> IO ()) -> IO (ConnectId cr)
> > afterEdited changed from
> >    :: TreeModelClass tm => CellRendererText -> tm -> (TreeIter -> String -> IO ()) -> IO (ConnectId CellRendererText)
> > to :: CellRendererTextClass cr => cr -> (TreePath -> String -> IO ()) -> IO (ConnectId cr)
> > 
> > -- note sure about dropping the tm param.
> 
> Note that the iterator also changed to TreePath, so is breaking the API.

Hmm, yes. That does make it less clear that we can have the old and new
apis co-exist in the next release.

> I think the more general version was necessary since there are now
> renderers that derive from RendererText.

Yes, that's fine.

> > cellEditable changed from
> >    :: Attribute CellRendererText (Maybe Bool)
> > to :: CellRendererTextClass self => Attr self Bool
> > cellMarkup changed from
> >    :: Attribute CellRendererText String
> > to :: CellRendererTextClass cr => WriteAttr cr (Maybe String)
> > cellText changed from
> >    :: Attribute CellRendererText String
> > to :: CellRendererTextClass cr => Attr cr String
> > cellActive changed from
> >    :: Attribute CellRendererToggle Bool
> > to :: CellRendererToggleClass self => Attr self Bool
> > cellRadio changed from
> >    :: Attribute CellRendererToggle Bool
> > to :: CellRendererToggleClass self => Attr self Bool
> > 
> > -- new style attributes for cell renderers
> > 
> > Functions removed:
> > cellViewDisplayedRow
> > cellViewGetDisplayedRow
> > cellViewSetDisplayedRow
> 
> I think these require more thought on how to implement them with the new
> TreeList API.

Ok. A good reason to punt these changes to the next release.

> > Functions removed:
> > treeViewColumnNewWithAttributes
> > 
> > -- dunno
> 
> Old TreeList API.

Ah yes.

> > Functions removed:
> > castToCurve
> > castToGammaCurve
> > fromCurve
> > fromGammaCurve
> > mkCurve
> > mkGammaCurve
> > toCurve
> > toGammaCurve
> > unCurve
> > unGammaCurve
> > 
> > -- not sure what's going on here. This is a deprecated module anyway.
> 
> Don't know either. Did we just remove the type from hierarchy.txt?

I think we must have. It's not there now. Mind you we never bound it so
that makes sense. So that change can't break anything.

> > Functions changed:
> > aboutDialogLicense changed from
> >    :: AboutDialogClass self => Attr self (Maybe String)
> > to :: AboutDialogClass self => Attr self String
> > aboutDialogLogoIconName changed from
> >    :: AboutDialogClass self => ReadWriteAttr self String (Maybe String)
> > to :: AboutDialogClass self => Attr self (Maybe String)
> > 
> > -- simplification to map Nothing to "". Not essential, could punt.
> 
> I think this is very new anyway.

Yes, it's pretty new.

> > Functions changed:
> > windowBeginMoveDrag changed from
> >    :: WindowClass self => self -> Int -> Int -> Int -> Word32 -> IO ()
> > to :: WindowClass self => self -> MouseButton -> Int -> Int -> Word32 -> IO ()
> > windowBeginResizeDrag changed from
> >    :: WindowClass self => self -> WindowEdge -> Int -> Int -> Int -> Word32 -> IO ()
> > to :: WindowClass self => self -> WindowEdge -> MouseButton -> Int -> Int -> Word32 -> IO ()
> > 
> > -- not sure if these are just type aliases or what.
> 
> They are Enums and should have been from the beginning.

Ok.

> > windowSetIconFromFile changed from
> >    :: WindowClass self => self -> FilePath -> IO Bool
> > to :: WindowClass self => self -> FilePath -> IO ()
> > 
> > -- dunno
> ?

Ah, it now throws an exception rather than returning Bool. It's a rarely
used function I think so I don't think it really matters.

Duncan