Gtk2Hs Tutorial - (part 1)
- -Hans van Thiel
--
-
- -
The start of a port and adaptation to Gtk2Hs of the:
- -GTK+2.0 Tutorial by
- -Tony Gale
- -Ian Main
- -& the GTK team
-- -
-
-
- Table of Contents - -
-
- Introduction and Overview: not available yet...
-
-
- Getting Started
-
-
- Packing Widgets
-
-
- Packing Demonstration Program
-
-
- Packing Using Tables
-
-
- The Button Widget
-
-
- Adjustments, Scale and Range
-
- -
-
-
- Labels
-
-
- Arrows and Tooltips
-
-
- Dialogs, Stock Items and Progress - Bars
-
-
- Text Entries and Statusbars
-
-
-
- -
Tutorial - Copyright and Permissions Notice
- -The GTK Tutorial is Copyright (C) 1997 Ian Main.
- -Copyright (C) 1998-2002 Tony Gale.
- -Copyright (C) 2007 Hans van Thiel
- -Permission is granted to make and distribute verbatim copies - of this manual provided the copyright notice and this permission - notice are preserved on all copies.
- -Permission is granted to copy and distribute modified versions - of this document under the conditions for verbatim copying, - provided that this copyright notice is included exactly as in the - original, and that the entire resulting derived work is - distributed under the terms of a permission notice identical to - this one.
- -Permission is granted to copy and distribute translations of - this document into another language, under the above conditions - for modified versions.
- -If you are intending to incorporate this document into a - published work, please contact the maintainer, and we will make - an effort to ensure that you have the most up to date information - available.
- -There is no guarantee that this document lives up to its - intended purpose. This is simply provided as a free resource. As - such, the authors and maintainers of the information provided - within can not make any guarantee that the information is even - accurate.
-- -
|
- |
-
-
- |
-
- - - | -
|
- |
-
-
- - |
-
-
- |
-
|
- Gtk2Hs Tutorial - |
- ||
|---|---|---|
| - - | + hunk ./docs/tutorial/Tutorial_Port/chap3.xhtml 12 -+ | - - | -
+
Getting Started
hunk ./docs/tutorial/Tutorial_Port/chap3.xhtml 21 -Getting Started
++The first thing to do, of course, is download Gtk2Hs and install it. You can +always get the latest version from +http://haskell.org/gtk2hs/ and several +Linux versions have their own Gtk2Hs packages. For Windows there is an +installer available. +
hunk ./docs/tutorial/Tutorial_Port/chap3.xhtml 29 -The first thing to do, of course, is download Gtk2Hs and - install it. You can always get the latest version from http://haskell.org/gtk2hs/ and - several Linux versions have their own Gtk2Hs packages. For - Windows there is an installer available.
++The next thing is to open the Gtk2Hs API reference documentation for your +version. You will need to use this extensively to be able to find the names for +widgets, methods, attributes and signals you might want to use. The contents +lists all modules and there is also an index. Inside each module description +there is also a class hierarchy. If a method, attribute or signal you expect is +missing, it might belong to one of the superclasses of which your widget type +is an instance. +
hunk ./docs/tutorial/Tutorial_Port/chap3.xhtml 39 -The next thing is to open the Gtk2Hs API reference - documentation for your version. You will need to use this - extensively to be able to find the names for widgets, methods, - attributes and signals you might want to use. The contents - list all modules and there is also an index. Inside each - module description there is also a class hierarchy. If a method, - attribute or signal you expect is missing, it might belong to one - of the superclasses of which your widget type is an instance.
++To begin our introduction to Gtk2Hs, we'll start with the simplest program +possible. This program will create a 200x200 pixel window and has no way of +exiting except to be killed by using the shell. +
hunk ./docs/tutorial/Tutorial_Port/chap3.xhtml 45 -To begin our introduction to Gk2Hs, we'll start with the - simplest program possible. This program will create a 200x200 - pixel window and has no way of exiting except to be killed by - using the shell.
+
- +hunk ./docs/tutorial/Tutorial_Port/chap3.xhtml 57 - |
-
You can compile the above program with the Glasgow Haskell - Compiler (GHC) using:
++You can compile the above program with the Glasgow Haskell Compiler (GHC) +using: +
hunk ./docs/tutorial/Tutorial_Port/chap3.xhtml 63 -ghc --make GtkChap3a.hs -o Chap3a
++ghc --make GtkChap3a.hs -o Chap3a +hunk ./docs/tutorial/Tutorial_Port/chap3.xhtml 67 -
assuming GtkChap3a.hs is the filename. Alternatively you can - use the interactive GHCi, for earlier and later versions of - Gtk2Hs. (Because of threading problems intermediate versions will - not work interactively. Gtk2Hs does not work with Hugs.)
+
+assuming GtkChap3a.hs is the filename. Alternatively you can use
+the interactive GHCi, for earlier and later versions of Gtk2Hs. (Because of
+threading problems intermediate versions will not work interactively. Gtk2Hs
+does not work with Hugs.)
+
The first line imports the Gtk2Hs graphics library.
++The first line of the program imports the Gtk2Hs graphics library. +
hunk ./docs/tutorial/Tutorial_Port/chap3.xhtml 78 -All Gtk2Hs programs run in main and the first line:
+
+All Gtk2Hs programs run in main. The first line of that function's
+do block:
+
- +hunk ./docs/tutorial/Tutorial_Port/chap3.xhtml 86 - |
-
is called in all Gk2Hs applications. The next two lines of - code create and display a window.
++is a function called in all Gtk2Hs applications. +
+ ++The next two lines in the block create and display a window and its contents: +
hunk ./docs/tutorial/Tutorial_Port/chap3.xhtml 95 -
- +hunk ./docs/tutorial/Tutorial_Port/chap3.xhtml 99 - |
-
Rather than create a window of 0x0 size, a window without - children is set to 200x200 by default so you can still manipulate - it. Widgets that can be visible (not all can) may be shown or - hidden using their own methods, but the second line works on a - widget (here the window) and all its children.
++Rather than create a window of 0x0 size, a window without children is set to +200x200 by default so you can still manipulate it. Widgets that can be visible +(not all can) may be shown or hidden using their own methods, but the second +line works on a widget (here the window) and all its children. +
hunk ./docs/tutorial/Tutorial_Port/chap3.xhtml 107 -The last line enters the Gtk2Hs main processing loop.
+
+The last line of main enters the Gtk2Hs main processing loop:
+
- +hunk ./docs/tutorial/Tutorial_Port/chap3.xhtml 114 - |
-
mainGUI is another call you will see in every Gtk2Hs - application. When control reaches this point, Gtk2Hs will sleep - waiting for X events (such as button or key presses), timeouts, - or file IO notifications to occur. In our simple example, - however, events are ignored.
++and is another call you will see in every Gtk2Hs application. When control +reaches this point, Gtk2Hs will sleep waiting for X events (such as button or +key presses), timeouts, or file IO notifications to occur. In our simple +example, however, events are ignored. +
hunk ./docs/tutorial/Tutorial_Port/chap3.xhtml 122 -Hello World - in Gtk2Hs
+"Hello World" in Gtk2Hs
hunk ./docs/tutorial/Tutorial_Port/chap3.xhtml 124 -Now for a program with a widget (a button). It's the classic - hello world à la Gtk2Hs.
++Now for a program with a widget (a button): the classic "hello world" à +la Gtk2Hs. +
hunk ./docs/tutorial/Tutorial_Port/chap3.xhtml 129 -
If the button is clicked it will display the text Hello - World. This is implemented in the Haskell function - hello with a button b as its argument. The type - declaration actually states the type variable o is an - instance of class ButtonClass. Gtk2Hs extensively uses - Haskell classes to map the object hierarchy of the original Gtk - widgets. Each widget in Gtk2Hs, of course, has a Haskell - type.
+
+If the button is clicked it will display the text "Hello World". This is
+implemented in the Haskell function hello with a button
+b as its argument. The type declaration actually states the type
+variable o is an instance of class ButtonClass. Gtk2Hs
+extensively uses Haskell classes to map the object hierarchy of the original
+GTK widgets. Each widget in Gtk2Hs, of course, has a Haskell type.
+
Widgets, and the classes their types belong to, usually have - attributes. These can be set either by named methods or by the - general set function, which uses a list-like notation as - shown below. Of special interest here is the - containerChild attribute of the window (actually a - superclass of the window) which states the relationship with the - button. Because of this widgetShowAll window will also - make the button visible.
+
+Widgets, and the classes their types belong to, usually have attributes. These
+can be set either by named methods or by the general set function,
+which uses a list-like notation as shown below. Of special interest here is the
+containerChild attribute of the window (actually of a superclass
+of the window) which states the relationship with the button. Because of this
+relationship widgetShowAll window will also make the button
+visible.
+
Widgets are connected to other widgets in a graphical - dependency tree (not to be confused with the class hierarchy). - Gtk2hs also works with the Glade visual interface designer and, - if you use Glade, such connections are visible in the Widget - tree window. There is a separate - introductory tutorial on how to use Glade with Gtk2Hs.
++Widgets are connected to other widgets in a graphical dependency tree (not to +be confused with the class hierarchy). Gtk2Hs also works with the Glade visual +interface designer and, if you use Glade, such connections are visible in the +Inspector pane. There is a +separate introductory +tutorial on how to use Glade with Gtk2Hs. +
hunk ./docs/tutorial/Tutorial_Port/chap3.xhtml 159 -
- +hunk ./docs/tutorial/Tutorial_Port/chap3.xhtml 171 - containerChild := button , containerBorderWidth := 10 ] + containerChild := button, containerBorderWidth := 10 ] hunk ./docs/tutorial/Tutorial_Port/chap3.xhtml 177 - |
-
- -
Gtk2Hs is event driven. The mainGUI function will sleep until - something happens, like a mouse being clicked, a window being - destroyed or something else typical for a widget. Such events - then trigger signals which in turn trigger user defined functions - to be evaluated. In this case the onClicked signal, - emitted by the user clicking the button, is linked to the text - being displayed on the same button. When the user destroys the - window, unlike as with the first program, main now exits - cleanly.
- -
-
| - - | - -- - | - -- - | -
|
- Contents - |
hunk ./docs/tutorial/Tutorial_Port/chap3.xhtml 178
-
- - |
+
- Packing Widgets - |
-
-
|
- GTK2Hs Tutorial - |
- ||
|---|---|---|
| - - | + hunk ./docs/tutorial/Tutorial_Port/chap4.xhtml 12 -+ | - - | -
+
Packing Widgets
hunk ./docs/tutorial/Tutorial_Port/chap4.xhtml 21 -Packing Widgets
+
+When creating an application, you'll want to put more than one widget inside a
+window. Our first "hello world" example only used one widget so we could simply
+use set to specify a containerChild widget for
+window, or use containerAdd to "pack" the widget into
+the window. But when you want to put more than one widget into a window, how do
+you control where that widget is positioned? This is where packing comes in.
+
When creating an application, you'll want to put more than one - widget inside a window. Our first helloworld example only - used one widget so we could simply use a set (of the - containerChild attribute) or a containerAdd to - "pack" the widget into the window. But when you want to put more - than one widget into a window, how do you control where that - widget is positioned? This is where packing comes in.
+Theory of Packing Boxes
hunk ./docs/tutorial/Tutorial_Port/chap4.xhtml 32 -Theory of Packing Boxes
++Most packing is done by creating boxes. These are invisible widget containers +that we can pack our widgets into which come in two forms: a horizontal box and +a vertical box. When packing widgets into a horizontal box, the objects are +inserted horizontally from left to right or right to left depending on the call +used. In a vertical box, widgets are packed from top to bottom or vice versa. +You may use any combination of boxes inside or beside other boxes to create the +desired effect. +
hunk ./docs/tutorial/Tutorial_Port/chap4.xhtml 42 -Most packing is done by creating boxes. These are invisible - widget containers that we can pack our widgets into which come in - two forms, a horizontal box, and a vertical box. When packing - widgets into a horizontal box, the objects are inserted - horizontally from left to right or right to left depending on the - call used. In a vertical box, widgets are packed from top to - bottom or vice versa. You may use any combination of boxes inside - or beside other boxes to create the desired effect.
+
+To create a new horizontal box, we use hBoxNew, and for vertical
+boxes, vBoxNew. Both take a Bool and an
+Int parameter. The first parameter will give all children equal
+space allotments if set to True and the second sets the number of
+pixels to place by default between the children.
+
To create a new horizontal box, we use hBoxNew, and for - vertical boxes, vBoxNew. Both take a Bool and an Int - parameter. The first will give all children equal space - allotments if set True and the second sets the number of pixels - to place by default between the children.
+
+The boxPackStart and boxPackEnd functions are used to
+place objects inside of these containers. The boxPackStart
+function will start at the top and work its way down in a VBox,
+and pack left to right in an HBox. boxPackEnd will do
+the opposite, packing from bottom to top in a VBox, and right to
+left in an HBox. Using these functions allows us to right justify
+or left justify our widgets and they may be mixed in any way to achieve the
+desired effect. We will use boxPackStart in most of our examples.
+
The boxPackStart and boxPackEnd functions are - used to place objects inside of these containers. The - boxPackStart function will start at the top and work its - way down in a vbox, and pack left to right in an hbox. - boxPackEnd will do the opposite, packing from bottom to - top in a vbox, and right to left in an hbox. Using these - functions allows us to right justify or left justify our widgets - and may be mixed in any way to achieve the desired effect. We - will use boxPackStart in most of our examples. An object - may be another container or a widget. In fact, many widgets are - actually containers themselves, including the button, but we - usually only use a label inside a button.
+
+An object may be another container or a widget. In fact, many widgets are
+actually containers themselves—including button, but we
+usually only use a label inside a button.
+
- +hunk ./docs/tutorial/Tutorial_Port/chap4.xhtml 74 - initGUI - window <- windowNew - hbox <- hBoxNew True 10 - button1 <- buttonNewWithLabel "Button 1" - button2 <- buttonNewWithLabel "Button 2" - set window [windowDefaultWidth := 200, windowDefaultHeight := 200, - containerBorderWidth := 10, containerChild := hbox ] - boxPackStart hbox button1 PackGrow 0 - boxPackStart hbox button2 PackGrow 0 - widgetShowAll window - onDestroy window mainQuit - mainGUI + initGUI + window <- windowNew + hbox <- hBoxNew True 10 + button1 <- buttonNewWithLabel "Button 1" + button2 <- buttonNewWithLabel "Button 2" + set window [windowDefaultWidth := 200, windowDefaultHeight := 200, + containerBorderWidth := 10, containerChild := hbox ] + boxPackStart hbox button1 PackGrow 0 + boxPackStart hbox button2 PackGrow 0 + onDestroy window mainQuit + widgetShowAll window + mainGUI hunk ./docs/tutorial/Tutorial_Port/chap4.xhtml 87 - |
-
-
By using these calls, GTK knows where you want to place your - widgets so it can do automatic resizing and other nifty things. - The Packing parameter specifies the way the widgets in the - container behave when the window is resized. PackNatural - means the widgets will retain their size and stay where they are, - PackGrow means they will - be resized, and using PackRepel the widgets will be padded equally on both - sides. The last parameter is an Int, which specifies any extra - padding to be put between this child and its - neighbours.
+
+By using boxPackStart or boxPackEnd, GTK knows where
+you want to place your widgets so it can do automatic resizing and other nifty
+things.
+
Note that the packing only applies - to the dimension of the box. If, for example, you specify - PackNatural instead of Packgrow in the above, - resizing horizontally will keep the buttons at their original - size, but resizing vertically will also resize the buttons. This - is because the buttons are placed homogoneously in the horizontal - box (first parameter True) and the box itself will resize - with the window. The next example will make the effects more - clear.
-- -
| - - | - -- - | +- - | -
|
- Getting Started - |
+
- - |
+
- Packing Demonstration Program - |
-
-
Gtk2Hs Tutorial
+An Adaptation of the GTK+ 2.0 Tutorial by
+Tony Gale
+Ian Main
+&
+The GTK Team
+Table of Contents
+-
+
- 1. Introduction — Not Available Yet + +
- 2. Getting Started + +
- 3. Packing + + +
- 4. Miscellaneous Widgets + + +
Tutorial Copyright and Permissions Notice
+ +The GTK Tutorial is Copyright © 1997 Ian Main.
+ +Copyright © 1998-2002 Tony Gale.
+ +Copyright © 2007 Hans van Thiel and Alex Tarkovsky.
+ ++Permission is granted to make and distribute verbatim copies of this manual +provided the copyright notice and this permission notice are preserved on all +copies. +
+ ++Permission is granted to copy and distribute modified versions of this document +under the conditions for verbatim copying, provided that this copyright notice +is included exactly as in the original, and that the entire resulting derived +work is distributed under the terms of a permission notice identical to this +one. +
+ ++Permission is granted to copy and distribute translations of this document into +another language, under the above conditions for modified versions. +
+ ++If you are intending to incorporate this document into a published work, please +contact the maintainer, and we will make an effort to ensure that you have the +most up to date information available. +
+ ++There is no guarantee that this document lives up to its intended purpose. This +is simply provided as a free resource. As such, the authors and maintainers of +the information provided within can not make any guarantee that the information +is even accurate. +
+ + + + + }