Functions

Convenience constructor for an application reference

Finds the first accelerator in any GtkAccelGroup attached to object that matches accel_key and accel_mods, and activates that accelerator.

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

Gets the modifier mask.

The modifier mask determines which modifiers are considered significant for keyboard accelerators. See gtk_accelerator_set_default_mod_mask().

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

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

This is only useful for system-level components, applications should use gtk_accelerator_parse() instead.

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

This is only useful for system-level components, applications should use gtk_accelerator_parse() instead.

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

If you need to display accelerators in the user interface, see gtk_accelerator_get_label().

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

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

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 gdk_keyval_from_name(). 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, accelerator_key and accelerator_mods will be set to 0 (zero).

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

If accelerator_codes is given and the result stored in it is non-nil, the result must be freed with g_free().

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

If the parse fails, accelerator_key, accelerator_mods and accelerator_codes will be set to 0 (zero).

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

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.

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

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 GtkSettings object associated to screen, in order to be notified if the button order setting changes.

alternative_dialog_button_order is deprecated: 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 GtkSettings object associated to screen, in order to be notified if the button order setting changes.

alternative_dialog_button_order is deprecated: Deprecated

Parses a signal description from signal_desc and incorporates it into binding_set.

Signal descriptions may either bind a key combination to one or more signals:

  bind "key" {
    "signalname" (param, ...)
    ...
  }

Or they may also unbind a key combination:

  unbind "key"

Key combinations must be in a format that can be parsed by gtk_accelerator_parse().

Override or install a new key binding for keyval with modifiers on binding_set.

Remove a binding previously installed via gtk_binding_entry_add_signal() on binding_set.

Install a binding on binding_set which causes key lookups to be aborted, to prevent bindings from lower priority sets to be activated.

This function returns the binding set named after the type name of the passed in class structure. New binding sets are created on demand by this function.

Find a binding set by its globally unique name.

The set_name can either be a name used for gtk_binding_set_new() or the type name of a class used in gtk_binding_set_by_class().

GTK+ maintains a global list of binding sets. Each binding set has a unique name which needs to be specified upon creation.

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

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

Undocumented

This function is supposed to be called in GtkWidget::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.

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 GtkWidget::draw signal. It is intended to help porting multiwindow widgets from GTK+ 2 to the rendering architecture of GTK+ 3.

Checks that the GTK+ library in use is compatible with the given version. Generally you would pass in the constants GTK_MAJOR_VERSION, GTK_MINOR_VERSION, GTK_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 required_major.required_minor.required_micro. Second the running library must be binary compatible with the version required_major.required_minor.required_micro (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 gtk_check_version(), but still get loaded into an application using a newer version of GTK+.

Undocumented

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 block_others parameter is true, any other devices will be unable to interact with widget during the grab.

Removes a device grab from the given widget.

You have to pair calls to gtk_device_grab_add() and gtk_device_grab_remove().

Prevents gtk_init(), gtk_init_check(), gtk_init_with_args() 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.

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

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

Undocumented

Undocumented

Undocumented

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

Undocumented

Sets the icon for a given drag from a named themed icon. See the docs for GtkIconTheme 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 hot_x and hot_y have to be used with care.

Sets pixbuf as the icon for a given drag.

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

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.

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

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.

draw_insertion_cursor is deprecated: Use gtk_render_insertion_cursor() instead.

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

 // computation going on...

 while (gtk_events_pending ())
   gtk_main_iteration ();

 // ...computation continued

Analogical to gtk_true(), this function does nothing but always returns false.

Registers an error quark for GtkFileChooser if necessary.

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.

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

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

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

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

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

Returns the GTK+ debug flags.

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

Returns the PangoLanguage 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 pango_language_get_default(). See that function for details.

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

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.

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 GTK_TEXT_DIR_LTR direction otherwise. GTK_TEXT_DIR_NONE will never be returned.

GTK+ sets the default text direction according to the locale during gtk_init(), and you should normally use gtk_widget_get_direction() or gtk_widget_get_default_direction() 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 Language Example):

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

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 GTK_MAJOR_VERSION macro, which represents the major version of the GTK+ headers you have included when compiling your code.

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 GTK_MICRO_VERSION macro, which represents the micro version of the GTK+ headers you have included when compiling your code.

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 GTK_MINOR_VERSION macro, which represents the minor version of the GTK+ headers you have included when compiling your code.

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

You should add this group to your GOptionContext with g_option_context_add_group(), if you are using g_option_context_parse() to parse your commandline arguments.

Queries the current grab of the default window group.

Looks up the icon size associated with name.

icon_size_from_name is deprecated: Use #GtkIconTheme instead.

Gets the canonical name of the given icon size. The returned string is statically allocated and should not be freed.

icon_size_get_name is deprecated: Use #GtkIconTheme instead.

Obtains the pixel size of a semantic icon size size: GTK_ICON_SIZE_MENU, GTK_ICON_SIZE_BUTTON, etc. This function isn’t normally needed, gtk_icon_theme_load_icon() is the usual way to get an icon for rendering, then just look at the size of the rendered pixbuf. The rendered pixbuf may not even correspond to the width/height returned by gtk_icon_size_lookup(), because themes are free to render the pixbuf however they like, including changing the usual size.

