GI.Gtk.Functions

Methods

accelGroupsActivate

accelGroupsActivate

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

object: the Object, usually a Window, on which to activate the accelerator

-> Word32

accelKey: accelerator keyval from a key event

-> [ModifierType]

accelMods: keyboard state mask from a key event

-> m Bool

Returns: True if an accelerator was activated and handled this keypress

Finds the first accelerator in any AccelGroup attached to object that matches accelKey and accelMods, and activates that accelerator.

accelGroupsFromObject

accelGroupsFromObject

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

object: a Object, usually a Window

-> m [AccelGroup]

Returns: a list of all accel groups which are attached to object

Gets a list of all accel groups which are attached to object.

acceleratorGetDefaultModMask

acceleratorGetDefaultModMask

Arguments

:: (HasCallStack, MonadIO m)

=> m [ModifierType]

Returns: the default accelerator modifier mask

Gets the modifier mask.

The modifier mask determines which modifiers are considered significant for keyboard accelerators. See acceleratorSetDefaultModMask.

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.

Since: 2.6

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.

Since: 3.4

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.

Since: 3.4

acceleratorParse

acceleratorParse

Arguments

:: (HasCallStack, MonadIO m)

=> Text

accelerator: string representing an accelerator

-> m (Word32, [ModifierType])

Parses a string representing an accelerator. The format looks like “<Control>a” or “<Shift><Alt>F1” or “<Release>z” (the last one is for key release).

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)

=> Text

accelerator: string representing an accelerator

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

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

Since: 3.4

acceleratorSetDefaultModMask

acceleratorSetDefaultModMask

Arguments

:: (HasCallStack, MonadIO m)

=> [ModifierType]

defaultModMask: accelerator modifier mask

-> m ()

Sets the modifiers that will be considered significant for keyboard accelerators. The default mod mask depends on the GDK backend in use, but will typically include GDK_CONTROL_MASK | GDK_SHIFT_MASK | GDK_MOD1_MASK | GDK_SUPER_MASK | GDK_HYPER_MASK | GDK_META_MASK. In other words, Control, Shift, Alt, Super, Hyper and Meta. Other modifiers will by default be ignored by AccelGroup.

You must include at least the three modifiers Control, Shift and Alt in any value you pass to this function.

The default mod mask should be changed on application startup, before using any accelerator groups.

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.

alternativeDialogButtonOrder

alternativeDialogButtonOrder

Arguments

:: (HasCallStack, MonadIO m, IsScreen a)

=> Maybe a

screen: a Screen, or Nothing to use the default screen

-> m Bool

Returns: Whether the alternative button order should be used

Deprecated: (Since version 3.10)Deprecated

Returns True if dialogs are expected to use an alternative button order on the screen screen. See gtk_dialog_set_alternative_button_order() for more details about alternative button order.

If you need to use this function, you should probably connect to the notify:gtk-alternative-button-order signal on the Settings object associated to screen, in order to be notified if the button order setting changes.

Since: 2.6

bindingsActivate

bindingsActivate

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

object: object to activate when binding found

-> Word32

keyval: key value of the binding

-> [ModifierType]

modifiers: key modifier of the binding

-> m Bool

Returns: True if a binding was found and activated

Find a key binding matching keyval and modifiers and activate the binding on object.

bindingsActivateEvent

bindingsActivateEvent

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

object: a Object (generally must be a widget)

-> EventKey

event: a EventKey

-> m Bool

Returns: True if a matching key binding was found

Looks up key bindings for object to find one matching event, and if one was found, activate it.

Since: 2.4

cairoShouldDrawWindow

cairoShouldDrawWindow

Arguments

:: (HasCallStack, MonadIO m, IsWindow a)

=> Context

cr: a cairo context

-> a

window: the window to check. window may not be an input-only window.

-> m Bool

Returns: True if window should be drawn

This function is supposed to be called in draw implementations for widgets that support multiple windows. cr must be untransformed from invoking of the draw function. This function will return True if the contents of the given window are supposed to be drawn and False otherwise. Note that when the drawing was not initiated by the windowing system this function will return True for all windows, so you need to draw the bottommost window first. Also, do not use “else if” statements to check which window should be drawn.

Since: 3.0

cairoTransformToWindow

cairoTransformToWindow

Arguments

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

=> Context

cr: the cairo context to transform

-> a

widget: the widget the context is currently centered for

-> b

window: the window to transform the context to

-> m ()

Transforms the given cairo context cr that from widget-relative coordinates to window-relative coordinates. If the widget’s window is not an ancestor of window, no modification will be applied.

This is the inverse to the transformation GTK applies when preparing an expose event to be emitted with the draw signal. It is intended to help porting multiwindow widgets from GTK+ 2 to the rendering architecture of GTK+ 3.

Since: 3.0

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+.

deviceGrabAdd

deviceGrabAdd

Arguments

:: (HasCallStack, MonadIO m, IsWidget a, IsDevice b)

=> a

widget: a Widget

-> b

device: a Device to grab on.

-> Bool

blockOthers: True to prevent other devices to interact with widget.

-> m ()

Adds a GTK+ grab on device, so all the events on device and its associated pointer or keyboard (if any) are delivered to widget. If the blockOthers parameter is True, any other devices will be unable to interact with widget during the grab.

Since: 3.0

deviceGrabRemove

deviceGrabRemove

Arguments

:: (HasCallStack, MonadIO m, IsWidget a, IsDevice b)

=> a

widget: a Widget

-> b

device: a Device

-> m ()

Removes a device grab from the given widget.

You have to pair calls to deviceGrabAdd and deviceGrabRemove.

Since: 3.0

disableSetlocale

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

Prevents init, initCheck, initWithArgs and parseArgs 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

-> [RequestedSize]

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

-> m (Int32, [RequestedSize])

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.

dragCancel

dragCancel

Arguments

:: (HasCallStack, MonadIO m, IsDragContext a)

=> a

context: a DragContext, as e.g. returned by widgetDragBeginWithCoordinates

-> m ()

Cancels an ongoing drag operation on the source side.

If you want to be able to cancel a drag operation in this way, you need to keep a pointer to the drag context, either from an explicit call to widgetDragBeginWithCoordinates, or by connecting to dragBegin.

If context does not refer to an ongoing drag operation, this function does nothing.

If a drag is cancelled in this way, the result argument of dragFailed is set to gTKDRAGRESULTERROR.

Since: 3.16

dragFinish

dragFinish

Arguments

:: (HasCallStack, MonadIO m, IsDragContext a)

=> a

context: the drag context

-> Bool

success: a flag indicating whether the drop was successful

-> Bool

del: a flag indicating whether the source should delete the original data. (This should be True for a move)

-> Word32

time_: the timestamp from the dragDrop signal

-> m ()

Informs the drag source that the drop is finished, and that the data of the drag will no longer be required.

dragGetSourceWidget

dragGetSourceWidget

Arguments

:: (HasCallStack, MonadIO m, IsDragContext a)

=> a

context: a (destination side) drag context

-> m (Maybe Widget)

Returns: if the drag is occurring within a single application, a pointer to the source widget. Otherwise, Nothing.

Determines the source widget for a drag.

dragSetIconDefault

dragSetIconDefault

Arguments

:: (HasCallStack, MonadIO m, IsDragContext a)

=> a

context: the context for a drag (This must be called with a context for the source side of a drag)

-> m ()

Sets the icon for a particular drag to the default icon.

dragSetIconGicon

dragSetIconGicon

Arguments

:: (HasCallStack, MonadIO m, IsDragContext a, IsIcon b)

=> a

context: the context for a drag (This must be called with a context for the source side of a drag)

-> b

icon: a Icon

-> Int32

hotX: the X offset of the hotspot within the icon

-> Int32

hotY: the Y offset of the hotspot within the icon

-> m ()

Sets the icon for a given drag from the given icon. See the documentation for dragSetIconName for more details about using icons in drag and drop.

Since: 3.2

dragSetIconName

dragSetIconName

Arguments

:: (HasCallStack, MonadIO m, IsDragContext a)

=> a

context: the context for a drag (This must be called with a context for the source side of a drag)

-> Text

iconName: name of icon to use

-> Int32

hotX: the X offset of the hotspot within the icon

-> Int32

hotY: the Y offset of the hotspot within the icon

-> m ()

