Gtk2Hs

• 1. Significant changes
  • 1.1. Type changes
    • 1.1.1. Added ‘Maybe’ types
    • 1.1.2. Miscelanious type changes
    • 1.1.3. Swapped parameter order
  • 1.2. Name Changes
    • 1.2.1. Priority constants
  • 1.3. Removed functions and values
• 2. Insignificant changes
  • 2.1. Generalised types
  • 2.2. Specialised types

We are trying to make fixes and imprevements to the Gtk2Hs API before we reach version 1.0. For the the 1.0.x series the aim is for the API to remain stable and not contain backwards incompatbile changes between releases.

1. Significant changes

These API changes are will require minor changes in your code if you use any of the functions listed here.

1.1. Type changes

1.1.1. Added ‘Maybe’ types

These changes involve wrapping a function parameter or result in a Maybe type. This is usually because there is a meaningful ‘Nothing’ case that would otherwise be missed. (In previous Gtk2Hs versions the situations that now return ‘Nothing’ may have instead resulted in a segfault.)

binGetChild changed from

     :: BinClass bin => bin -> IO Widget
  to :: BinClass self => self -> IO (Maybe Widget)

panedGetChild1 changed from

     :: PanedClass p => p -> IO Widget
  to :: PanedClass self => self -> IO (Maybe Widget)

panedGetChild2 changed from

     :: PanedClass p => p -> IO Widget
  to :: PanedClass self => self -> IO (Maybe Widget)

entryCompletionGetModel changed from

     :: EntryCompletion -> IO TreeModel
  to :: EntryCompletion -> IO (Maybe TreeModel)

entryCompletionSetModel changed from

     :: EntryCompletion -> TreeModel -> IO ()
  to :: TreeModelClass model => EntryCompletion -> Maybe model -> IO ()

comboBoxSetModel changed from

     :: ComboBoxClass combo => combo -> TreeModel -> IO ()
  to :: (ComboBoxClass self, TreeModelClass model) => self -> Maybe model -> IO ()

treeViewGetCursor changed from

     :: TreeViewClass tv => tv -> IO (Maybe TreePath, Maybe TreeViewColumn)
  to :: TreeViewClass self => self -> IO (TreePath, Maybe TreeViewColumn)

1.1.2. Miscelanious type changes

miscSetAlignment changed from

     :: MiscClass m => m -> Double -> Double -> IO ()
  to :: MiscClass self => self -> Float -> Float -> IO ()

This function now takes Float rather than Double parameters which more accurately reflects the underlying C API.

frameGetLabelAlign changed from

     :: FrameClass f => f -> IO Float
  to :: FrameClass self => self -> IO (Float, Float)

frameSetLabelAlign changed from

     :: FrameClass f => f -> Float -> IO ()
  to :: FrameClass self => self -> Float -> Float -> IO ()

frameSetLabelAlign now takes an extra Float argument and frameGetLabelAlign now returns an extra Float argument. This extra value is the Y alignment.

Pass 0.0 for the Y alignment (the second argument) to frameSetLabelAlign to get the previous behavour of this function.

These two functions previosuly only set and returned the X alignment of the frame’s label. They now act on both theX and Y alignment.

1.1.3. Swapped parameter order

For some reason these functions had their argumets the wrong way round. The object being acted upon should be the first argument.

toggleButtonSetActive changed from

     :: ToggleButtonClass tb => Bool -> tb -> IO ()
  to :: ToggleButtonClass self => self -> Bool -> IO ()

toggleButtonSetInconsistent changed from

     :: ToggleButtonClass tb => Bool -> tb -> IO ()
  to :: ToggleButtonClass self => self -> Bool -> IO ()

textBufferGetIterAtLine changed from

     :: TextBufferClass tb => Int -> tb -> IO TextIter
  to :: TextBufferClass self => self -> Int -> IO TextIter

textViewForwardDisplayLineEnd changed from

     :: TextViewClass tv => TextIter -> tv -> IO Bool
  to :: TextViewClass self => self -> TextIter -> IO Bool

treeViewExpandRow changed from

     :: TreeViewClass tv => TreePath -> Bool -> tv -> IO Bool
  to :: TreeViewClass self => self -> TreePath -> Bool -> IO Bool

1.2. Name Changes

treeViewGetHadjustment has been renamed to treeViewGetHAdjustment

treeViewGetVadjustment has been renamed to treeViewGetVAdjustment

treeViewSetHadjustment has been renamed to treeViewSetHadjustment

treeViewSetVadjustment has been renamed to treeViewSetVAdjustment

The names of the adjustment objects are VAdjustment and HAdjustment, not Vadjustment and Hadjustment. Also, for some reason the “Set” variants of these functions had their argumets the wrong way round. The object being acted upon should be the first argument.

fileChooserlistShortcutFolders has been renamed to fileChooserListShortcutFolders

1.2.1. Priority constants

Changed the meaning of the priority contants used by idleAdd and timeoutAdd.

If you use these functions you should change uses of priorityDefault to priorityDefaultIdle and priorityHigh to priorityHighIdle. This will give the same behaviour as before - which is almost certainly what you want.

Previously priorityDefault had actually been the value of G_PRIORITY_DEFAULT_IDLE rather than G_PRIORITY_DEFAULT and similarly for priorityHigh.

So now priorityDefault refers to G_PRIORITY_DEFAULT and there is a new value priorityDefaultIdle that refers to G_PRIORITY_DEFAULT_IDLE.

1.3. Removed functions and values

The event type testing functions: hasButLeft, hasButMiddle, hasButRight, hasControl, hasLock, hasMod1, hasMod2, hasMod3, hasMod4, hasMod5, hasShift have been removed. The Modifier data type is not opaque anymore so you can use the Modifier data constructors instead.

