diff options
Diffstat (limited to 'src/Gtk/Widgets.dcl')
| -rw-r--r-- | src/Gtk/Widgets.dcl | 185 |
1 files changed, 175 insertions, 10 deletions
diff --git a/src/Gtk/Widgets.dcl b/src/Gtk/Widgets.dcl index 65f8c87..957838b 100644 --- a/src/Gtk/Widgets.dcl +++ b/src/Gtk/Widgets.dcl @@ -1,5 +1,25 @@ definition module Gtk.Widgets +/** + * This module provides functionality for common widgets in the Gtk library. + * See the Gtk+ 3 reference manual for more details about what they are used + * for: https://developer.gnome.org/gtk3/stable/ + * + * Also see the widget gallery for a quick overview of the different widgets: + * https://developer.gnome.org/gtk3/stable/ch03.html + * + * The Gtk library is object-oriented. This is mirrored here with classes. For + * example, all subclasses of `GtkWidget` implement the `gtkWidget` class, and + * common methods of the `GtkWidget` class correspond to overloaded functions + * in Clean. + * + * NB: The types of widgets are exported here because (1) newtypes cannot be + * abstract and (2) they must be able to implement `TC` so that they can be + * shared (see `Gtk.Shares`). When the compiler supports abstract newtypes and + * `TC` instantiation of hidden types, the implementation of these types may + * be removed from the definition module; do not rely on it! + */ + from StdMaybe import :: Maybe from System.FilePath import :: FilePath @@ -12,29 +32,49 @@ from Gtk.Types import :: GdkModifier, :: GtkAlign, :: GtkButtonsType, :: GtkCompletionMode, :: GtkCSSClass, :: GtkDirection, :: GtkExpand, :: GtkFileChooserAction, :: GtkMargins, - :: GtkMessageType, :: GtkModal, :: GtkOrientation, :: GtkPanedHandleWidth, - :: GtkResize, :: GtkResponse, :: GtkScrollbarPolicy, :: GtkSensitivity, - :: GtkShrink, :: GtkSizeRequest, :: GtkSpacing, :: GtkStylePriority, - :: GtkText, :: GtkTitle, :: GtkWrapMode - + :: GtkMarkup, :: GtkMessageType, :: GtkModal, :: GtkOrientation, + :: GtkPanedHandleWidth, :: GtkResize, :: GtkResponse, + :: GtkScrollbarPolicy, :: GtkSensitivity, :: GtkShrink, :: GtkSizeRequest, + :: GtkSpacing, :: GtkStylePriority, :: GtkText, :: GtkTitle, :: GtkWrapMode + +/** + * A `GtkAccelGroup` is needed for a `GtkAccelerator`. 'Accelerator' is Gtk's + * term for what most people call shortcuts, i.e. `Ctrl`-`S`, etc. + */ :: GtkAccelGroup =: GtkAccelGroup Pointer newAccelGroup :: !w -> GtkM GtkAccelGroup | gtkWindow w +/** + * An accelerator is what people normally call a shortcut (e.g. `Ctrl`-`S`). + * The `String` is the name of the key that is pressed. See `gdkkeysyms.h` and + * remove the `GDK_KEY_` prefix; hence e.g. `s` for the letter `s` or `Return` + * for the return/enter key. + */ :: GtkAccelerator = Accelerator !GtkAccelGroup !String ![GdkModifier] +//* An action bar typically holds a number of buttons. :: GtkActionBar =: GtkActionBar Pointer instance gtkWidget GtkActionBar newActionBar :: GtkM GtkActionBar + +//* Add `w` to the start or end of the action bar. packActionBar :: !GtkActionBar !GtkDirection !w -> GtkM w | gtkWidget w +//* A box holds a number of child widgets in some direction with spacing. :: GtkBox =: GtkBox Pointer instance gtkWidget GtkBox instance gtkContainer GtkBox instance gtkOrientable GtkBox -newBox :: !GtkOrientation !Int -> GtkM GtkBox +newBox :: !GtkOrientation -> GtkM GtkBox + +/** + * Add `w` to the start or the end of the box. When used with `Expand`, + * additional space for the box is given to this child (and all other children + * with `Expand` set). + */ packBox :: !GtkBox !GtkDirection !GtkExpand !w -> GtkM w | gtkWidget w instance tune GtkBox GtkSpacing @@ -42,6 +82,12 @@ instance tune GtkBox GtkSpacing :: GtkButton =: GtkButton Pointer instance gtkWidget GtkButton +/** + * Create a button with a single icon. See the icon naming specification for a + * list of common icon names: + * https://developer.gnome.org/icon-naming-spec/ + * You can also see the icons in `/usr/share/icons/<theme>/<size>. + */ newButtonFromIconName :: !String -> GtkM GtkButton :: GtkContainer =: GtkContainer Pointer @@ -53,6 +99,7 @@ instance gtkContainer GtkContainer addToContainer :: !c !w -> GtkM w | gtkWidget w & gtkContainer c +//* A dialog is a popup window. :: GtkDialog =: GtkDialog Pointer class gtkDialog a :: !a -> GtkDialog @@ -62,18 +109,39 @@ instance gtkContainer GtkDialog instance gtkWindow GtkDialog instance gtkDialog GtkDialog +//* If a dialog is `Modal` it prevents interaction with the underlying window. instance tune d GtkModal | gtkDialog d newDialog :: !GtkWindow -> GtkM GtkDialog + +/** + * Runs a dialog, returning when a button has been activated or the dialog has + * been closed somehow (typically by pressing `Esc`). Note that you still need + * to `destroy` the dialog (this allows you to not close the dialog and show an + * error message, if appropriate). + */ runDialog :: !d -> GtkM GtkResponse | gtkDialog d +/** + * Add a button with the given `String` as text to the dialog. When pressed, + * the dialog returns the given `GtkResponse`. + */ addButton :: !String !GtkResponse !d -> GtkM GtkButton | gtkDialog d getContentArea :: !d -> GtkBox | gtkDialog d +//* Convenience function to create a simple message dialog. newMessageDialog :: !GtkWindow !GtkMessageType !GtkButtonsType !String -> GtkM GtkDialog + +/** + * Convenience function to select a file or folder. The optional `String` is + * the title for the dialog. This function internally calls `runDialog` and + * returns the chosen file path, or `Nothing` if the dialog has been cancelled + * somehow. + */ getFileWithDialog :: !GtkWindow !GtkFileChooserAction !(Maybe String) -> GtkM (Maybe FilePath) +//* An entry is a simple text field. Subclasses allow more advanced input. :: GtkEntry =: GtkEntry Pointer class gtkEntry a :: !a -> GtkEntry @@ -87,50 +155,97 @@ getText :: !e -> GtkM String | gtkEntry e instance tune GtkEntry GtkText instance tune GtkEntry GtkEntryCompletion +/** + * See the Gtk documentation an overview of user input completion: + * https://developer.gnome.org/gtk3/stable/GtkEntryCompletion.html#GtkEntryCompletion.description + * + * We do not provide all features here, but assume the common use case of a + * `GtkListStore` that is filtered with the default match function. It is + * possible to tune the completion method with a `GtkCompletionMode`, however. + */ :: GtkEntryCompletion =: GtkEntryCompletion Pointer newEntryCompletion :: GtkM GtkEntryCompletion + +//* Sets the column of the `GtkListStore` to be used for completion. setTextColumn :: !Int !GtkEntryCompletion -> GtkM GtkEntryCompletion instance tune GtkEntryCompletion GtkListStore instance tune GtkEntryCompletion GtkCompletionMode +//* A frame holds a single child, with a border and an optional title. :: GtkFrame =: GtkFrame Pointer instance gtkWidget GtkFrame instance gtkContainer GtkFrame +//* Create a new frame with `w` as the child. newFrame :: !GtkTitle !w -> GtkM GtkFrame | gtkWidget w +//* Convenience function to create a widget and a frame around it at once. framed :: !GtkTitle !(GtkM w) -> GtkM (w, GtkFrame) | gtkWidget w +/** + * A grid is a generalized table, allowing outlining child widget positions to + * each other. + */ :: GtkGrid =: GtkGrid Pointer instance gtkWidget GtkGrid newGrid :: GtkM GtkGrid + +/** + * Attach `w` to the given grid. The first `(Int,Int)` argument is the position + * in the grid (where the top left is `(0,0)`); the second `(Int,Int)` argument + * is the number of rows and columns that the widget occupies. + */ attachGrid :: !GtkGrid !(!Int,!Int) !(!Int,!Int) !w -> GtkM w | gtkWidget w +//* A label is used to display a small or medium amount of text. :: GtkLabel =: GtkLabel Pointer instance gtkWidget GtkLabel newLabel :: GtkM GtkLabel instance tune GtkLabel GtkText +/** + * A list store holds values in a list. It is used in several places, like for + * `GtkEntryCompletion` and `GtkTreeView`. + */ :: GtkListStore =: GtkListStore Pointer +//* Create a new list store where rows are lists of values of the given types. newListStore :: ![GType] -> GtkM GtkListStore + +//* Remove all items from the list store. clearListStore :: !GtkListStore -> GtkM GtkListStore + +//* Add a new value to the end of the list store. appendToListStore :: ![GValue] !GtkListStore -> GtkM GtkListStore + +//* Swap the items at the given indices in the list store, returning success. swapItems :: !Int !Int !GtkListStore -> GtkM Bool +/** + * A menu provides actions to the user. `GtkMenu` by itself is useful to create + * sub-menus (see `setSubMenu`). For a top-level menu, see `GtkMenuBar`. + */ :: GtkMenu =: GtkMenu Pointer instance gtkWidget GtkMenu newMenu :: GtkM GtkMenu +/** + * A menu bar is usually placed at the top of a window, providing actions to + * the user. + */ :: GtkMenuBar =: GtkMenuBar Pointer instance gtkWidget GtkMenuBar newMenuBar :: GtkM GtkMenuBar +/** + * A menu item is an item in a menu. Attach an `ActivateHandler` or set a + * sub-menu with `setSubMenu`. + */ :: GtkMenuItem =: GtkMenuItem Pointer class gtkMenuItem a :: !a -> GtkMenuItem @@ -139,22 +254,31 @@ instance gtkWidget GtkMenuItem instance gtkMenuItem GtkMenuItem newMenuItem :: !String -> GtkM GtkMenuItem + +//* Attach the menu as a sub-menu to `mi`. setSubMenu :: !mi !GtkMenu -> GtkM GtkMenu | gtkMenuItem mi +//* A check menu item is a menu item with a checkbox. :: GtkCheckMenuItem =: GtkCheckMenuItem Pointer instance gtkWidget GtkCheckMenuItem instance gtkMenuItem GtkCheckMenuItem newCheckMenuItem :: !String -> GtkM GtkCheckMenuItem + +//* Check whether the checkbox of the menu item is checked. isActive :: !GtkCheckMenuItem -> GtkM Bool + +//* Modify the checked status of the checkbox of the menu item. setActive :: !Bool !GtkCheckMenuItem -> GtkM GtkCheckMenuItem +//* A separator menu item draws as a simple line to group other items together. :: GtkSeparatorMenuItem =: GtkSeparatorMenuItem Pointer instance gtkWidget GtkSeparatorMenuItem instance gtkMenuItem GtkSeparatorMenuItem newSeparatorMenuItem :: GtkM GtkSeparatorMenuItem +//* This is an interface for widgets that hold a collection of menu items. :: GtkMenuShell =: GtkMenuShell Pointer instance gtkWidget GtkMenuShell @@ -163,12 +287,14 @@ instance gtkMenuShell GtkMenu, GtkMenuBar, GtkMenuShell appendToMenuShell :: !s !mi -> GtkM mi | gtkMenuShell s & gtkMenuItem mi +//* This is an interface for widgets of which the children can be oriented. :: GtkOrientable =: GtkOrientable Pointer class gtkOrientable a :: !a -> GtkOrientable instance tune o GtkOrientation | gtkOrientable o +//* A paned holds two children, with a (usually moveable) handle in between. :: GtkPaned =: GtkPaned Pointer instance gtkWidget GtkPaned instance gtkContainer GtkPaned @@ -177,6 +303,10 @@ newPaned :: !GtkOrientation !GtkPanedHandleWidth -> GtkM GtkPaned packPane1 :: !GtkPaned !GtkResize !GtkShrink !w -> GtkM w | gtkWidget w packPane2 :: !GtkPaned !GtkResize !GtkShrink !w -> GtkM w | gtkWidget w +/** + * A scrolled window holds a single child and uses a scrollbar if it does not + * fit in the outer dimensions. + */ :: GtkScrolledWindow =: GtkScrolledWindow Pointer instance gtkWidget GtkScrolledWindow instance gtkContainer GtkScrolledWindow @@ -186,17 +316,20 @@ newScrolledWindow :: GtkM GtkScrolledWindow instance tune GtkScrolledWindow (GtkScrollbarPolicy, GtkScrollbarPolicy) where tune :: !(!GtkScrollbarPolicy, !GtkScrollbarPolicy) !GtkScrolledWindow -> GtkM GtkScrolledWindow +//* A search entry is a special entry with a search icon and clear button. :: GtkSearchEntry =: GtkSearchEntry Pointer instance gtkWidget GtkSearchEntry instance gtkEntry GtkSearchEntry newSearchEntry :: GtkM GtkSearchEntry +//* A separator is a simple line, allowing for separation between widgets. :: GtkSeparator =: GtkSeparator Pointer instance gtkWidget GtkSeparator newSeparator :: !GtkOrientation -> GtkM GtkSeparator +//* A spinner is an animated widget signaling indefinite progress. :: GtkSpinner =: GtkSpinner Pointer instance gtkWidget GtkSpinner @@ -204,12 +337,14 @@ newSpinner :: GtkM GtkSpinner startSpinner :: !GtkSpinner -> GtkM GtkSpinner stopSpinner :: !GtkSpinner -> GtkM GtkSpinner +//* A text buffer is viewed by a `GtkTextView`; updates occur on this type. :: GtkTextBuffer =: GtkTextBuffer Pointer -setText :: !String !GtkTextBuffer -> GtkM GtkTextBuffer -setMarkup :: !String !GtkTextBuffer -> GtkM GtkTextBuffer +instance tune GtkTextBuffer GtkText +instance tune GtkTextBuffer GtkMarkup insertAtCursor :: !String !GtkTextBuffer -> GtkM GtkTextBuffer +//* A text view holds a larger amount of text than a `GtkLabel`. :: GtkTextView =: GtkTextView Pointer instance gtkWidget GtkTextView instance gtkContainer GtkTextView @@ -219,16 +354,33 @@ getTextBuffer :: !GtkTextView -> GtkTextBuffer instance tune GtkTextView GtkWrapMode +//* A tree view is a view on a `GtkListStore` with customizable columns. :: GtkTreeView =: GtkTreeView Pointer instance gtkWidget GtkTreeView newTreeView :: !GtkListStore -> GtkM GtkTreeView + +/** + * Append a column with a given title to the tree view. The `Int` argument is + * the column index in the list store that is shown. When `Expand` is used, + * excess space of the tree view is (partially) given to this column. + */ appendColumnToTreeView :: !String !Int !GtkExpand !GtkTreeView -> GtkM GtkTreeView +//* Add a signal handler for the event that the user selects a different row. addSelectionChangedHandler :: !(GtkM ()) !GtkTreeView -> GtkM GtkTreeView + +/** + * Gets the path to the currently selected item, or `Nothing` if no item is + * selected. For list stores, this is a singleton list containing the row + * number. + */ getPathToSelection :: !GtkTreeView -> GtkM (Maybe [Int]) + +//* Select an item in the view, by its path (see `getPathToSelection`). selectPath :: ![Int] !GtkTreeView -> GtkM Bool +//* This is an abstract class; every GUI element is a widget. :: GtkWidget =: GtkWidget Pointer class gtkWidget a :: !a -> GtkWidget @@ -237,14 +389,20 @@ instance gtkWidget GtkWidget show :: !w -> GtkM w | gtkWidget w hide :: !w -> GtkM w | gtkWidget w + +//* Check whether this widget and all of its parents are visible. isVisible :: !w -> GtkM Bool | gtkWidget w + +//* Destroy the widget, freeing all related memory. destroy :: !w -> GtkM () | gtkWidget w + +//* Grabs user input focus. This only makes sense for `GtkEntry` and similar. grabFocus :: !w -> GtkM w | gtkWidget w -addCSSClass :: !GtkCSSClass !w -> GtkM w | gtkWidget w removeCSSClass :: !GtkCSSClass !w -> GtkM () | gtkWidget w -setMargins :: !GtkMargins !w -> GtkM w | gtkWidget w +instance tune w GtkCSSClass | gtkWidget w +instance tune w GtkMargins | gtkWidget w instance tune w GtkSensitivity | gtkWidget w instance tune w (GtkAlign,GtkAlign) | gtkWidget w where tune :: !(!GtkAlign, !GtkAlign) !w -> GtkM w | gtkWidget w @@ -253,6 +411,7 @@ where tune :: !(!GtkExpand, !GtkExpand) !w -> GtkM w | gtkWidget w instance tune w GtkAccelerator | gtkWidget w instance tune w GtkSizeRequest | gtkWidget w +//* A window is a top-level element, holding a single child widget. :: GtkWindow =: GtkWindow Pointer class gtkWindow a :: !a -> GtkWindow @@ -263,6 +422,12 @@ instance gtkWindow GtkWindow newPopup :: GtkM GtkWindow newWindow :: GtkM GtkWindow + +/** + * Adds CSS from a local file to the window and all its child widgets. + * @result Success (the operation may fail if the file cannot be found or + * contains illegal syntax). + */ addCSSFromFile :: !GtkStylePriority !FilePath !GtkWindow -> GtkM Bool instance tune w GtkTitle | gtkWindow w |