GI.Gtk.Functions

Methods

acceleratorGetDefaultModMask

acceleratorGetDefaultModMask

Arguments

:: (HasCallStack, MonadIO m)

=> m [ModifierType]

Returns: the modifier mask for accelerators

Gets the modifier mask.

The modifier mask determines which modifiers are considered significant for keyboard accelerators. This includes all keyboard modifiers except for ModifierTypeLockMask.

acceleratorGetLabel

acceleratorGetLabel

Arguments

:: (HasCallStack, MonadIO m)

=> Word32

acceleratorKey: accelerator keyval

-> [ModifierType]

acceleratorMods: accelerator modifier mask

-> m Text

Returns: a newly-allocated string representing the accelerator.

Converts an accelerator keyval and modifier mask into a string which can be used to represent the accelerator to the user.

acceleratorGetLabelWithKeycode

acceleratorGetLabelWithKeycode

Arguments

:: (HasCallStack, MonadIO m, IsDisplay a)

=> Maybe a

display: a Display or Nothing to use the default display

-> Word32

acceleratorKey: accelerator keyval

-> Word32

keycode: accelerator keycode

-> [ModifierType]

acceleratorMods: accelerator modifier mask

-> m Text

Returns: a newly-allocated string representing the accelerator.

Converts an accelerator keyval and modifier mask into a (possibly translated) string that can be displayed to a user, similarly to acceleratorGetLabel, but handling keycodes.

This is only useful for system-level components, applications should use acceleratorParse instead.

acceleratorName

acceleratorName

Arguments

:: (HasCallStack, MonadIO m)

=> Word32

acceleratorKey: accelerator keyval

-> [ModifierType]

acceleratorMods: accelerator modifier mask

-> m Text

Returns: a newly-allocated accelerator name

Converts an accelerator keyval and modifier mask into a string parseable by acceleratorParse. For example, if you pass in KEY_q and GDK_CONTROL_MASK, this function returns “<Control>q”.

If you need to display accelerators in the user interface, see acceleratorGetLabel.

acceleratorNameWithKeycode

acceleratorNameWithKeycode

Arguments

:: (HasCallStack, MonadIO m, IsDisplay a)

=> Maybe a

display: a Display or Nothing to use the default display

-> Word32

acceleratorKey: accelerator keyval

-> Word32

keycode: accelerator keycode

-> [ModifierType]

acceleratorMods: accelerator modifier mask

-> m Text

Returns: a newly allocated accelerator name.

Converts an accelerator keyval and modifier mask into a string parseable by acceleratorParseWithKeycode, similarly to acceleratorName but handling keycodes. This is only useful for system-level components, applications should use acceleratorParse instead.

acceleratorParse

acceleratorParse

Arguments

:: (HasCallStack, MonadIO m)

=> Text

accelerator: string representing an accelerator

-> m (Bool, Word32, [ModifierType])

Parses a string representing an accelerator. The format looks like “<Control>a” or “<Shift><Alt>F1”.

The parser is fairly liberal and allows lower or upper case, and also abbreviations such as “<Ctl>” and “<Ctrl>”. Key names are parsed using keyvalFromName. For character keys the name is not the symbol, but the lowercase name, e.g. one would use “<Ctrl>minus” instead of “<Ctrl>-”.

If the parse fails, acceleratorKey and acceleratorMods will be set to 0 (zero).

acceleratorParseWithKeycode

acceleratorParseWithKeycode

Arguments

:: (HasCallStack, MonadIO m, IsDisplay a)

=> Text

accelerator: string representing an accelerator

-> Maybe a

display: the Display to look up acceleratorCodes in

-> m (Bool, Word32, [Word32], [ModifierType])

Returns: True if parsing succeeded

Parses a string representing an accelerator, similarly to acceleratorParse but handles keycodes as well. This is only useful for system-level components, applications should use acceleratorParse instead.

If acceleratorCodes is given and the result stored in it is non-Nothing, the result must be freed with free.

If a keycode is present in the accelerator and no acceleratorCodes is given, the parse will fail.

If the parse fails, acceleratorKey, acceleratorMods and acceleratorCodes will be set to 0 (zero).

acceleratorValid

acceleratorValid

Arguments