textViewBackwardDisplayLineEnd and textViewForwardDisplayLineStart have been removed. In a sense they never really existed! They were incorrectly implemented as aliases to other functions. If you were using textViewBackwardDisplayLineEnd you were actually using textViewBackwardDisplayLineStart and similarly if you were using textViewForwardDisplayLineStart you were actually using textViewForwardDisplayLineStart. So you can fix your code by doing the appropriate renaming.

2. Insignificant changes

These changes will probably not require any changes in your code, even if you use the functions listed in this section.

2.1. Generalised types

These changes are where a function parameter that was a specific concrete type has been replaced by a type class of which the original concrete type was a member. So for example, instead of requiring a TreeModel we allow any type in the TreeModelClass. Such a change will not break programs except in the unlikely circumstance that it introduces a type ambiguity.

In the OOP model this change means allowing subclasses to be passed as well.

comboBoxNewWithModel changed from

     :: TreeModel -> IO ComboBox
  to :: TreeModelClass model => model -> IO ComboBox

comboBoxEntryNewWithModel changed from

     :: TreeModel -> Int -> IO ComboBoxEntry
  to :: TreeModelClass model => model -> Int -> IO ComboBoxEntry

toolbarSetDropHighlightItem changed from

     :: ToolbarClass tb => tb -> Maybe ToolItem -> Int -> IO ()
  to :: (ToolbarClass self, ToolItemClass toolItem) => self -> Maybe toolItem -> Int -> IO ()

textBufferApplyTag changed from

     :: TextBufferClass tb => tb -> TextTag -> TextIter -> TextIter -> IO ()
  to :: (TextBufferClass self, TextTagClass tag) => self -> tag -> TextIter -> TextIter -> IO ()

textBufferDeleteMark changed from

     :: TextBufferClass tb => tb -> TextMark -> IO ()
  to :: (TextBufferClass self, TextMarkClass mark) => self -> mark -> IO ()

textBufferGetIterAtMark changed from

     :: TextBufferClass tb => tb -> TextMark -> IO TextIter
  to :: (TextBufferClass self, TextMarkClass mark) => self -> mark -> IO TextIter

textBufferMoveMark changed from

     :: TextBufferClass tb => tb -> TextMark -> TextIter -> IO ()
  to :: (TextBufferClass self, TextMarkClass mark) => self -> mark -> TextIter -> IO ()

textBufferNew changed from

     :: Maybe TextTagTable -> IO TextBuffer
  to :: TextTagTableClass table => Maybe table -> IO TextBuffer

textBufferRemoveTag changed from

     :: TextBufferClass tb => tb -> TextTag -> TextIter -> TextIter -> IO ()
  to :: (TextBufferClass self, TextTagClass tag) => self -> tag -> TextIter -> TextIter -> IO ()

textTagTableAdd changed from

     :: TextTagTableClass obj => obj -> TextTag -> IO ()
  to :: (TextTagTableClass self, TextTagClass tag) => self -> tag -> IO ()

textTagTableRemove changed from

     :: TextTagTableClass obj => obj -> TextTag -> IO ()
  to :: (TextTagTableClass self, TextTagClass tag) => self -> tag -> IO ()

textViewMoveMarkOnscreen changed from

     :: TextViewClass tv => tv -> TextMark -> IO Bool
  to :: (TextViewClass self, TextMarkClass mark) => self -> mark -> IO Bool

textViewNewWithBuffer changed from

     :: TextBuffer -> IO TextView
  to :: TextBufferClass buffer => buffer -> IO TextView

textViewScrollMarkOnscreen changed from

     :: TextViewClass tv => tv -> TextMark -> IO ()
  to :: (TextViewClass self, TextMarkClass mark) => self -> mark -> IO ()

textViewScrollToMark changed from

     :: TextViewClass tv => tv -> TextMark -> Double -> Maybe (Double, Double) -> IO ()
  to :: (TextViewClass self, TextMarkClass mark) => self -> mark -> Double -> Maybe (Double, Double) -> IO ()

textViewSetBuffer changed from

     :: TextViewClass tv => tv -> TextBuffer -> IO ()
  to :: (TextViewClass self, TextBufferClass buffer) => self -> buffer -> IO ()

treeViewSetCursorOnCell changed from

     :: TreeViewClass tv => tv -> TreePath -> TreeViewColumn -> CellRenderer -> Bool -> IO ()
  to :: (TreeViewClass self, CellRendererClass focusCell) => self -> TreePath -> TreeViewColumn -> focusCell -> Bool -> IO ()

2.2. Specialised types

This is the opposite change to those above. It replaces a polymorphic parameter constrained by a type class with a concrete member of that class, or by another type class that inherits from the original one. These examples should not break any code since the concrete type was the only member of the type class.

In the OOP model this amounts to making the object type closed, so it cannot be inherited from.

containerSetFocusHAdjustment changed from

     :: (ContainerClass c, AdjustmentClass a) => c -> a -> IO ()
  to :: ContainerClass self => self -> Adjustment -> IO ()

containerSetFocusVAdjustment changed from

     :: (ContainerClass c, AdjustmentClass a) => c -> a -> IO ()
  to :: ContainerClass self => self -> Adjustment -> IO ()

afterToggled changed from

     :: ButtonClass b => b -> IO () -> IO (ConnectId b)
  to :: ToggleButtonClass self => self -> IO () -> IO (ConnectId self)

onToggled changed from

     :: ButtonClass b => b -> IO () -> IO (ConnectId b)
  to :: ToggleButtonClass self => self -> IO () -> IO (ConnectId self)

every TreeViewColumn function changed from

     :: TreeViewColumnClass tvc => tvc -> ...
  to :: TreeViewColumn -> ...