Sets the icon for a given drag from a named themed icon. See the docs for IconTheme for more details. Note that the size of the icon depends on the icon theme (the icon is loaded at the symbolic size GTK_ICON_SIZE_DND), thus hotX and hotY have to be used with care.

Since: 2.8

dragSetIconPixbuf

dragSetIconPixbuf

Arguments

:: (HasCallStack, MonadIO m, IsDragContext a, IsPixbuf b)

=> a

context: the context for a drag (This must be called with a context for the source side of a drag)

-> b

pixbuf: the Pixbuf to use as the drag icon

-> Int32

hotX: the X offset within widget of the hotspot

-> Int32

hotY: the Y offset within widget of the hotspot

-> m ()

Sets pixbuf as the icon for a given drag.

dragSetIconStock

dragSetIconStock

Arguments

:: (HasCallStack, MonadIO m, IsDragContext a)

=> a

context: the context for a drag (This must be called with a context for the source side of a drag)

-> Text

stockId: the ID of the stock icon to use for the drag

-> Int32

hotX: the X offset within the icon of the hotspot

-> Int32

hotY: the Y offset within the icon of the hotspot

-> m ()

Deprecated: (Since version 3.10)Use dragSetIconName instead.

Sets the icon for a given drag from a stock ID.

dragSetIconSurface

dragSetIconSurface

Arguments

:: (HasCallStack, MonadIO m, IsDragContext a)

=> a

context: the context for a drag (This must be called with a context for the source side of a drag)

-> Surface

surface: the surface to use as icon

-> m ()

Sets surface as the icon for a given drag. GTK+ retains references for the arguments, and will release them when they are no longer needed.

To position the surface relative to the mouse, use cairo_surface_set_device_offset() on surface. The mouse cursor will be positioned at the (0,0) coordinate of the surface.

dragSetIconWidget

dragSetIconWidget

Arguments

:: (HasCallStack, MonadIO m, IsDragContext a, IsWidget b)

=> a

context: the context for a drag. (This must be called with a context for the source side of a drag)

-> b

widget: a widget to use as an icon

-> Int32

hotX: the X offset within widget of the hotspot

-> Int32

hotY: the Y offset within widget of the hotspot

-> m ()

Changes the icon for drag operation to a given widget. GTK+ will not destroy the widget, so if you don’t want it to persist, you should connect to the “drag-end” signal and destroy it yourself.

drawInsertionCursor

drawInsertionCursor

Arguments

:: (HasCallStack, MonadIO m, IsWidget a)

=> a

widget: a Widget

-> Context

cr: cairo context to draw to

-> Rectangle

location: location where to draw the cursor (location->width is ignored)

-> Bool

isPrimary: if the cursor should be the primary cursor color.

-> TextDirection

direction: whether the cursor is left-to-right or right-to-left. Should never be GTK_TEXT_DIR_NONE

-> Bool

drawArrow: True to draw a directional arrow on the cursor. Should be False unless the cursor is split.

-> m ()

Deprecated: (Since version 3.4)Use renderInsertionCursor instead.

Draws a text caret on cr at location. This is not a style function but merely a convenience function for drawing the standard cursor shape.

Since: 3.0

eventsPending

eventsPending

Arguments

:: (HasCallStack, MonadIO m)

=> m Bool

Returns: True if any events are pending, False otherwise

Checks if any events are pending.

This can be used to update the UI and invoke timeouts etc. while doing some time intensive computation.

Updating the UI during a long computation

C code

// computation going on...

while (gtk_events_pending ())
  gtk_main_iteration ();

// ...computation continued

false

false

Arguments

:: (HasCallStack, MonadIO m)

=> m Bool

Returns: False

Analogical to true, this function does nothing but always returns False.

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.

Since: 3.0

getCurrentEvent

getCurrentEvent

Arguments

:: (HasCallStack, MonadIO m)

=> m (Maybe Event)

Returns: a copy of the current event, or Nothing if there is no current event. The returned event must be freed with eventFree.

Obtains a copy of the event currently being processed by GTK+.

For example, if you are handling a clicked signal, the current event will be the EventButton that triggered the clicked signal.

getCurrentEventDevice

getCurrentEventDevice

Arguments

:: (HasCallStack, MonadIO m)

=> m (Maybe Device)

Returns: a Device, or Nothing

If there is a current event and it has a device, return that device, otherwise return Nothing.

getCurrentEventState

getCurrentEventState

Arguments

:: (HasCallStack, MonadIO m)

=> m (Bool, [ModifierType])

Returns: True if there was a current event and it had a state field

If there is a current event and it has a state field, place that state field in state and return True, otherwise return False.

getCurrentEventTime

getCurrentEventTime

Arguments

:: (HasCallStack, MonadIO m)

=> m Word32

Returns: the timestamp from the current event, or CURRENT_TIME.

If there is a current event and it has a timestamp, return that timestamp, otherwise return CURRENT_TIME.

getDebugFlags

getDebugFlags

Arguments

:: (HasCallStack, MonadIO m)

=> m Word32

Returns: the GTK+ debug flags.

Returns the GTK+ debug flags.

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.

getEventWidget

getEventWidget

Arguments

:: (HasCallStack, MonadIO m)

=> Event

event: a Event

-> m (Maybe Widget)

Returns: the widget that originally received event, or Nothing

If event is Nothing or the event was not associated with any widget, returns Nothing, otherwise returns the widget that received the event originally.

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.

Since: 3.0

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 direcion.

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

Since: 3.12

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.

Since: 3.0

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.

Since: 3.0

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.

Since: 3.0

getOptionGroup

getOptionGroup

Arguments

:: (HasCallStack, MonadIO m)

=> Bool

openDefaultDisplay: whether to open the default display when parsing the commandline arguments

-> m OptionGroup

Returns: a OptionGroup for the commandline arguments recognized by GTK+

Returns a OptionGroup for the commandline arguments recognized by GTK+ and GDK.

You should add this group to your OptionContext with optionContextAddGroup, if you are using optionContextParse to parse your commandline arguments.

Since: 2.6

grabGetCurrent

grabGetCurrent

Arguments

:: (HasCallStack, MonadIO m)

=> m (Maybe Widget)

Returns: The widget which currently has the grab or Nothing if no grab is active

Queries the current grab of the default window group.

init

init

Arguments

:: (HasCallStack, MonadIO m)

=> Maybe [Text]

argv: Address of the argv parameter of main(), or Nothing. Any options understood by GTK+ are stripped before return.

-> m (Maybe [Text])

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.

Although you are expected to pass the argc, argv parameters from main() to this function, it is possible to pass Nothing if argv is not available or commandline handling is not required.

argc and argv are adjusted accordingly so your own code will never see those standard arguments.

Note that there are some alternative ways to initialize GTK+: if you are calling parseArgs, initCheck, initWithArgs or optionContextParse with the option group returned by getOptionGroup, you don’t have to call init.

And if you are using Application, you don't have to call any of the initialization functions either; the Application::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.

Since 2.18, 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)

=> Maybe [Text]

argv: Address of the argv parameter of main(), or Nothing. Any options understood by GTK+ are stripped before return.

-> m (Bool, Maybe [Text])

Returns: True if the commandline arguments (if any) were valid and 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 commandline arguments couldn’t be parsed or 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.

Note that calling any GTK function or instantiating any GTK type after this function returns False results in undefined behavior.

initWithArgs

initWithArgs

Arguments

:: (HasCallStack, MonadIO m)

=> Maybe [Text]

argv: Address of the argv parameter of main(), or Nothing. Any options understood by GTK+ are stripped before return.

-> Maybe Text

parameterString: a string which is displayed in the first line of --help output, after programname [OPTION...]

-> [OptionEntry]

entries: a Nothing-terminated array of GOptionEntrys describing the options of your program

-> Maybe Text

translationDomain: a translation domain to use for translating the --help output for the options in entries and the parameterString with gettext(), or Nothing

-> m (Maybe [Text])

(Can throw GError)

This function does the same work as initCheck. Additionally, it allows you to add your own commandline options, and it automatically generates nicely formatted --help output. Note that your program will be terminated after writing out the help output.

Since: 2.6

keySnooperRemove

keySnooperRemove

Arguments

:: (HasCallStack, MonadIO m)

=> Word32

snooperHandlerId: Identifies the key snooper to remove

-> m ()

Deprecated: (Since version 3.4)Key snooping should not be done. Events should be handled by widgets.