:: (HasCallStack, MonadIO m)

=> Word32

keyval: a GDK keyval

-> [ModifierType]

modifiers: modifier mask

-> m Bool

Returns: True if the accelerator is valid

Determines whether a given keyval and modifier mask constitute a valid keyboard accelerator. For example, the KEY_a keyval plus GDK_CONTROL_MASK is valid - this is a “Ctrl+a” accelerator. But, you can't, for instance, use the KEY_Control_L keyval as an accelerator.

checkVersion

checkVersion

Arguments

:: (HasCallStack, MonadIO m)

=> Word32

requiredMajor: the required major version

-> Word32

requiredMinor: the required minor version

-> Word32

requiredMicro: the required micro version

-> m (Maybe Text)

Returns: Nothing if the GTK library is compatible with the given version, or a string describing the version mismatch. The returned string is owned by GTK and should not be modified or freed.

Checks that the GTK library in use is compatible with the given version. Generally you would pass in the constants MAJOR_VERSION, MINOR_VERSION, MICRO_VERSION as the three arguments to this function; that produces a check that the library in use is compatible with the version of GTK the application or module was compiled against.

Compatibility is defined by two things: first the version of the running library is newer than the version requiredMajor.required_minor.requiredMicro. Second the running library must be binary compatible with the version requiredMajor.required_minor.requiredMicro (same major version.)

This function is primarily for GTK modules; the module can call this function to check that it wasn’t loaded into an incompatible version of GTK. However, such a check isn’t completely reliable, since the module may be linked against an old version of GTK and calling the old version of checkVersion, but still get loaded into an application using a newer version of GTK.

cssParserErrorQuark

cssParserErrorQuark :: (HasCallStack, MonadIO m) => m Word32

No description available in the introspection data.

cssParserWarningQuark

cssParserWarningQuark :: (HasCallStack, MonadIO m) => m Word32

No description available in the introspection data.

disableSetlocale

disableSetlocale :: (HasCallStack, MonadIO m) => m ()

Prevents init, initCheck and gtk_parse_args() from automatically calling setlocale (LC_ALL, ""). You would want to use this function if you wanted to set the locale for your program to something other than the user’s locale, or if you wanted to set different values for different locale categories.

Most programs should not need to call this function.

distributeNaturalAllocation

distributeNaturalAllocation

Arguments

:: (HasCallStack, MonadIO m)

=> Int32

extraSpace: Extra space to redistribute among children after subtracting minimum sizes and any child padding from the overall allocation

-> Word32

nRequestedSizes: Number of requests to fit into the allocation

-> RequestedSize

sizes: An array of structs with a client pointer and a minimum/natural size in the orientation of the allocation.

-> m Int32

Returns: The remainder of extraSpace after redistributing space to sizes.

Distributes extraSpace to child sizes by bringing smaller children up to natural size first.

The remaining space will be added to the minimumSize member of the GtkRequestedSize struct. If all sizes reach their natural size then the remaining space is returned.

getBinaryAge

getBinaryAge

Arguments

:: (HasCallStack, MonadIO m)

=> m Word32

Returns: the binary age of the GTK library

Returns the binary age as passed to libtool when building the GTK library the process is running against. If libtool means nothing to you, don't worry about it.

getDebugFlags

getDebugFlags

Arguments

:: (HasCallStack, MonadIO m)

=> m [DebugFlags]

Returns: the GTK debug flags.

Returns the GTK debug flags that are currently active.

This function is intended for GTK modules that want to adjust their debug output based on GTK debug flags.

getDefaultLanguage

getDefaultLanguage

Arguments

:: (HasCallStack, MonadIO m)

=> m Language

Returns: the default language as a Language, must not be freed

Returns the Language for the default language currently in effect. (Note that this can change over the life of an application.) The default language is derived from the current locale. It determines, for example, whether GTK uses the right-to-left or left-to-right text direction.

This function is equivalent to languageGetDefault. See that function for details.

getInterfaceAge

getInterfaceAge

Arguments

:: (HasCallStack, MonadIO m)

=> m Word32

Returns: the interface age of the GTK library

Returns the interface age as passed to libtool when building the GTK library the process is running against. If libtool means nothing to you, don't worry about it.

getLocaleDirection