Obtains the pixel size of a semantic icon size, possibly modified by user preferences for a particular GtkSettings. Normally size would be GTK_ICON_SIZE_MENU, GTK_ICON_SIZE_BUTTON, etc. This function isn’t normally needed, gtk_widget_render_icon_pixbuf() is the usual way to get an icon for rendering, then just look at the size of the rendered pixbuf. The rendered pixbuf may not even correspond to the width/height returned by gtk_icon_size_lookup(), because themes are free to render the pixbuf however they like, including changing the usual size.

icon_size_lookup_for_settings is deprecated: Use gtk_icon_size_lookup() instead.

Registers a new icon size, along the same lines as GTK_ICON_SIZE_MENU, etc. Returns the integer value for the size.

icon_size_register is deprecated: Use #GtkIconTheme instead.

Registers alias as another name for target. So calling gtk_icon_size_from_name() with alias as argument will return target.

icon_size_register_alias is deprecated: Use #GtkIconTheme instead.

Undocumented

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 nil 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 gtk_parse_args(), gtk_init_check(), gtk_init_with_args() or g_option_context_parse() with the option group returned by gtk_get_option_group(), you don’t have to call gtk_init().

And if you are using GtkApplication, you don’t have to call any of the initialization functions either; the GtkApplication::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 gtk_init_check() 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 gtk_init(), but notice that other libraries (e.g. libdbus or gvfs) might do similar things.

This function does the same work as gtk_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.

This function does the same work as gtk_init_check(). 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.

Installs a key snooper function, which will get called on all key events before delivering them normally.

key_snooper_install is deprecated: Key snooping should not be done. Events should be handled by widgets.

Removes the key snooper function with the given id.

key_snooper_remove is deprecated: Key snooping should not be done. Events should be handled by widgets.

Runs the main loop until gtk_main_quit() is called.

You can nest calls to gtk_main(). In that case gtk_main_quit() will make the innermost invocation of the main loop return.

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

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.

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 gtk_main_iteration_do() or check if any events are pending with gtk_events_pending() first.

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

Asks for the current nesting level of the main loop.

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

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

paint_arrow is deprecated: Use gtk_render_arrow() instead

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

paint_arrow is deprecated: Use gtk_render_arrow() instead

Draws a box on cr with the given parameters.

paint_box is deprecated: Use gtk_render_frame() and gtk_render_background() instead

Draws a box on cr with the given parameters.

paint_box is deprecated: Use gtk_render_frame() and gtk_render_background() instead

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

paint_box_gap is deprecated: Use gtk_render_frame_gap() instead

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

paint_box_gap is deprecated: Use gtk_render_frame_gap() instead

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

paint_check is deprecated: Use gtk_render_check() instead

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

paint_check is deprecated: Use gtk_render_check() instead

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

paint_diamond is deprecated: Use cairo instead

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

paint_diamond is deprecated: Use cairo instead

Draws an expander as used in GtkTreeView. 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.

paint_expander is deprecated: Use gtk_render_expander() instead

Draws an expander as used in GtkTreeView. 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.

paint_expander is deprecated: Use gtk_render_expander() instead

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

paint_extension is deprecated: Use gtk_render_extension() instead

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

paint_extension is deprecated: Use gtk_render_extension() instead

Draws a flat box on cr with the given parameters.

paint_flat_box is deprecated: Use gtk_render_frame() and gtk_render_background() instead

Draws a flat box on cr with the given parameters.

paint_flat_box is deprecated: Use gtk_render_frame() and gtk_render_background() instead

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

paint_focus is deprecated: Use gtk_render_focus() instead

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

paint_focus is deprecated: Use gtk_render_focus() instead

Draws a handle as used in GtkHandleBox and GtkPaned.

paint_handle is deprecated: Use gtk_render_handle() instead

Draws a handle as used in GtkHandleBox and GtkPaned.

paint_handle is deprecated: Use gtk_render_handle() instead

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

paint_hline is deprecated: Use gtk_render_line() instead

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

paint_hline is deprecated: Use gtk_render_line() instead

Draws a layout on cr using the given parameters.

paint_layout is deprecated: Use gtk_render_layout() instead

Draws a layout on cr using the given parameters.

paint_layout is deprecated: Use gtk_render_layout() instead

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

paint_option is deprecated: Use gtk_render_option() instead

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

paint_option is deprecated: Use gtk_render_option() instead

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

paint_resize_grip is deprecated: Use gtk_render_handle() instead

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

paint_resize_grip is deprecated: Use gtk_render_handle() instead

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

paint_shadow is deprecated: Use gtk_render_frame() instead

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

paint_shadow is deprecated: Use gtk_render_frame() 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.

paint_shadow_gap is deprecated: Use gtk_render_frame_gap() 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.

paint_shadow_gap is deprecated: Use gtk_render_frame_gap() instead

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

paint_slider is deprecated: Use gtk_render_slider() instead

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

paint_slider is deprecated: Use gtk_render_slider() instead

Draws a spinner on window using the given parameters.

paint_spinner is deprecated: Use gtk_render_icon() and the #GtkStyleContext you are drawing instead

Draws a spinner on window using the given parameters.

paint_spinner is deprecated: Use gtk_render_icon() and the #GtkStyleContext you are drawing instead

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

paint_tab is deprecated: 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.

paint_tab is deprecated: Use cairo instead