Removes the key snooper function with the given id.

main

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

Runs the main loop until mainQuit is called.

You can nest calls to main. In that case mainQuit will make the innermost invocation of the main loop return.

mainDoEvent

mainDoEvent

Arguments

:: (HasCallStack, MonadIO m)

=> Event

event: An event to process (normally passed by GDK)

-> m ()

Processes a single GDK event.

This is public only to allow filtering of events between GDK and GTK+. You will not usually need to call this function directly.

While you should not call this function directly, you might want to know how exactly events are handled. So here is what this function does with the event:

1. Compress enter/leave notify events. If the event passed build an enter/leave pair together with the next event (peeked from GDK), both events are thrown away. This is to avoid a backlog of (de-)highlighting widgets crossed by the pointer.
2. Find the widget which got the event. If the widget can’t be determined the event is thrown away unless it belongs to a INCR transaction.
3. Then the event is pushed onto a stack so you can query the currently handled event with getCurrentEvent.
4. The event is sent to a widget. If a grab is active all events for widgets that are not in the contained in the grab widget are sent to the latter with a few exceptions: - Deletion and destruction events are still sent to the event widget for obvious reasons. - Events which directly relate to the visual representation of the event widget. - Leave events are delivered to the event widget if there was an enter event delivered to it before without the paired leave event. - Drag events are not redirected because it is unclear what the semantics of that would be. Another point of interest might be that all key events are first passed through the key snooper functions if there are any. Read the description of gtk_key_snooper_install() if you need this feature.
5. After finishing the delivery the event is popped from the event stack.

mainIteration

mainIteration

Arguments

:: (HasCallStack, MonadIO m)

=> m Bool

Returns: True if mainQuit has been called for the innermost mainloop

Runs a single iteration of the mainloop.

If no events are waiting to be processed GTK+ will block until the next event is noticed. If you don’t want to block look at mainIterationDo or check if any events are pending with eventsPending first.

mainIterationDo

mainIterationDo

Arguments

:: (HasCallStack, MonadIO m)

=> Bool

blocking: True if you want GTK+ to block if no events are pending

-> m Bool

Returns: True if mainQuit has been called for the innermost mainloop

Runs a single iteration of the mainloop. If no events are available either return or block depending on the value of blocking.

mainLevel

mainLevel

Arguments

:: (HasCallStack, MonadIO m)

=> m Word32

Returns: the nesting level of the current invocation of the main loop

Asks for the current nesting level of the main loop.

mainQuit

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

Makes the innermost invocation of the main loop return when it regains control.

paintArrow

paintArrow

Arguments

:: (HasCallStack, MonadIO m, IsStyle a, IsWidget b)

=> a

style: a Style

-> Context

cr: a Context

-> StateType

stateType: a state

-> ShadowType

shadowType: the type of shadow to draw

-> Maybe b

widget: the widget

-> Maybe Text

detail: a style detail

-> ArrowType

arrowType: the type of arrow to draw

-> Bool

fill: True if the arrow tip should be filled

-> Int32

x: x origin of the rectangle to draw the arrow in

-> Int32

y: y origin of the rectangle to draw the arrow in

-> Int32

width: width of the rectangle to draw the arrow in

-> Int32

height: height of the rectangle to draw the arrow in

-> m ()

Deprecated: (Since version 3.0)Use renderArrow instead

Draws an arrow in the given rectangle on cr using the given parameters. arrowType determines the direction of the arrow.

paintBox

paintBox

Arguments

:: (HasCallStack, MonadIO m, IsStyle a, IsWidget b)

=> a

style: a Style

-> Context

cr: a Context

-> StateType

stateType: a state

-> ShadowType

shadowType: the type of shadow to draw

-> Maybe b

widget: the widget

-> Maybe Text

detail: a style detail

-> Int32

x: x origin of the box

-> Int32

y: y origin of the box

-> Int32

width: the width of the box

-> Int32

height: the height of the box

-> m ()

Deprecated: (Since version 3.0)Use renderFrame and renderBackground instead

Draws a box on cr with the given parameters.

paintBoxGap

paintBoxGap

Arguments

:: (HasCallStack, MonadIO m, IsStyle a, IsWidget b)

=> a

style: a Style

-> Context

cr: a Context

-> StateType

stateType: a state

-> ShadowType

shadowType: type of shadow to draw

-> Maybe b

widget: the widget

-> Maybe Text

detail: a style detail

-> Int32

x: x origin of the rectangle

-> Int32

y: y origin of the rectangle

-> Int32

width: width of the rectangle

-> Int32

height: width of the rectangle

-> PositionType

gapSide: side in which to leave the gap

-> Int32

gapX: starting position of the gap

-> Int32

gapWidth: width of the gap

-> m ()

Deprecated: (Since version 3.0)Use renderFrameGap instead

Draws a box in cr using the given style and state and shadow type, leaving a gap in one side.

paintCheck

paintCheck

Arguments

:: (HasCallStack, MonadIO m, IsStyle a, IsWidget b)

=> a

style: a Style

-> Context

cr: a Context

-> StateType

stateType: a state

-> ShadowType

shadowType: the type of shadow to draw

-> Maybe b

widget: the widget

-> Maybe Text

detail: a style detail

-> Int32

x: x origin of the rectangle to draw the check in

-> Int32

y: y origin of the rectangle to draw the check in

-> Int32

width: the width of the rectangle to draw the check in

-> Int32

height: the height of the rectangle to draw the check in

-> m ()

Deprecated: (Since version 3.0)Use renderCheck instead

Draws a check button indicator in the given rectangle on cr with the given parameters.

paintDiamond

paintDiamond

Arguments

:: (HasCallStack, MonadIO m, IsStyle a, IsWidget b)

=> a

style: a Style

-> Context

cr: a Context

-> StateType

stateType: a state

-> ShadowType

shadowType: the type of shadow to draw

-> Maybe b

widget: the widget

-> Maybe Text

detail: a style detail

-> Int32

x: x origin of the rectangle to draw the diamond in

-> Int32

y: y origin of the rectangle to draw the diamond in

-> Int32

width: width of the rectangle to draw the diamond in

-> Int32

height: height of the rectangle to draw the diamond in

-> m ()

Deprecated: (Since version 3.0)Use cairo instead

Draws a diamond in the given rectangle on window using the given parameters.

paintExpander

paintExpander

Arguments

:: (HasCallStack, MonadIO m, IsStyle a, IsWidget b)

=> a

style: a Style

-> Context

cr: a Context

-> StateType

stateType: a state

-> Maybe b

widget: the widget

-> Maybe Text

detail: a style detail

-> Int32

x: the x position to draw the expander at

-> Int32

y: the y position to draw the expander at

-> ExpanderStyle

expanderStyle: the style to draw the expander in; determines whether the expander is collapsed, expanded, or in an intermediate state.

-> m ()

Deprecated: (Since version 3.0)Use renderExpander instead