getLocaleDirection

Arguments

:: (HasCallStack, MonadIO m)

=> m TextDirection

Returns: the TextDirection of the current locale

Get the direction of the current locale. This is the expected reading direction for text and UI.

This function depends on the current locale being set with setlocale() and will default to setting the TextDirectionLtr direction otherwise. TextDirectionNone will never be returned.

GTK sets the default text direction according to the locale during init, and you should normally use widgetGetDirection or widgetGetDefaultDirection to obtain the current direction.

This function is only needed rare cases when the locale is changed after GTK has already been initialized. In this case, you can use it to update the default text direction as follows:

C code

setlocale (LC_ALL, new_locale);
direction = gtk_get_locale_direction ();
gtk_widget_set_default_direction (direction);

getMajorVersion

getMajorVersion

Arguments

:: (HasCallStack, MonadIO m)

=> m Word32

Returns: the major version number of the GTK library

Returns the major version number of the GTK library. (e.g. in GTK version 3.1.5 this is 3.)

This function is in the library, so it represents the GTK library your code is running against. Contrast with the MAJOR_VERSION macro, which represents the major version of the GTK headers you have included when compiling your code.

getMicroVersion

getMicroVersion

Arguments

:: (HasCallStack, MonadIO m)

=> m Word32

Returns: the micro version number of the GTK library

Returns the micro version number of the GTK library. (e.g. in GTK version 3.1.5 this is 5.)

This function is in the library, so it represents the GTK library your code is are running against. Contrast with the MICRO_VERSION macro, which represents the micro version of the GTK headers you have included when compiling your code.

getMinorVersion

getMinorVersion

Arguments

:: (HasCallStack, MonadIO m)

=> m Word32

Returns: the minor version number of the GTK library

Returns the minor version number of the GTK library. (e.g. in GTK version 3.1.5 this is 1.)

This function is in the library, so it represents the GTK library your code is are running against. Contrast with the MINOR_VERSION macro, which represents the minor version of the GTK headers you have included when compiling your code.

hsvToRgb

hsvToRgb

Arguments

:: (HasCallStack, MonadIO m)

=> Float

h: Hue

-> Float

s: Saturation

-> Float

v: Value

-> m (Float, Float, Float)

Converts a color from HSV space to RGB.

Input values must be in the [0.0, 1.0] range; output values will be in the same range.

init

init :: (HasCallStack, MonadIO m) => m ()

Call this function before using any other GTK functions in your GUI applications. It will initialize everything needed to operate the toolkit and parses some standard command line options.

If you are using Application, you don't have to call init or initCheck; the startup handler does it for you.

This function will terminate your program if it was unable to initialize the windowing system for some reason. If you want your program to fall back to a textual interface you want to call initCheck instead.

GTK calls signal (SIGPIPE, SIG_IGN) during initialization, to ignore SIGPIPE signals, since these are almost never wanted in graphical applications. If you do need to handle SIGPIPE for some reason, reset the handler after init, but notice that other libraries (e.g. libdbus or gvfs) might do similar things.

initCheck

initCheck

Arguments

:: (HasCallStack, MonadIO m)

=> m Bool

Returns: True if the windowing system has been successfully initialized, False otherwise

This function does the same work as init with only a single change: It does not terminate the program if the windowing system can’t be initialized. Instead it returns False on failure.

This way the application can fall back to some other means of communication with the user - for example a curses or command line interface.

isInitialized

isInitialized

Arguments

:: (HasCallStack, MonadIO m)

=> m Bool

Returns: the initialization status

Use this function to check if GTK has been initialized with init or initCheck.

paramSpecExpression

paramSpecExpression

Arguments

:: (HasCallStack, MonadIO m)

=> Text

name: canonical name of the property

-> Text

nick: a user-readable name for the property

-> Text

blurb: a user-readable description of the property

-> [ParamFlags]

flags: flags for the property

-> m GParamSpec

Returns: a newly created property specification

Creates a new ParamSpec instance for a property holding a Expression.

See g_param_spec_internal() for details on the property strings.

printRunPageSetupDialog

printRunPageSetupDialog

Arguments

:: (HasCallStack, MonadIO m, IsWindow a, IsPageSetup b, IsPrintSettings c)

