path: root/src/Gtk/Widgets.dcl

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.
 */

from StdMaybe import :: Maybe

from System.FilePath import :: FilePath
from System._Pointer import :: Pointer

from Gtk.State import :: GtkM
from Gtk.Tune import class tune
from Gtk.Types import
	:: GType, :: GValue,
	:: GdkModifier,
	:: GtkAlign, :: GtkButtonsType, :: GtkCompletionMode, :: GtkCSSClass,
	:: GtkDirection, :: GtkExpand, :: GtkFileChooserAction,
	:: GtkLineSpacingModifier, :: GtkMargins, :: 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 -> 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

:: 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)

class gtkContainer a :: !a -> GtkContainer

instance gtkWidget GtkContainer
instance gtkContainer GtkContainer

unsafeToContainer :: !Pointer -> GtkContainer

addToContainer :: !c !w -> GtkM w | gtkWidget w & gtkContainer c

//* A dialog is a popup window.
:: GtkDialog (=: GtkDialog Pointer)

class gtkDialog a :: !a -> GtkDialog

instance gtkWidget GtkDialog
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

instance gtkWidget GtkEntry
instance gtkEntry GtkEntry

unsafeToEntry :: !Pointer -> GtkEntry

newEntry :: GtkM GtkEntry
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

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

class gtkMenuShell a :: !a -> GtkMenuShell
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

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

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

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)

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

newTextView :: GtkM GtkTextView
getTextBuffer :: !GtkTextView -> GtkTextBuffer

instance tune GtkTextView GtkLineSpacingModifier
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

instance gtkWidget GtkWidget

toPtr :: !w -> Pointer | gtkWidget w
unsafeToWidget :: !Pointer -> 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

removeCSSClass :: !GtkCSSClass !w -> GtkM () | 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
instance tune w (GtkExpand,GtkExpand) | gtkWidget w
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

instance gtkWidget GtkWindow
instance gtkContainer GtkWindow
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