Draws an expander as used in TreeView. x and y specify the center the expander. The size of the expander is determined by the “expander-size” style property of widget. (If widget is not specified or doesn’t have an “expander-size” property, an unspecified default size will be used, since the caller doesn't have sufficient information to position the expander, this is likely not useful.) The expander is expander_size pixels tall in the collapsed position and expander_size pixels wide in the expanded position.

paintExtension

paintExtension

Arguments

:: (HasCallStack, MonadIO m, IsStyle a, IsWidget b)

=> a

style: a Style

-> Context

cr: a Context

-> StateType

stateType: a state

-> ShadowType

shadowType: type of shadow to draw

-> Maybe b

widget: the widget

-> Maybe Text

detail: a style detail

-> Int32

x: x origin of the extension

-> Int32

y: y origin of the extension

-> Int32

width: width of the extension

-> Int32

height: width of the extension

-> PositionType

gapSide: the side on to which the extension is attached

-> m ()

Deprecated: (Since version 3.0)Use renderExtension instead

Draws an extension, i.e. a notebook tab.

paintFlatBox

paintFlatBox

Arguments

:: (HasCallStack, MonadIO m, IsStyle a, IsWidget b)

=> a

style: a Style

-> Context

cr: a Context

-> StateType

stateType: a state

-> ShadowType

shadowType: the type of shadow to draw

-> Maybe b

widget: the widget

-> Maybe Text

detail: a style detail

-> Int32

x: x origin of the box

-> Int32

y: y origin of the box

-> Int32

width: the width of the box

-> Int32

height: the height of the box

-> m ()

Deprecated: (Since version 3.0)Use renderFrame and renderBackground instead

Draws a flat box on cr with the given parameters.

paintFocus

paintFocus

Arguments

:: (HasCallStack, MonadIO m, IsStyle a, IsWidget b)

=> a

style: a Style

-> Context

cr: a Context

-> StateType

stateType: a state

-> Maybe b

widget: the widget

-> Maybe Text

detail: a style detail

-> Int32

x: the x origin of the rectangle around which to draw a focus indicator

-> Int32

y: the y origin of the rectangle around which to draw a focus indicator

-> Int32

width: the width of the rectangle around which to draw a focus indicator

-> Int32

height: the height of the rectangle around which to draw a focus indicator

-> m ()

Deprecated: (Since version 3.0)Use renderFocus instead

Draws a focus indicator around the given rectangle on cr using the given style.

paintHandle

paintHandle

Arguments

:: (HasCallStack, MonadIO m, IsStyle a, IsWidget b)

=> a

style: a Style

-> Context

cr: a Context

-> StateType

stateType: a state

-> ShadowType

shadowType: type of shadow to draw

-> Maybe b

widget: the widget

-> Maybe Text

detail: a style detail

-> Int32

x: x origin of the handle

-> Int32

y: y origin of the handle

-> Int32

width: with of the handle

-> Int32

height: height of the handle

-> Orientation

orientation: the orientation of the handle

-> m ()

Deprecated: (Since version 3.0)Use renderHandle instead

Draws a handle as used in HandleBox and Paned.

paintHline

paintHline

Arguments

:: (HasCallStack, MonadIO m, IsStyle a, IsWidget b)

=> a

style: a Style

-> Context

cr: a caio_t

-> StateType

stateType: a state

-> Maybe b

widget: the widget

-> Maybe Text

detail: a style detail

-> Int32

x1: the starting x coordinate

-> Int32

x2: the ending x coordinate

-> Int32

y: the y coordinate

-> m ()

Deprecated: (Since version 3.0)Use renderLine instead

Draws a horizontal line from (x1, y) to (x2, y) in cr using the given style and state.

paintLayout

paintLayout

Arguments

:: (HasCallStack, MonadIO m, IsStyle a, IsWidget b, IsLayout c)

=> a

style: a Style

-> Context

cr: a Context

-> StateType

stateType: a state

-> Bool

useText: whether to use the text or foreground graphics context of style

-> Maybe b

widget: the widget

-> Maybe Text

detail: a style detail

-> Int32

x: x origin

-> Int32

y: y origin

-> c

layout: the layout to draw

-> m ()

Deprecated: (Since version 3.0)Use renderLayout instead

Draws a layout on cr using the given parameters.

paintOption

paintOption

Arguments

:: (HasCallStack, MonadIO m, IsStyle a, IsWidget b)

=> a

style: a Style

-> Context

cr: a Context

-> StateType

stateType: a state

-> ShadowType

shadowType: the type of shadow to draw

-> Maybe b

widget: the widget

-> Maybe Text

detail: a style detail

-> Int32

x: x origin of the rectangle to draw the option in

-> Int32

y: y origin of the rectangle to draw the option in

-> Int32

width: the width of the rectangle to draw the option in

-> Int32

height: the height of the rectangle to draw the option in

-> m ()

Deprecated: (Since version 3.0)Use renderOption instead

Draws a radio button indicator in the given rectangle on cr with the given parameters.

paintResizeGrip

paintResizeGrip

Arguments

:: (HasCallStack, MonadIO m, IsStyle a, IsWidget b)

=> a

style: a Style

-> Context

cr: a Context

-> StateType

stateType: a state

-> Maybe b

widget: the widget

-> Maybe Text

detail: a style detail

-> WindowEdge

edge: the edge in which to draw the resize grip

-> Int32

x: the x origin of the rectangle in which to draw the resize grip

-> Int32

y: the y origin of the rectangle in which to draw the resize grip

-> Int32

width: the width of the rectangle in which to draw the resize grip

-> Int32

height: the height of the rectangle in which to draw the resize grip

-> m ()

Deprecated: (Since version 3.0)Use renderHandle instead

Draws a resize grip in the given rectangle on cr using the given parameters.

paintShadow

paintShadow

Arguments

:: (HasCallStack, MonadIO m, IsStyle a, IsWidget b)

=> a

style: a Style

-> Context

cr: a Context

-> StateType

stateType: a state

-> ShadowType

shadowType: type of shadow to draw

-> Maybe b

widget: the widget

-> Maybe Text

detail: a style detail

-> Int32

x: x origin of the rectangle

-> Int32

y: y origin of the rectangle

-> Int32

width: width of the rectangle

-> Int32

height: width of the rectangle

-> m ()

Deprecated: (Since version 3.0)Use renderFrame instead

Draws a shadow around the given rectangle in cr using the given style and state and shadow type.

paintShadowGap

paintShadowGap

Arguments

:: (HasCallStack, MonadIO m, IsStyle a, IsWidget b)

=> a

style: a Style

-> Context

cr: a Context

-> StateType

stateType: a state

-> ShadowType

shadowType: type of shadow to draw

-> Maybe b

widget: the widget

-> Maybe Text

detail: a style detail

-> Int32

x: x origin of the rectangle

-> Int32

y: y origin of the rectangle

-> Int32

width: width of the rectangle

-> Int32

height: width of the rectangle

-> PositionType

gapSide: side in which to leave the gap

-> Int32

gapX: starting position of the gap

-> Int32

gapWidth: width of the gap

-> m ()

Deprecated: (Since version 3.0)Use renderFrameGap instead

Draws a shadow around the given rectangle in cr using the given style and state and shadow type, leaving a gap in one side.

paintSlider

paintSlider

Arguments

:: (HasCallStack, MonadIO m, IsStyle a, IsWidget b)

=> a

style: a Style

-> Context

cr: a Context

-> StateType

stateType: a state

-> ShadowType

shadowType: a shadow

-> Maybe b

widget: the widget

-> Maybe Text

detail: a style detail

-> Int32

x: the x origin of the rectangle in which to draw a slider

-> Int32

y: the y origin of the rectangle in which to draw a slider

-> Int32

width: the width of the rectangle in which to draw a slider

-> Int32

height: the height of the rectangle in which to draw a slider

-> Orientation

orientation: the orientation to be used

-> m ()

Deprecated: (Since version 3.0)Use renderSlider instead

Draws a slider in the given rectangle on cr using the given style and orientation.

paintSpinner

paintSpinner

Arguments

:: (HasCallStack, MonadIO m, IsStyle a, IsWidget b)

=> a

style: a Style

-> Context

cr: a Context

-> StateType

stateType: a state

-> Maybe b

widget: the widget (may be Nothing)

-> Maybe Text

detail: a style detail (may be Nothing)

-> Word32

step: the nth step

-> Int32

x: the x origin of the rectangle in which to draw the spinner

-> Int32

y: the y origin of the rectangle in which to draw the spinner

-> Int32

width: the width of the rectangle in which to draw the spinner

-> Int32

height: the height of the rectangle in which to draw the spinner

-> m ()

Deprecated: (Since version 3.0)Use renderIcon and the StyleContext you are drawing instead

Draws a spinner on window using the given parameters.

paintTab

paintTab

Arguments

:: (HasCallStack, MonadIO m, IsStyle a, IsWidget b)

=> a

style: a Style

-> Context

cr: a Context

-> StateType

stateType: a state

-> ShadowType

shadowType: the type of shadow to draw

-> Maybe b

widget: the widget

-> Maybe Text

detail: a style detail

-> Int32

x: x origin of the rectangle to draw the tab in

-> Int32

y: y origin of the rectangle to draw the tab in

-> Int32

width: the width of the rectangle to draw the tab in

-> Int32

height: the height of the rectangle to draw the tab in

-> m ()

Deprecated: (Since version 3.0)Use cairo instead

Draws an option menu tab (i.e. the up and down pointing arrows) in the given rectangle on cr using the given parameters.

paintVline

paintVline

Arguments

:: (HasCallStack, MonadIO m, IsStyle a, IsWidget b)

=> a

style: a Style

-> Context

cr: a Context

-> StateType

stateType: a state

-> Maybe b

widget: the widget

-> Maybe Text

detail: a style detail

-> Int32

y1_: the starting y coordinate

-> Int32

y2_: the ending y coordinate

-> Int32

x: the x coordinate

-> m ()

Deprecated: (Since version 3.0)Use renderLine instead

Draws a vertical line from (x, y1_) to (x, y2_) in cr using the given style and state.

parseArgs

parseArgs

Arguments

:: (HasCallStack, MonadIO m)

=> [Text]

argv: a pointer to the array of command line arguments

-> m (Bool, [Text])

Returns: True if initialization succeeded, otherwise False

Parses command line arguments, and initializes global attributes of GTK+, but does not actually open a connection to a display. (See displayOpen, getDisplayArgName)

Any arguments used by GTK+ or GDK are removed from the array and argc and argv are updated accordingly.

There is no need to call this function explicitly if you are using init, or initCheck.

Note that many aspects of GTK+ require a display connection to function, so this way of initializing GTK+ is really only useful for specialized use cases.

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.

Since: 2.10

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.

Since: 2.10

propagateEvent

propagateEvent

Arguments

:: (HasCallStack, MonadIO m, IsWidget a)

=> a

widget: a Widget

-> Event

event: an event

-> m ()

Sends an event to a widget, propagating the event to parent widgets if the event remains unhandled.

Events received by GTK+ from GDK normally begin in mainDoEvent. Depending on the type of event, existence of modal dialogs, grabs, etc., the event may be propagated; if so, this function is used.

propagateEvent calls widgetEvent on each widget it decides to send the event to. So widgetEvent is the lowest-level function; it simply emits the event and possibly an event-specific signal on a widget. propagateEvent is a bit higher-level, and mainDoEvent is the highest level.

All that said, you most likely don’t want to use any of these functions; synthesizing events is rarely needed. There are almost certainly better ways to achieve your goals. For example, use windowInvalidateRect or widgetQueueDraw instead of making up expose events.

rcAddDefaultFile

rcAddDefaultFile

Arguments

:: (HasCallStack, MonadIO m)

=> [Char]

filename: the pathname to the file. If filename is not absolute, it is searched in the current directory.

-> m ()

Deprecated: (Since version 3.0)Use StyleContext with a custom StyleProvider instead

Adds a file to the list of files to be parsed at the end of init.

rcFindModuleInPath

rcFindModuleInPath

Arguments

:: (HasCallStack, MonadIO m)

=> Text

moduleFile: name of a theme engine

-> m [Char]

Returns: The filename, if found (must be freed with free), otherwise Nothing.

Deprecated: (Since version 3.0)Use CssProvider instead.

Searches for a theme engine in the GTK+ search path. This function is not useful for applications and should not be used.

rcFindPixmapInPath

rcFindPixmapInPath

Arguments

:: (HasCallStack, MonadIO m, IsSettings a)

=> a

settings: a Settings

-> Scanner

scanner: Scanner used to get line number information for the warning message, or Nothing

-> Text

pixmapFile: name of the pixmap file to locate.

-> m [Char]

Returns: the filename.

Deprecated: (Since version 3.0)Use CssProvider instead.

Looks up a file in pixmap path for the specified Settings. If the file is not found, it outputs a warning message using g_warning() and returns Nothing.

rcGetDefaultFiles

rcGetDefaultFiles

Arguments

:: (HasCallStack, MonadIO m)

=> m [[Char]]

Returns: A Nothing-terminated array of filenames. This memory is owned by GTK+ and must not be freed by the application. If you want to store this information, you should make a copy.

Deprecated: (Since version 3.0)Use StyleContext instead

Retrieves the current list of RC files that will be parsed at the end of init.

rcGetImModuleFile

rcGetImModuleFile

Arguments

:: (HasCallStack, MonadIO m)

=> m [Char]

Returns: a newly-allocated string containing the name of the file listing the IM modules available for loading

Deprecated: (Since version 3.0)Use CssProvider instead.

Obtains the path to the IM modules file. See the documentation of the GTK_IM_MODULE_FILE environment variable for more details.

rcGetImModulePath

rcGetImModulePath

Arguments

:: (HasCallStack, MonadIO m)

=> m [Char]

Returns: a newly-allocated string containing the path in which to look for IM modules.

Deprecated: (Since version 3.0)Use CssProvider instead.

Obtains the path in which to look for IM modules. See the documentation of the GTK_PATH environment variable for more details about looking up modules. This function is useful solely for utilities supplied with GTK+ and should not be used by applications under normal circumstances.

rcGetModuleDir

rcGetModuleDir

Arguments

:: (HasCallStack, MonadIO m)

=> m [Char]

Returns: the directory. (Must be freed with free)

Deprecated: (Since version 3.0)Use CssProvider instead.

Returns a directory in which GTK+ looks for theme engines. For full information about the search for theme engines, see the docs for GTK_PATH in [Running GTK+ Applications][gtk-running].

rcGetStyle

rcGetStyle

Arguments

:: (HasCallStack, MonadIO m, IsWidget a)

=> a

widget: a Widget

-> m Style

Returns: the resulting style. No refcount is added to the returned style, so if you want to save this style around, you should add a reference yourself.

Deprecated: (Since version 3.0)Use StyleContext instead

Finds all matching RC styles for a given widget, composites them together, and then creates a Style representing the composite appearance. (GTK+ actually keeps a cache of previously created styles, so a new style may not be created.)

rcGetStyleByPaths

rcGetStyleByPaths

Arguments

:: (HasCallStack, MonadIO m, IsSettings a)

=> a

settings: a Settings object

-> Maybe Text

widgetPath: the widget path to use when looking up the style, or Nothing if no matching against the widget path should be done

-> Maybe Text

classPath: the class path to use when looking up the style, or Nothing if no matching against the class path should be done.

-> GType

type: a type that will be used along with parent types of this type when matching against class styles, or G_TYPE_NONE

-> m (Maybe Style)

Returns: A style created by matching with the supplied paths, or Nothing if nothing matching was specified and the default style should be used. The returned value is owned by GTK+ as part of an internal cache, so you must call objectRef on the returned value if you want to keep a reference to it.

Deprecated: (Since version 3.0)Use StyleContext instead

Creates up a Style from styles defined in a RC file by providing the raw components used in matching. This function may be useful when creating pseudo-widgets that should be themed like widgets but don’t actually have corresponding GTK+ widgets. An example of this would be items inside a GNOME canvas widget.

The action of rcGetStyle is similar to:

C code

gtk_widget_path (widget, NULL, &path, NULL);
gtk_widget_class_path (widget, NULL, &class_path, NULL);
gtk_rc_get_style_by_paths (gtk_widget_get_settings (widget),
                           path, class_path,
                           G_OBJECT_TYPE (widget));

rcGetThemeDir

rcGetThemeDir

Arguments

:: (HasCallStack, MonadIO m)

=> m Text

Returns: The directory (must be freed with free).

Deprecated: (Since version 3.0)Use CssProvider instead.

Returns the standard directory in which themes should be installed. (GTK+ does not actually use this directory itself.)

rcParse

rcParse

Arguments

:: (HasCallStack, MonadIO m)

=> Text

filename: the filename of a file to parse. If filename is not absolute, it is searched in the current directory.

-> m ()

Deprecated: (Since version 3.0)Use CssProvider instead.

Parses a given resource file.

rcParseColor

rcParseColor

Arguments

:: (HasCallStack, MonadIO m)

=> Scanner

scanner: a Scanner

-> m (Word32, Color)

Returns: TokenTypeNone if parsing succeeded, otherwise the token that was expected but not found

Deprecated: (Since version 3.0)Use CssProvider instead

Parses a color in the format expected in a RC file.

Note that theme engines should use rcParseColorFull in order to support symbolic colors.

rcParseColorFull

rcParseColorFull

Arguments

:: (HasCallStack, MonadIO m, IsRcStyle a)

=> Scanner

scanner: a Scanner

-> Maybe a

style: a RcStyle, or Nothing

-> m (Word32, Color)

Returns: TokenTypeNone if parsing succeeded, otherwise the token that was expected but not found

Deprecated: (Since version 3.0)Use CssProvider instead

Parses a color in the format expected in a RC file. If style is not Nothing, it will be consulted to resolve references to symbolic colors.

Since: 2.12

rcParsePriority

rcParsePriority

Arguments

:: (HasCallStack, MonadIO m)

=> Scanner

scanner: a Scanner (must be initialized for parsing an RC file)

-> PathPriorityType

priority: A pointer to PathPriorityType variable in which to store the result.

-> m Word32

Returns: TokenTypeNone if parsing succeeded, otherwise the token that was expected but not found.

Deprecated: (Since version 3.0)Use CssProvider instead

Parses a PathPriorityType variable from the format expected in a RC file.

rcParseState

rcParseState

Arguments

:: (HasCallStack, MonadIO m)

=> Scanner

scanner: a Scanner (must be initialized for parsing an RC file)

-> m (Word32, StateType)

Returns: TokenTypeNone if parsing succeeded, otherwise the token that was expected but not found.

Deprecated: (Since version 3.0)Use CssProvider instead

Parses a StateType variable from the format expected in a RC file.

rcParseString

rcParseString

Arguments

:: (HasCallStack, MonadIO m)

=> Text

rcString: a string to parse.

-> m ()

Deprecated: (Since version 3.0)Use CssProvider instead.

Parses resource information directly from a string.

rcReparseAll

rcReparseAll

Arguments

:: (HasCallStack, MonadIO m)

=> m Bool

Returns: True if the files were reread.

Deprecated: (Since version 3.0)Use CssProvider instead.

If the modification time on any previously read file for the default Settings has changed, discard all style information and then reread all previously read RC files.

rcReparseAllForSettings

rcReparseAllForSettings

Arguments

:: (HasCallStack, MonadIO m, IsSettings a)

=> a

settings: a Settings

-> Bool

forceLoad: load whether or not anything changed

-> m Bool

Returns: True if the files were reread.

Deprecated: (Since version 3.0)Use CssProvider instead.

If the modification time on any previously read file for the given Settings has changed, discard all style information and then reread all previously read RC files.

rcResetStyles

rcResetStyles

Arguments

:: (HasCallStack, MonadIO m, IsSettings a)

=> a

settings: a Settings

-> m ()

Deprecated: (Since version 3.0)Use CssProvider instead.

This function recomputes the styles for all widgets that use a particular Settings object. (There is one Settings object per Screen, see settingsGetForScreen); It is useful when some global parameter has changed that affects the appearance of all widgets, because when a widget gets a new style, it will both redraw and recompute any cached information about its appearance. As an example, it is used when the default font size set by the operating system changes. Note that this function doesn’t affect widgets that have a style set explicitly on them with widgetSetStyle.

Since: 2.4

rcSetDefaultFiles

rcSetDefaultFiles

Arguments

:: (HasCallStack, MonadIO m)

=> [[Char]]

filenames: A Nothing-terminated list of filenames.

-> m ()

Deprecated: (Since version 3.0)Use StyleContext with a custom StyleProvider instead

Sets the list of files that GTK+ will read at the end of init.

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.

Since: 3.0

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

Since: 3.0

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:

Since: 3.0.

renderBackgroundGetClip

renderBackgroundGetClip

Arguments

:: (HasCallStack, MonadIO m, IsStyleContext a)

=> a

context: a StyleContext

-> Double

x: X origin of the rectangle

-> Double

y: Y origin of the rectangle

-> Double

width: rectangle width

-> Double

height: rectangle height

-> m Rectangle

Returns the area that will be affected (i.e. drawn to) when calling renderBackground for the given context and rectangle.

Since: 3.20

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:

Since: 3.0

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:

Since: 3.0

renderExtension

renderExtension

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

-> PositionType

gapSide: side where the gap is

-> m ()

Renders a extension (as in a Notebook tab) in the rectangle defined by x, y, width, height. The side where the extension connects to is defined by gapSide.

Typical extension rendering:

Since: 3.0

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:

Since: 3.0

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:

Since: 3.0

renderFrameGap

renderFrameGap

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

-> PositionType

gapSide: side where the gap is

-> Double

xy0Gap: initial coordinate (X or Y depending on gapSide) for the gap

-> Double

xy1Gap: end coordinate (X or Y depending on gapSide) for the gap

-> m ()

Deprecated: (Since version 3.24)Use renderFrame instead. Themes can create gaps by omitting borders via CSS.

Renders a frame around the rectangle defined by (x, y, width, height), leaving a gap on one side. xy0Gap and xy1Gap will mean X coordinates for PositionTypeTop and PositionTypeBottom gap sides, and Y coordinates for PositionTypeLeft and PositionTypeRight.

Typical rendering of a frame with a gap:

Since: 3.0

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 HandleBox, Paned and Window’s resize grip), in the rectangle determined by x, y, width, height.