=> Maybe a

parent: transient parent

-> Maybe b

pageSetup: an existing PageSetup

-> c

settings: a PrintSettings

-> m PageSetup

Returns: a new PageSetup

Runs a page setup dialog, letting the user modify the values from pageSetup. If the user cancels the dialog, the returned PageSetup is identical to the passed in pageSetup, otherwise it contains the modifications done in the dialog.

Note that this function may use a recursive mainloop to show the page setup dialog. See printRunPageSetupDialogAsync if this is a problem.

printRunPageSetupDialogAsync

printRunPageSetupDialogAsync

Arguments

:: (HasCallStack, MonadIO m, IsWindow a, IsPageSetup b, IsPrintSettings c)

=> Maybe a

parent: transient parent, or Nothing

-> Maybe b

pageSetup: an existing PageSetup, or Nothing

-> c

settings: a PrintSettings

-> PageSetupDoneFunc

doneCb: a function to call when the user saves the modified page setup

-> m ()

Runs a page setup dialog, letting the user modify the values from pageSetup.

In contrast to printRunPageSetupDialog, this function returns after showing the page setup dialog on platforms that support this, and calls doneCb from a signal handler for the response signal of the dialog.

renderActivity

renderActivity

Arguments

:: (HasCallStack, MonadIO m, IsStyleContext a)

=> a

context: a StyleContext

-> Context

cr: a Context

-> Double

x: X origin of the rectangle

-> Double

y: Y origin of the rectangle

-> Double

width: rectangle width

-> Double

height: rectangle height

-> m ()

Renders an activity indicator (such as in Spinner). The state StateFlagsChecked determines whether there is activity going on.

renderArrow

renderArrow

Arguments

:: (HasCallStack, MonadIO m, IsStyleContext a)

=> a

context: a StyleContext

-> Context

cr: a Context

-> Double

angle: arrow angle from 0 to 2 * PI, being 0 the arrow pointing to the north

-> Double

x: X origin of the render area

-> Double

y: Y origin of the render area

-> Double

size: square side for render area

-> m ()

Renders an arrow pointing to angle.

Typical arrow rendering at 0, 1⁄2 π;, π; and 3⁄2 π:

renderBackground

renderBackground

Arguments

:: (HasCallStack, MonadIO m, IsStyleContext a)

=> a

context: a StyleContext

-> Context

cr: a Context

-> Double

x: X origin of the rectangle

-> Double

y: Y origin of the rectangle

-> Double

width: rectangle width

-> Double

height: rectangle height

-> m ()

Renders the background of an element.

Typical background rendering, showing the effect of background-image, border-width and border-radius:

renderCheck

renderCheck

Arguments

:: (HasCallStack, MonadIO m, IsStyleContext a)

=> a

context: a StyleContext

-> Context

cr: a Context

-> Double

x: X origin of the rectangle

-> Double

y: Y origin of the rectangle

-> Double

width: rectangle width

-> Double

height: rectangle height

-> m ()

Renders a checkmark (as in a CheckButton).

The StateFlagsChecked state determines whether the check is on or off, and StateFlagsInconsistent determines whether it should be marked as undefined.

Typical checkmark rendering:

renderExpander

renderExpander

Arguments

:: (HasCallStack, MonadIO m, IsStyleContext a)

=> a

context: a StyleContext

-> Context

cr: a Context

-> Double

x: X origin of the rectangle

-> Double

y: Y origin of the rectangle

-> Double

width: rectangle width

-> Double

height: rectangle height

-> m ()

Renders an expander (as used in TreeView and Expander) in the area defined by x, y, width, height. The state StateFlagsChecked determines whether the expander is collapsed or expanded.

Typical expander rendering:

renderFocus

renderFocus

Arguments

:: (HasCallStack, MonadIO m, IsStyleContext a)

=> a

context: a StyleContext

-> Context

cr: a Context

-> Double

x: X origin of the rectangle

-> Double

y: Y origin of the rectangle

-> Double

width: rectangle width

-> Double

height: rectangle height

-> m ()

Renders a focus indicator on the rectangle determined by x, y, width, height.

Typical focus rendering:

renderFrame

renderFrame

Arguments

:: (HasCallStack, MonadIO m, IsStyleContext a)

=> a

context: a StyleContext

-> Context

cr: a Context

-> Double

x: X origin of the rectangle

-> Double

y: Y origin of the rectangle

-> Double

width: rectangle width

-> Double

height: rectangle height

-> m ()

Renders a frame around the rectangle defined by x, y, width, height.

Examples of frame rendering, showing the effect of border-image, border-color, border-width, border-radius and junctions:

renderHandle

renderHandle

Arguments

:: (HasCallStack, MonadIO m, IsStyleContext a)

=> a

context: a StyleContext

-> Context

cr: a Context

-> Double

x: X origin of the rectangle

-> Double

y: Y origin of the rectangle

-> Double

width: rectangle width

-> Double

height: rectangle height

-> m ()

Renders a handle (as in Paned and Window’s resize grip), in the rectangle determined by x, y, width, height.

Handles rendered for the paned and grip classes:

renderIcon

renderIcon

Arguments

:: (HasCallStack, MonadIO m, IsStyleContext a, IsTexture b)

=> a

context: a StyleContext

-> Context

cr: a Context

-> b

texture: a Texture containing the icon to draw

-> Double

x: X position for the texture

-> Double

y: Y position for the texture

-> m ()

Renders the icon in texture at the specified x and y coordinates.

This function will render the icon in texture at exactly its size, regardless of scaling factors, which may not be appropriate when drawing on displays with high pixel densities.

renderLayout

renderLayout

Arguments

:: (HasCallStack, MonadIO m, IsStyleContext a, IsLayout b)

=> a

context: a StyleContext

-> Context

cr: a Context

-> Double

x: X origin

-> Double

y: Y origin

-> b

layout: the Layout to render

-> m ()

Renders layout on the coordinates x, y

renderLine

renderLine

Arguments

:: (HasCallStack, MonadIO m, IsStyleContext a)

=> a

context: a StyleContext

-> Context

cr: a Context

-> Double

x0: X coordinate for the origin of the line

-> Double

y0: Y coordinate for the origin of the line

-> Double

x1: X coordinate for the end of the line

-> Double

y1: Y coordinate for the end of the line

-> m ()

Renders a line from (x0, y0) to (x1, y1).

renderOption

renderOption

Arguments

:: (HasCallStack, MonadIO m, IsStyleContext a)

=> a

context: a StyleContext

-> Context

cr: a Context

-> Double

x: X origin of the rectangle

-> Double

y: Y origin of the rectangle

-> Double

width: rectangle width

-> Double

height: rectangle height

-> m ()

Renders an option mark (as in a radio button), the StateFlagsChecked state will determine whether the option is on or off, and StateFlagsInconsistent whether it should be marked as undefined.

Typical option mark rendering:

rgbToHsv

rgbToHsv

Arguments

:: (HasCallStack, MonadIO m)

=> Float

r: Red

-> Float

g: Green

-> Float

b: Blue

-> m (Float, Float, Float)

Converts a color from RGB space to HSV.

Input values must be in the [0.0, 1.0] range; output values will be in the same range.

setDebugFlags

setDebugFlags

Arguments

:: (HasCallStack, MonadIO m)

=> [DebugFlags]

flags: the debug flags to set

-> m ()

Sets the GTK debug flags.

showUri

showUri

Arguments

:: (HasCallStack, MonadIO m, IsWindow a)

=> Maybe a

parent: parent window

-> Text

uri: the uri to show

-> Word32

timestamp: timestamp from the event that triggered this call, or CURRENT_TIME

-> m ()

This function launches the default application for showing a given uri, or shows an error dialog if that fails.

showUriFullFinish

showUriFullFinish

Arguments

:: (HasCallStack, MonadIO m, IsWindow a, IsAsyncResult b)

=> a

parent: the Window passed to showUri

-> b

result: AsyncResult that was passed to callback

-> m ()

(Can throw GError)

Finishes the showUri call and returns the result of the operation.

testAccessibleAssertionMessageRole

testAccessibleAssertionMessageRole :: (HasCallStack, MonadIO m, IsAccessible a) => Text -> Text -> Int32 -> Text -> Text -> a -> AccessibleRole -> AccessibleRole -> m ()