Handles rendered for the paned and grip classes:

Since: 3.0

renderIcon

renderIcon

Arguments

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

=> a

context: a StyleContext

-> Context

cr: a Context

-> b

pixbuf: a Pixbuf containing the icon to draw

-> Double

x: X position for the pixbuf

-> Double

y: Y position for the pixbuf

-> m ()

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

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

You probably want to use renderIconSurface instead, if you already have a Cairo surface.

Since: 3.2

renderIconPixbuf

renderIconPixbuf

Arguments

:: (HasCallStack, MonadIO m, IsStyleContext a)

=> a

context: a StyleContext

-> IconSource

source: the IconSource specifying the icon to render

-> Int32

size: the size (tIconSize) to render the icon at. A size of (GtkIconSize) -1 means render at the size of the source and don’t scale.

-> m Pixbuf

Returns: a newly-created Pixbuf containing the rendered icon

Deprecated: (Since version 3.10)Use iconThemeLoadIcon instead.

Renders the icon specified by source at the given size, returning the result in a pixbuf.

Since: 3.0

renderIconSurface

renderIconSurface

Arguments

:: (HasCallStack, MonadIO m, IsStyleContext a)

=> a

context: a StyleContext

-> Context

cr: a Context

-> Surface

surface: a Surface containing the icon to draw