No description available in the introspection data.

testAccessibleHasProperty

testAccessibleHasProperty

Arguments

:: (HasCallStack, MonadIO m, IsAccessible a)

=> a

accessible: a Accessible

-> AccessibleProperty

property: a AccessibleProperty

-> m Bool

Returns: True if the property is set in the accessible

Checks whether the Accessible has property set.

testAccessibleHasRelation

testAccessibleHasRelation

Arguments

:: (HasCallStack, MonadIO m, IsAccessible a)

=> a

accessible: a Accessible

-> AccessibleRelation

relation: a AccessibleRelation

-> m Bool

Returns: True if the relation is set in the accessible

Checks whether the Accessible has relation set.

testAccessibleHasRole

testAccessibleHasRole

Arguments

:: (HasCallStack, MonadIO m, IsAccessible a)

=> a

accessible: a Accessible

-> AccessibleRole

role: a AccessibleRole

-> m Bool

Returns: True if the role matches

Checks whether the Accessible:accessible-role of the accessible is role.

testAccessibleHasState

testAccessibleHasState

Arguments

:: (HasCallStack, MonadIO m, IsAccessible a)

=> a

accessible: a Accessible

-> AccessibleState

state: a AccessibleState

-> m Bool

Returns: True if the state is set in the accessible

Checks whether the Accessible has state set.

testListAllTypes

testListAllTypes

Arguments

:: (HasCallStack, MonadIO m)

=> m ([GType], Word32)

Returns: 0-terminated array of type ids

Return the type ids that have been registered after calling testRegisterAllTypes.

testRegisterAllTypes

testRegisterAllTypes :: (HasCallStack, MonadIO m) => m ()

Force registration of all core GTK object types.

This allowes to refer to any of those object types via typeFromName after calling this function.

testWidgetWaitForDraw

testWidgetWaitForDraw

Arguments

:: (HasCallStack, MonadIO m, IsWidget a)

=> a

widget: the widget to wait for

-> m ()

Enters the main loop and waits for widget to be “drawn”. In this context that means it waits for the frame clock of widget to have run a full styling, layout and drawing cycle.

This function is intended to be used for syncing with actions that depend on widget relayouting or on interaction with the display server.

treeCreateRowDragContent

treeCreateRowDragContent

Arguments

:: (HasCallStack, MonadIO m, IsTreeModel a)

=> a

treeModel: a TreeModel

-> TreePath

path: a row in treeModel

-> m ContentProvider

Returns: a new ContentProvider

Creates a content provider for dragging path from treeModel.

treeGetRowDragData

treeGetRowDragData

Arguments

:: (HasCallStack, MonadIO m)

=> GValue

value: a Value

-> m (Bool, Maybe TreeModel, Maybe TreePath)

Returns: True if selectionData had target type GTK_TYPE_TREE_ROW_DATA is otherwise valid

Obtains a treeModel and path from value of target type GTK_TYPE_TREE_ROW_DATA.

The returned path must be freed with treePathFree.

valueDupExpression

valueDupExpression

Arguments

:: (HasCallStack, MonadIO m)

=> GValue

value: a Value initialized with type GTK_TYPE_EXPRESSION

-> m (Maybe Expression)

Returns: a Expression

Retrieves the Expression stored inside the given value, and acquires a reference to it.

valueGetExpression

valueGetExpression

Arguments

:: (HasCallStack, MonadIO m)

=> GValue

value: a Value initialized with type GTK_TYPE_EXPRESSION

-> m (Maybe Expression)

Returns: a Expression

Retrieves the Expression stored inside the given value.

valueSetExpression

valueSetExpression

Arguments

:: (HasCallStack, MonadIO m, IsExpression a)

=> GValue

value: a Value initialized with type GTK_TYPE_EXPRESSION

-> a

expression: a Expression

-> m ()

Stores the given Expression inside value.

The Value will acquire a reference to the expression.

valueTakeExpression

valueTakeExpression

Arguments

:: (HasCallStack, MonadIO m, IsExpression a)

=> GValue

value: a Value initialized with type GTK_TYPE_EXPRESSION

-> Maybe a

expression: a Expression

-> m ()

Stores the given Expression inside value.

This function transfers the ownership of the expression to the Value.