-> Double

x: X position for the icon

-> Double

y: Y position for the incon

-> m ()

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

Since: 3.10

renderInsertionCursor

renderInsertionCursor

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 of the text

-> Int32

index: the index in the Layout

-> Direction

direction: the Direction of the text

-> m ()

Draws a text caret on cr at the specified index of layout.

Since: 3.4

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

Since: 3.0

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

Since: 3.0

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

Since: 3.0

renderSlider

renderSlider

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

-> Orientation

orientation: orientation of the slider

-> m ()

Renders a slider (as in Scale) in the rectangle defined by x, y, width, height. orientation defines whether the slider is vertical or horizontal.

Typical slider rendering:

Since: 3.0

rgbToHsv

rgbToHsv

Arguments

:: (HasCallStack, MonadIO m)

=> Double

r: Red

-> Double

g: Green

-> Double

b: Blue

-> m (Double, Double, Double)

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.

Since: 2.14

selectionAddTarget

selectionAddTarget

Arguments

:: (HasCallStack, MonadIO m, IsWidget a)

=> a

widget: a Widget

-> Atom

selection: the selection

-> Atom

target: target to add.

-> Word32

info: A unsigned integer which will be passed back to the application.

-> m ()

Appends a specified target to the list of supported targets for a given widget and selection.

selectionAddTargets

selectionAddTargets

Arguments

:: (HasCallStack, MonadIO m, IsWidget a)

=> a

widget: a Widget

-> Atom

selection: the selection

-> [TargetEntry]

targets: a table of targets to add

-> m ()

Prepends a table of targets to the list of supported targets for a given widget and selection.

selectionClearTargets

selectionClearTargets

Arguments

:: (HasCallStack, MonadIO m, IsWidget a)

=> a

widget: a Widget

-> Atom

selection: an atom representing a selection

-> m ()

Remove all targets registered for the given selection for the widget.

selectionConvert

selectionConvert

Arguments

:: (HasCallStack, MonadIO m, IsWidget a)

=> a

widget: The widget which acts as requestor

-> Atom

selection: Which selection to get

-> Atom

target: Form of information desired (e.g., STRING)

-> Word32

time_: Time of request (usually of triggering event) In emergency, you could use CURRENT_TIME

-> m Bool

Returns: True if requested succeeded. False if we could not process request. (e.g., there was already a request in process for this widget).

Requests the contents of a selection. When received, a “selection-received” signal will be generated.

selectionOwnerSet

selectionOwnerSet

Arguments

:: (HasCallStack, MonadIO m, IsWidget a)

=> Maybe a

widget: a Widget, or Nothing.

-> Atom

selection: an interned atom representing the selection to claim

-> Word32

time_: timestamp with which to claim the selection

-> m Bool

Returns: True if the operation succeeded

Claims ownership of a given selection for a particular widget, or, if widget is Nothing, release ownership of the selection.

selectionOwnerSetForDisplay

selectionOwnerSetForDisplay

Arguments

:: (HasCallStack, MonadIO m, IsDisplay a, IsWidget b)

=> a

display: the Display where the selection is set

-> Maybe b

widget: new selection owner (a Widget), or Nothing.

-> Atom

selection: an interned atom representing the selection to claim.

-> Word32

time_: timestamp with which to claim the selection

-> m Bool

Returns: TRUE if the operation succeeded

Claim ownership of a given selection for a particular widget, or, if widget is Nothing, release ownership of the selection.

Since: 2.2

selectionRemoveAll

selectionRemoveAll

Arguments

:: (HasCallStack, MonadIO m, IsWidget a)

=> a

widget: a Widget

-> m ()

Removes all handlers and unsets ownership of all selections for a widget. Called when widget is being destroyed. This function will not generally be called by applications.

setDebugFlags

setDebugFlags :: (HasCallStack, MonadIO m) => Word32 -> m ()

Sets the GTK+ debug flags.

showUri

showUri

Arguments

:: (HasCallStack, MonadIO m, IsScreen a)

=> Maybe a

screen: screen to show the uri on or Nothing for the default screen

-> Text

uri: the uri to show

-> Word32

timestamp: a timestamp to prevent focus stealing

-> m ()

(Can throw GError)

A convenience function for launching the default application to show the uri. Like showUriOnWindow, but takes a screen as transient parent instead of a window.

Note that this function is deprecated as it does not pass the necessary information for helpers to parent their dialog properly, when run from sandboxed applications for example.

Since: 2.14

showUriOnWindow

showUriOnWindow

Arguments

:: (HasCallStack, MonadIO m, IsWindow a)

=> Maybe a

parent: parent window

-> Text

uri: the uri to show

-> Word32

timestamp: a timestamp to prevent focus stealing

-> m ()

(Can throw GError)

This is a convenience function for launching the default application to show the uri. The uri must be of a form understood by GIO (i.e. you need to install gvfs to get support for uri schemes such as http:// or ftp://, as only local files are handled by GIO itself). Typical examples are

• file:///home/gnome/pict.jpg

• http://www.gnome.org

• mailto:[e-mail]

Ideally the timestamp is taken from the event triggering the showUri call. If timestamp is not known you can take CURRENT_TIME.

This is the recommended call to be used as it passes information necessary for sandbox helpers to parent their dialogs properly.

Since: 3.22

stockAdd

stockAdd

Arguments

:: (HasCallStack, MonadIO m)

=> [StockItem]

items: a StockItem or array of items

-> m ()

Deprecated: (Since version 3.10)

Registers each of the stock items in items. If an item already exists with the same stock ID as one of the items, the old item gets replaced. The stock items are copied, so GTK+ does not hold any pointer into items and items can be freed. Use stockAddStatic if items is persistent and GTK+ need not copy the array.

stockAddStatic

stockAddStatic

Arguments

:: (HasCallStack, MonadIO m)

=> [StockItem]

items: a StockItem or array of StockItem

-> m ()

Deprecated: (Since version 3.10)

Same as stockAdd, but doesn’t copy items, so items must persist until application exit.

stockListIds

stockListIds

Arguments

:: (HasCallStack, MonadIO m)

=> m [Text]

Returns: a list of known stock IDs

Deprecated: (Since version 3.10)

Retrieves a list of all known stock IDs added to a IconFactory or registered with stockAdd. The list must be freed with g_slist_free(), and each string in the list must be freed with free.

stockLookup

stockLookup

Arguments

:: (HasCallStack, MonadIO m)

=> Text

stockId: a stock item name

-> m (Bool, StockItem)

Returns: True if item was initialized

Deprecated: (Since version 3.10)

Fills item with the registered values for stockId, returning True if stockId was known.

stockSetTranslateFunc

stockSetTranslateFunc

Arguments

:: (HasCallStack, MonadIO m)

=> Text

domain: the translation domain for which func shall be used

-> TranslateFunc

func: a TranslateFunc

-> m ()

Deprecated: (Since version 3.10)

Sets a function to be used for translating the label of a stock item.

If no function is registered for a translation domain, dgettext is used.

The function is used for all stock items whose translationDomain matches domain. Note that it is possible to use strings different from the actual gettext translation domain of your application for this, as long as your TranslateFunc uses the correct domain when calling dgettext(). This can be useful, e.g. when dealing with message contexts:

C code

GtkStockItem items[] = {
 { MY_ITEM1, NC_("odd items", "Item 1"), 0, 0, "odd-item-domain" },
 { MY_ITEM2, NC_("even items", "Item 2"), 0, 0, "even-item-domain" },
};

gchar *
my_translate_func (const gchar *msgid,
                   gpointer     data)
{
  gchar *msgctxt = data;

  return (gchar*)g_dpgettext2 (GETTEXT_PACKAGE, msgctxt, msgid);
}

...

gtk_stock_add (items, G_N_ELEMENTS (items));
gtk_stock_set_translate_func ("odd-item-domain", my_translate_func, "odd items");
gtk_stock_set_translate_func ("even-item-domain", my_translate_func, "even items");

Since: 2.8

targetTableFree

targetTableFree

Arguments

:: (HasCallStack, MonadIO m)

=> [TargetEntry]

targets: a TargetEntry array

-> m ()

This function frees a target table as returned by targetTableNewFromList

Since: 2.10

targetTableNewFromList

targetTableNewFromList

Arguments

:: (HasCallStack, MonadIO m)

=> TargetList

list: a TargetList

-> m [TargetEntry]

Returns: the new table.

This function creates an TargetEntry array that contains the same targets as the passed list. The returned table is newly allocated and should be freed using targetTableFree when no longer needed.

Since: 2.10

targetsIncludeImage

targetsIncludeImage

Arguments

:: (HasCallStack, MonadIO m)

=> [Atom]

targets: an array of GdkAtoms

-> Bool

writable: whether to accept only targets for which GTK+ knows how to convert a pixbuf into the format

-> m Bool

Returns: True if targets include a suitable target for images, otherwise False.

Determines if any of the targets in targets can be used to provide a Pixbuf.

Since: 2.10

targetsIncludeRichText

targetsIncludeRichText

Arguments

:: (HasCallStack, MonadIO m, IsTextBuffer a)

=> [Atom]

targets: an array of GdkAtoms

-> a

buffer: a TextBuffer

-> m Bool

Returns: True if targets include a suitable target for rich text, otherwise False.

Determines if any of the targets in targets can be used to provide rich text.

Since: 2.10

targetsIncludeText

targetsIncludeText

Arguments

:: (HasCallStack, MonadIO m)

=> [Atom]

targets: an array of GdkAtoms

-> m Bool

Returns: True if targets include a suitable target for text, otherwise False.

Determines if any of the targets in targets can be used to provide text.

Since: 2.10

targetsIncludeUri

targetsIncludeUri

Arguments

:: (HasCallStack, MonadIO m)

=> [Atom]

targets: an array of GdkAtoms

-> m Bool

Returns: True if targets include a suitable target for uri lists, otherwise False.

Determines if any of the targets in targets can be used to provide an uri list.

Since: 2.10

testCreateSimpleWindow

testCreateSimpleWindow

Arguments

:: (HasCallStack, MonadIO m)

=> Text

windowTitle: Title of the window to be displayed.

-> Text

dialogText: Text inside the window to be displayed.

-> m Widget

Returns: a widget pointer to the newly created GtkWindow.

Deprecated: (Since version 3.20)This testing infrastructure is phased out in favor of reftests.

Create a simple window with window title windowTitle and text contents dialogText. The window will quit any running main-loop when destroyed, and it will automatically be destroyed upon test function teardown.

Since: 2.14

testFindLabel

testFindLabel

Arguments

:: (HasCallStack, MonadIO m, IsWidget a)

=> a

widget: Valid label or container widget.

-> Text

labelPattern: Shell-glob pattern to match a label string.

-> m Widget

Returns: a GtkLabel widget if any is found.

This function will search widget and all its descendants for a GtkLabel widget with a text string matching labelPattern. The labelPattern may contain asterisks “*” and question marks “?” as placeholders, patternMatch is used for the matching. Note that locales other than "C“ tend to alter (translate” label strings, so this function is genrally only useful in test programs with predetermined locales, see gtk_test_init() for more details.

Since: 2.14

testFindSibling

testFindSibling

Arguments

:: (HasCallStack, MonadIO m, IsWidget a)

=> a

baseWidget: Valid widget, part of a widget hierarchy

-> GType

widgetType: Type of a aearched for sibling widget

-> m Widget

Returns: a widget of type widgetType if any is found.

This function will search siblings of baseWidget and siblings of its ancestors for all widgets matching widgetType. Of the matching widgets, the one that is geometrically closest to baseWidget will be returned. The general purpose of this function is to find the most likely “action” widget, relative to another labeling widget. Such as finding a button or text entry widget, given its corresponding label widget.

Since: 2.14

testFindWidget

testFindWidget

Arguments

:: (HasCallStack, MonadIO m, IsWidget a)

=> a

widget: Container widget, usually a GtkWindow.

-> Text

labelPattern: Shell-glob pattern to match a label string.

-> GType

widgetType: Type of a aearched for label sibling widget.

-> m (Maybe Widget)

Returns: a valid widget if any is found or Nothing.

This function will search the descendants of widget for a widget of type widgetType that has a label matching labelPattern next to it. This is most useful for automated GUI testing, e.g. to find the “OK” button in a dialog and synthesize clicks on it. However see testFindLabel, testFindSibling and testWidgetClick for possible caveats involving the search of such widgets and synthesizing widget events.

Since: 2.14

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.

Since: 2.14

testRegisterAllTypes

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

Force registration of all core Gtk+ and Gdk object types. This allowes to refer to any of those object types via typeFromName after calling this function.

Since: 2.14

testSliderGetValue

testSliderGetValue

Arguments

:: (HasCallStack, MonadIO m, IsWidget a)

=> a

widget: valid widget pointer.

-> m Double

Returns: gtk_adjustment_get_value (adjustment) for an adjustment belonging to widget.

Deprecated: (Since version 3.20)This testing infrastructure is phased out in favor of reftests.

Retrive the literal adjustment value for GtkRange based widgets and spin buttons. Note that the value returned by this function is anything between the lower and upper bounds of the adjustment belonging to widget, and is not a percentage as passed in to testSliderSetPerc.

Since: 2.14

testSliderSetPerc

testSliderSetPerc

Arguments

:: (HasCallStack, MonadIO m, IsWidget a)

=> a

widget: valid widget pointer.

-> Double

percentage: value between 0 and 100.

-> m ()

Deprecated: (Since version 3.20)This testing infrastructure is phased out in favor of reftests.

This function will adjust the slider position of all GtkRange based widgets, such as scrollbars or scales, it’ll also adjust spin buttons. The adjustment value of these widgets is set to a value between the lower and upper limits, according to the percentage argument.

Since: 2.14

testSpinButtonClick

testSpinButtonClick

Arguments

:: (HasCallStack, MonadIO m, IsSpinButton a)

=> a

spinner: valid GtkSpinButton widget.

-> Word32

button: Number of the pointer button for the event, usually 1, 2 or 3.

-> Bool

upwards: True for upwards arrow click, False for downwards arrow click.

-> m Bool

Returns: whether all actions neccessary for the button click simulation were carried out successfully.

Deprecated: (Since version 3.20)This testing infrastructure is phased out in favor of reftests.

This function will generate a button click in the upwards or downwards spin button arrow areas, usually leading to an increase or decrease of spin button’s value.

Since: 2.14

testTextGet

testTextGet

Arguments

:: (HasCallStack, MonadIO m, IsWidget a)

=> a

widget: valid widget pointer.

-> m Text

Returns: new 0-terminated C string, needs to be released with free.

Deprecated: (Since version 3.20)This testing infrastructure is phased out in favor of reftests.

Retrive the text string of widget if it is a GtkLabel, GtkEditable (entry and text widgets) or GtkTextView.

Since: 2.14

testTextSet

testTextSet

Arguments

:: (HasCallStack, MonadIO m, IsWidget a)

=> a

widget: valid widget pointer.

-> Text

string: a 0-terminated C string

-> m ()

Deprecated: (Since version 3.20)This testing infrastructure is phased out in favor of reftests.

Set the text string of widget to string if it is a GtkLabel, GtkEditable (entry and text widgets) or GtkTextView.

Since: 2.14

testWidgetClick

testWidgetClick

Arguments

:: (HasCallStack, MonadIO m, IsWidget a)

=> a

widget: Widget to generate a button click on.

-> Word32

button: Number of the pointer button for the event, usually 1, 2 or 3.

-> [ModifierType]

modifiers: Keyboard modifiers the event is setup with.

-> m Bool

Returns: whether all actions neccessary for the button click simulation were carried out successfully.

Deprecated: (Since version 3.20)This testing infrastructure is phased out in favor of reftests.

This function will generate a button click (button press and button release event) in the middle of the first GdkWindow found that belongs to widget. For windowless widgets like Button (which returns False from widgetGetHasWindow), this will often be an input-only event window. For other widgets, this is usually widget->window. Certain caveats should be considered when using this function, in particular because the mouse pointer is warped to the button click location, see testSimulateButton for details.

Since: 2.14

testWidgetSendKey

testWidgetSendKey

Arguments

:: (HasCallStack, MonadIO m, IsWidget a)

=> a

widget: Widget to generate a key press and release on.

-> Word32

keyval: A Gdk keyboard value.

-> [ModifierType]

modifiers: Keyboard modifiers the event is setup with.

-> m Bool

Returns: whether all actions neccessary for the key event simulation were carried out successfully.

This function will generate keyboard press and release events in the middle of the first GdkWindow found that belongs to widget. For windowless widgets like Button (which returns False from widgetGetHasWindow), this will often be an input-only event window. For other widgets, this is usually widget->window. Certain caveats should be considered when using this function, in particular because the mouse pointer is warped to the key press location, see testSimulateKey for details.

Since: 2.14

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.

Since: 3.10

treeGetRowDragData

treeGetRowDragData

Arguments

:: (HasCallStack, MonadIO m)

=> SelectionData

selectionData: a SelectionData

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

Returns: True if selectionData had target type GTK_TREE_MODEL_ROW and is otherwise valid

Obtains a treeModel and path from selection data of target type GTK_TREE_MODEL_ROW. Normally called from a drag_data_received handler. This function can only be used if selectionData originates from the same process that’s calling this function, because a pointer to the tree model is being passed around. If you aren’t in the same process, then you'll get memory corruption. In the TreeDragDest drag_data_received handler, you can assume that selection data of type GTK_TREE_MODEL_ROW is in from the current process. The returned path must be freed with treePathFree.

treeSetRowDragData

treeSetRowDragData

Arguments

:: (HasCallStack, MonadIO m, IsTreeModel a)

=> SelectionData

selectionData: some SelectionData

-> a

treeModel: a TreeModel

-> TreePath

path: a row in treeModel

-> m Bool

Returns: True if the SelectionData had the proper target type to allow us to set a tree row

Sets selection data of target type GTK_TREE_MODEL_ROW. Normally used in a drag_data_get handler.

true

true

Arguments

:: (HasCallStack, MonadIO m)

=> m Bool

Returns: True

All this function does it to return True.

This can be useful for example if you want to inhibit the deletion of a window. Of course you should not do this as the user expects a reaction from clicking the close icon of the window...

A persistent window

C code

#include <gtk/gtk.h>

int
main (int argc, char **argv)
{
  GtkWidget *win, *but;
  const char *text = "Close yourself. I mean it!";

  gtk_init (&argc, &argv);

  win = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  g_signal_connect (win,
                    "delete-event",
                    G_CALLBACK (gtk_true),
                    NULL);
  g_signal_connect (win, "destroy",
                    G_CALLBACK (gtk_main_quit),
                    NULL);

  but = gtk_button_new_with_label (text);
  g_signal_connect_swapped (but, "clicked",
                            G_CALLBACK (gtk_object_destroy),
                            win);
  gtk_container_add (GTK_CONTAINER (win), but);

  gtk_widget_show_all (win);

  gtk_main ();

  return 0;
}