[gtk/ebassi/gidocgen: 220/501] window: Convert docs
- From: Emmanuele Bassi <ebassi src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gtk/ebassi/gidocgen: 220/501] window: Convert docs
- Date: Fri, 5 Mar 2021 15:53:33 +0000 (UTC)
commit d8e53bdc35b0dd0361d75330e1eae285d1946ac0
Author: Matthias Clasen <mclasen redhat com>
Date: Thu Feb 25 23:24:31 2021 -0500
window: Convert docs
Convert link format, add an example image, add
property annotations. General cleanup.
gtk/gtkwindow.c | 875 +++++++++++++++++++++++++++++++-------------------------
1 file changed, 486 insertions(+), 389 deletions(-)
---
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index b4de2cc97c..791cab15b8 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -96,18 +96,19 @@
#endif
/**
- * SECTION:gtkwindow
- * @title: GtkWindow
- * @short_description: Toplevel which can contain other widgets
+ * GtkWindow:
+ *
+ * A `GtkWindow` is a toplevel window which can contain other widgets.
+ *
+ * 
*
- * A GtkWindow is a toplevel window which can contain other widgets.
* Windows normally have decorations that are under the control
* of the windowing system and allow the user to manipulate the window
* (resize it, move it, close it,...).
*
* # GtkWindow as GtkBuildable
*
- * The GtkWindow implementation of the #GtkBuildable interface supports
+ * The `GtkWindow` implementation of the [iface@Gtk.Buildable] interface supports
* setting a child as the titlebar by specifying “titlebar” as the “type”
* attribute of a <child> element.
*
@@ -119,7 +120,7 @@
* ╰── <titlebar child>.titlebar [.default-decoration]
* ]|
*
- * GtkWindow has a main CSS node with name window and style class .background.
+ * `GtkWindow` has a main CSS node with name window and style class .background.
*
* Style classes that are typically used with the main CSS node are .csd (when
* client-side decorations are in use), .solid-csd (for client-side decorations
@@ -128,7 +129,7 @@
* style classes on the main node: .maximized, .fullscreen, .tiled (when supported,
* also .tiled-top, .tiled-left, .tiled-right, .tiled-bottom).
*
- * GtkWindow subclasses often add their own discriminating style classes,
+ * `GtkWindow` subclasses often add their own discriminating style classes,
* such as .dialog, .popup or .tooltip.
*
* Generally, some CSS properties don't make sense on the toplevel window node,
@@ -138,12 +139,12 @@
* resize drags. In the .csd case, the shadow area outside of the window
* can be used to resize it.
*
- * GtkWindow adds the .titlebar and .default-decoration style classes to the
+ * `GtkWindow` adds the .titlebar and .default-decoration style classes to the
* widget that is added as a titlebar child.
*
* # Accessibility
*
- * GtkWindow uses the %GTK_ACCESSIBLE_ROLE_WINDOW role.
+ * `GtkWindow` uses the %GTK_ACCESSIBLE_ROLE_WINDOW role.
*/
#define MENU_BAR_ACCEL GDK_KEY_F10
@@ -707,6 +708,11 @@ gtk_window_class_init (GtkWindowClass *klass)
klass->enable_debugging = gtk_window_enable_debugging;
klass->close_request = gtk_window_close_request;
+ /**
+ * GtkWindow:title: (attributes org.gtk.Property.get=gtk_window_get_title
org.gtk.Property.set=gtk_window_set_title)
+ *
+ * The title of the window.
+ */
window_props[PROP_TITLE] =
g_param_spec_string ("title",
P_("Window Title"),
@@ -715,11 +721,9 @@ gtk_window_class_init (GtkWindowClass *klass)
GTK_PARAM_READWRITE);
/**
- * GtkWindow:startup-id:
+ * GtkWindow:startup-id: (attributes org.gtk.Property.set=gtk_window_set_startup_id)
*
- * The :startup-id is a write-only property for setting window's
- * startup notification identifier. See gtk_window_set_startup_id()
- * for more details.
+ * A write-only property for setting window's startup notification identifier.
*/
window_props[PROP_STARTUP_ID] =
g_param_spec_string ("startup-id",
@@ -728,6 +732,11 @@ gtk_window_class_init (GtkWindowClass *klass)
NULL,
GTK_PARAM_WRITABLE);
+ /**
+ * GtkWindow:resizable: (attributes org.gtk.Property.get=gtk_window_get_resizable
org.gtk.Property.set=gtk_window_set_resizable)
+ *
+ * If %TRUE, users can resize the window.
+ */
window_props[PROP_RESIZABLE] =
g_param_spec_boolean ("resizable",
P_("Resizable"),
@@ -735,6 +744,11 @@ gtk_window_class_init (GtkWindowClass *klass)
TRUE,
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * GtkWindow:modal: (attributes org.gtk.Property.get=gtk_window_get_modal
org.gtk.Property.set=gtk_window_set_modal)
+ *
+ * If %TRUE, the window is modal.
+ */
window_props[PROP_MODAL] =
g_param_spec_boolean ("modal",
P_("Modal"),
@@ -742,6 +756,11 @@ gtk_window_class_init (GtkWindowClass *klass)
FALSE,
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * GtkWindow:default-width:
+ *
+ * The default width of the window.
+ */
window_props[PROP_DEFAULT_WIDTH] =
g_param_spec_int ("default-width",
P_("Default Width"),
@@ -750,6 +769,11 @@ gtk_window_class_init (GtkWindowClass *klass)
0,
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * GtkWindow:default-height:
+ *
+ * The default height of the window.
+ */
window_props[PROP_DEFAULT_HEIGHT] =
g_param_spec_int ("default-height",
P_("Default Height"),
@@ -758,6 +782,11 @@ gtk_window_class_init (GtkWindowClass *klass)
0,
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * GtkWindow:destroy-with-parent: (attributes org.gtk.Property.get=gtk_window_get_destroy_with_parent
org.gtk.Property.set=gtk_window_set_destroy_with_parent)
+ *
+ * If this window should be destroyed when the parent is destroyed.
+ */
window_props[PROP_DESTROY_WITH_PARENT] =
g_param_spec_boolean ("destroy-with-parent",
P_("Destroy with Parent"),
@@ -765,14 +794,20 @@ gtk_window_class_init (GtkWindowClass *klass)
FALSE,
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * GtkWindow:hide-on-close: (attributes org.gtk.Property.get=gtk_window_get_hide_on_close
org.gtk.Property.set=gtk_window_set_hide_on_close)
+ *
+ * If this window should be hidden when the users clicks the close button.
+ */
window_props[PROP_HIDE_ON_CLOSE] =
g_param_spec_boolean ("hide-on-close",
P_("Hide on close"),
P_("If this window should be hidden when the user clicks the close button"),
FALSE,
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
+
/**
- * GtkWindow:mnemonics-visible:
+ * GtkWindow:mnemonics-visible: (attributes org.gtk.Property.get=gtk_window_get_mnemonics_visible
org.gtk.Property.set=gtk_window_set_mnemonics_visible)
*
* Whether mnemonics are currently visible in this window.
*
@@ -787,7 +822,7 @@ gtk_window_class_init (GtkWindowClass *klass)
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
/**
- * GtkWindow:focus-visible:
+ * GtkWindow:focus-visible: (attributes org.gtk.Property.get=gtk_window_get_focus_visible
org.gtk.Property.set=gtk_window_set_focus_visible)
*
* Whether 'focus rectangles' are currently visible in this window.
*
@@ -802,10 +837,11 @@ gtk_window_class_init (GtkWindowClass *klass)
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
/**
- * GtkWindow:icon-name:
+ * GtkWindow:icon-name: (attributes org.gtk.Property.get=gtk_window_get_icon_name
org.gtk.Property.set=gtk_window_set_icon_name)
+ *
+ * Specifies the name of the themed icon to use as the window icon.
*
- * The :icon-name property specifies the name of the themed icon to
- * use as the window icon. See #GtkIconTheme for more details.
+ * See [class@Gtk.IconTheme] for more details.
*/
window_props[PROP_ICON_NAME] =
g_param_spec_string ("icon-name",
@@ -814,6 +850,11 @@ gtk_window_class_init (GtkWindowClass *klass)
NULL,
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * GtkWindow:display: (attributes org.gtk.Property.set=gtk_window_set_display)
+ *
+ * The display that will display this window.
+ */
window_props[PROP_DISPLAY] =
g_param_spec_object ("display",
P_("Display"),
@@ -821,6 +862,11 @@ gtk_window_class_init (GtkWindowClass *klass)
GDK_TYPE_DISPLAY,
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * GtkWindow:is-active: (attributes org.gtk.Property.get=gtk_window_is_active)
+ *
+ * Whether the toplevel is the currently active window.
+ */
window_props[PROP_IS_ACTIVE] =
g_param_spec_boolean ("is-active",
P_("Is Active"),
@@ -829,9 +875,9 @@ gtk_window_class_init (GtkWindowClass *klass)
GTK_PARAM_READABLE);
/**
- * GtkWindow:decorated:
+ * GtkWindow:decorated: (attributes org.gtk.Property.get=gtk_window_get_decorated
org.gtk.Property.set=gtk_window_set_decorated)
*
- * Whether the window should be decorated by the window manager.
+ * Whether the window should have a frame (also known as *decorations*).
*/
window_props[PROP_DECORATED] =
g_param_spec_boolean ("decorated",
@@ -841,7 +887,7 @@ gtk_window_class_init (GtkWindowClass *klass)
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
/**
- * GtkWindow:deletable:
+ * GtkWindow:deletable: (attributes org.gtk.Property.get=gtk_window_get_deletable
org.gtk.Property.set=gtk_window_set_deletable)
*
* Whether the window frame should have a close button.
*/
@@ -853,10 +899,9 @@ gtk_window_class_init (GtkWindowClass *klass)
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
/**
- * GtkWindow:transient-for:
+ * GtkWindow:transient-for: (attributes org.gtk.Property.get=gtk_window_get_transient_for
org.gtk.Property.set=gtk_window_set_transient_for)
*
- * The transient parent of the window. See gtk_window_set_transient_for() for
- * more details about transient windows.
+ * The transient parent of the window.
*/
window_props[PROP_TRANSIENT_FOR] =
g_param_spec_object ("transient-for",
@@ -866,14 +911,15 @@ gtk_window_class_init (GtkWindowClass *klass)
GTK_PARAM_READWRITE|G_PARAM_CONSTRUCT|G_PARAM_EXPLICIT_NOTIFY);
/**
- * GtkWindow:maximized:
+ * GtkWindow:maximized: (attributes org.gtk.Property.get=gtk_window_is_maximized)
*
* Whether the window is maximized.
*
- * Setting this property is the equivalent of calling gtk_window_maximize()
- * and gtk_window_unmaximize(); either operation is asynchronous, which
- * means you will need to connect to the #GObject::notify signal in order to
- * know whether the operation was successful.
+ * Setting this property is the equivalent of calling
+ * [method@Gtk.Window.maximize] or [method@Gtk.Window.unmaximize];
+ * either operation is asynchronous, which means you will need to
+ * connect to the ::notify signal in order to know whether the
+ * operation was successful.
*/
window_props[PROP_MAXIMIZED] =
g_param_spec_boolean ("maximized",
@@ -883,14 +929,15 @@ gtk_window_class_init (GtkWindowClass *klass)
GTK_PARAM_READWRITE|G_PARAM_CONSTRUCT|G_PARAM_EXPLICIT_NOTIFY);
/**
- * GtkWindow:fullscreened:
+ * GtkWindow:fullscreened: (attributes org.gtk.Property.get=gtk_window_is_fullscreen)
*
* Whether the window is fullscreen.
*
- * Setting this property is the equivalent of calling gtk_window_fullscreen()
- * and gtk_window_unfullscreen(); either operation is asynchronous, which
- * means you will need to connect to the #GObject::notify signal in order to
- * know whether the operation was successful.
+ * Setting this property is the equivalent of calling
+ * [method@Gtk.Window.fullscreen] or [method@Gtk.Window.unfullscreen];
+ * either operation is asynchronous, which means you will need to
+ * connect to the ::notify signal in order to know whether the
+ * operation was successful.
*/
window_props[PROP_FULLSCREENED] =
g_param_spec_boolean ("fullscreened",
@@ -900,9 +947,9 @@ gtk_window_class_init (GtkWindowClass *klass)
GTK_PARAM_READWRITE|G_PARAM_CONSTRUCT|G_PARAM_EXPLICIT_NOTIFY);
/**
- * GtkWindow:application:
+ * GtkWindow:application: (attributes org.gtk.Property.get=gtk_window_get_application
org.gtk.Property.set=gtk_window_set_application)
*
- * The #GtkApplication associated with the window.
+ * The `GtkApplication` associated with the window.
*
* The application will be kept alive for at least as long as it
* has any windows associated with it (see g_application_hold()
@@ -919,6 +966,11 @@ gtk_window_class_init (GtkWindowClass *klass)
GTK_TYPE_APPLICATION,
GTK_PARAM_READWRITE|G_PARAM_STATIC_STRINGS|G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * GtkWindow:default-widget: (attributes org.gtk.Property.get=gtk_window_get_default_widget
org.gtk.Property.set=gtk_window_set_default_widget)
+ *
+ * The default widget.
+ */
window_props[PROP_DEFAULT_WIDGET] =
g_param_spec_object ("default-widget",
P_("Default widget"),
@@ -926,6 +978,11 @@ gtk_window_class_init (GtkWindowClass *klass)
GTK_TYPE_WIDGET,
GTK_PARAM_READWRITE|G_PARAM_STATIC_STRINGS|G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * GtkWindow:focus-widget: (attributes org.gtk.Property.get=gtk_window_get_focus
org.gtk.Property.set=gtk_window_set_focus)
+ *
+ * The focus widget.
+ */
window_props[PROP_FOCUS_WIDGET] =
g_param_spec_object ("focus-widget",
P_("Focus widget"),
@@ -933,6 +990,11 @@ gtk_window_class_init (GtkWindowClass *klass)
GTK_TYPE_WIDGET,
GTK_PARAM_READWRITE|G_PARAM_STATIC_STRINGS|G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * GtkWindow:child: (attributes org.gtk.Property.get=gtk_window_get_child
org.gtk.Property.set=gtk_window_set_child)
+ *
+ * The child widget.
+ */
window_props[PROP_CHILD] =
g_param_spec_object ("child",
P_("Child"),
@@ -947,10 +1009,10 @@ gtk_window_class_init (GtkWindowClass *klass)
* GtkWindow::activate-focus:
* @window: the window which received the signal
*
- * The ::activate-focus signal is a
- * [keybinding signal][GtkSignalAction]
- * which gets emitted when the user activates the currently
- * focused widget of @window.
+ * Emitted when the user activates the currently focused
+ * widget of @window.
+ *
+ * This is a [keybinding signal](class.SignalAction.html).
*/
window_signals[ACTIVATE_FOCUS] =
g_signal_new (I_("activate-focus"),
@@ -966,10 +1028,10 @@ gtk_window_class_init (GtkWindowClass *klass)
* GtkWindow::activate-default:
* @window: the window which received the signal
*
- * The ::activate-default signal is a
- * [keybinding signal][GtkSignalAction]
- * which gets emitted when the user activates the default widget
+ * Emitted when the user activates the default widget
* of @window.
+ *
+ * This is a [keybinding signal](class.SignalAction.html).
*/
window_signals[ACTIVATE_DEFAULT] =
g_signal_new (I_("activate-default"),
@@ -985,8 +1047,8 @@ gtk_window_class_init (GtkWindowClass *klass)
* GtkWindow::keys-changed:
* @window: the window which received the signal
*
- * The ::keys-changed signal gets emitted when the set of accelerators
- * or mnemonics that are associated with @window changes.
+ * emitted when the set of accelerators or mnemonics that
+ * are associated with @window changes.
*/
window_signals[KEYS_CHANGED] =
g_signal_new (I_("keys-changed"),
@@ -1003,11 +1065,13 @@ gtk_window_class_init (GtkWindowClass *klass)
* @window: the window on which the signal is emitted
* @toggle: toggle the debugger
*
- * The ::enable-debugging signal is a [keybinding signal][GtkSignalAction]
- * which gets emitted when the user enables or disables interactive
- * debugging. When @toggle is %TRUE, interactive debugging is toggled
- * on or off, when it is %FALSE, the debugger will be pointed at the
- * widget under the pointer.
+ * Emitted when the user enables or disables interactive debugging.
+ *
+ * When @toggle is %TRUE, interactive debugging is toggled on or off,
+ * when it is %FALSE, the debugger will be pointed at the widget
+ * under the pointer.
+ *
+ * This is a [keybinding signal](class.SignalAction.html).
*
* The default bindings for this signal are Ctrl-Shift-I
* and Ctrl-Shift-D.
@@ -1028,8 +1092,7 @@ gtk_window_class_init (GtkWindowClass *klass)
* GtkWindow::close-request:
* @window: the window on which the signal is emitted
*
- * The ::close-request signal is emitted when the user clicks on the close
- * button of the window.
+ * Emitted when the user clicks on the close button of the window.
*
* Return: %TRUE to stop other handlers from being invoked for the signal
*/
@@ -1112,8 +1175,8 @@ gtk_window_class_init (GtkWindowClass *klass)
}
/**
- * gtk_window_is_maximized:
- * @window: a #GtkWindow
+ * gtk_window_is_maximized: (attributes org.gtk.Method.get_property=maximized)
+ * @window: a `GtkWindow`
*
* Retrieves the current maximized state of @window.
*
@@ -1121,7 +1184,7 @@ gtk_window_class_init (GtkWindowClass *klass)
* manager and happens asynchronously to an application request, you
* shouldn’t assume the return value of this function changing
* immediately (or at all), as an effect of calling
- * gtk_window_maximize() or gtk_window_unmaximize().
+ * [method@Gtk.Window.maximize] or [method@Gtk.Window.unmaximize].
*
* If the window isn't yet mapped, the value returned will whether the
* initial requested state is maximized.
@@ -1139,8 +1202,8 @@ gtk_window_is_maximized (GtkWindow *window)
}
/**
- * gtk_window_is_fullscreen:
- * @window: a #GtkWindow
+ * gtk_window_is_fullscreen: (attributes org.gtk.Property.get=fullscreened)
+ * @window: a `GtkWindow`
*
* Retrieves the current fullscreen state of @window.
*
@@ -1148,7 +1211,7 @@ gtk_window_is_maximized (GtkWindow *window)
* manager and happens asynchronously to an application request, you
* shouldn’t assume the return value of this function changing
* immediately (or at all), as an effect of calling
- * gtk_window_fullscreen() or gtk_window_unfullscreen().
+ * [method@Gtk.Window.fullscreen] or [method@Gtk.Window.unfullscreen].
*
* If the window isn't yet mapped, the value returned will whether the
* initial requested state is fullscreen.
@@ -1178,10 +1241,12 @@ _gtk_window_toggle_maximized (GtkWindow *window)
/**
* gtk_window_close:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
+ *
+ * Requests that the window is closed.
*
- * Requests that the window is closed, similar to what happens
- * when a window manager close button is clicked.
+ * This is similar to what happens when a window manager
+ * close button is clicked.
*
* This function can be used with close buttons in custom
* titlebars.
@@ -2015,23 +2080,22 @@ gtk_window_native_interface_init (GtkNativeInterface *iface)
/**
* gtk_window_new:
- *
- * Creates a new #GtkWindow, which is a toplevel window that can
- * contain other widgets.
+ *
+ * Creates a new `GtkWindow`.
*
* To get an undecorated window (no window borders), use
- * gtk_window_set_decorated().
+ * [method@Gtk.Window.set_decorated].
*
- * All top-level windows created by gtk_window_new() are stored in
- * an internal top-level window list. This list can be obtained from
- * gtk_window_list_toplevels(). Due to Gtk+ keeping a reference to
- * the window internally, gtk_window_new() does not return a reference
- * to the caller.
+ * All top-level windows created by gtk_window_new() are stored
+ * in an internal top-level window list. This list can be obtained
+ * from [func@Gtk.Window.list_toplevels]. Due to GTK keeping a
+ * reference to the window internally, gtk_window_new() does not
+ * return a reference to the caller.
*
- * To delete a #GtkWindow, call gtk_window_destroy().
- *
- * Returns: a new #GtkWindow.
- **/
+ * To delete a `GtkWindow`, call [method@Gtk.Window.destroy].
+ *
+ * Returns: a new `GtkWindow`.
+ */
GtkWidget*
gtk_window_new (void)
{
@@ -2039,22 +2103,21 @@ gtk_window_new (void)
}
/**
- * gtk_window_set_title:
- * @window: a #GtkWindow
+ * gtk_window_set_title: (attributes org.gtk.Method.set_property=title)
+ * @window: a `GtkWindow`
* @title: (nullable): title of the window
- *
- * Sets the title of the #GtkWindow. The title of a window will be
- * displayed in its title bar; on the X Window System, the title bar
- * is rendered by the [window manager][gtk-X11-arch],
- * so exactly how the title appears to users may vary
- * according to a user’s exact configuration. The title should help a
- * user distinguish this window from other windows they may have
- * open. A good title might include the application name and current
- * document filename, for example.
- * document filename, for example.
-
+ *
+ * Sets the title of the `GtkWindow`.
+ *
+ * The title of a window will be displayed in its title bar; on the
+ * X Window System, the title bar is rendered by the window manager
+ * so exactly how the title appears to users may vary according to a
+ * user’s exact configuration. The title should help a user distinguish
+ * this window from other windows they may have open. A good title might
+ * include the application name and current document filename, for example.
+ *
* Passing %NULL does the same as setting the title to an empty string.
- **/
+ */
void
gtk_window_set_title (GtkWindow *window,
const char *title)
@@ -2079,15 +2142,15 @@ gtk_window_set_title (GtkWindow *window,
}
/**
- * gtk_window_get_title:
- * @window: a #GtkWindow
+ * gtk_window_get_title: (attributes org.gtk.Method.get_property=title)
+ * @window: a `GtkWindow`
*
- * Retrieves the title of the window. See gtk_window_set_title().
+ * Retrieves the title of the window.
*
* Returns: (nullable): the title of the window, or %NULL if none has
- * been set explicitly. The returned string is owned by the widget
- * and must not be modified or freed.
- **/
+ * been set explicitly. The returned string is owned by the widget
+ * and must not be modified or freed.
+ */
const char *
gtk_window_get_title (GtkWindow *window)
{
@@ -2099,21 +2162,25 @@ gtk_window_get_title (GtkWindow *window)
}
/**
- * gtk_window_set_startup_id:
- * @window: a #GtkWindow
+ * gtk_window_set_startup_id: (attributes org.gtk.Method.set_property=startup-id)
+ * @window: a `GtkWindow`
* @startup_id: a string with startup-notification identifier
*
- * Startup notification identifiers are used by desktop environment to
- * track application startup, to provide user feedback and other
+ * Sets the startup notification ID.
+ *
+ * Startup notification identifiers are used by desktop environment
+ * to track application startup, to provide user feedback and other
* features. This function changes the corresponding property on the
- * underlying GdkSurface. Normally, startup identifier is managed
- * automatically and you should only use this function in special cases
- * like transferring focus from other processes. You should use this
- * function before calling gtk_window_present() or any equivalent
- * function generating a window map event.
+ * underlying `GdkSurface`.
+ *
+ * Normally, startup identifier is managed automatically and you should
+ * only use this function in special cases like transferring focus from
+ * other processes. You should use this function before calling
+ * [method@Gtk.Window.present] or any equivalent function generating
+ * a window map event.
*
* This function is only useful on X11, not with other GTK targets.
- **/
+ */
void
gtk_window_set_startup_id (GtkWindow *window,
const char *startup_id)
@@ -2156,14 +2223,15 @@ gtk_window_set_startup_id (GtkWindow *window,
}
/**
- * gtk_window_set_default_widget:
- * @window: a #GtkWindow
+ * gtk_window_set_default_widget: (attributes org.gtk.Property.set=default-widget)
+ * @window: a `GtkWindow`
* @default_widget: (allow-none): widget to be the default, or %NULL
* to unset the default widget for the toplevel
*
- * The default widget is the widget that’s activated when the user
- * presses Enter in a dialog (for example). This function sets or
- * unsets the default widget for a #GtkWindow.
+ * Sets the default widget.
+ *
+ * The default widget is the widget that is activated when the user
+ * presses Enter in a dialog (for example).
*/
void
gtk_window_set_default_widget (GtkWindow *window,
@@ -2216,16 +2284,14 @@ gtk_window_set_default_widget (GtkWindow *window,
}
/**
- * gtk_window_get_default_widget:
- * @window: a #GtkWindow
+ * gtk_window_get_default_widget: (attributes org.gtk.Property.get=default-widget)
+ * @window: a `GtkWindow`
*
* Returns the default widget for @window.
*
- * See gtk_window_set_default_widget() for more details.
- *
* Returns: (nullable) (transfer none): the default widget, or %NULL
- * if there is none.
- **/
+ * if there is none.
+ */
GtkWidget *
gtk_window_get_default_widget (GtkWindow *window)
{
@@ -2266,18 +2332,19 @@ _gtk_window_notify_keys_changed (GtkWindow *window)
}
/**
- * gtk_window_get_focus:
- * @window: a #GtkWindow
- *
+ * gtk_window_get_focus: (attributes org.gtk.Property.get=focus-widget)
+ * @window: a `GtkWindow`
+ *
* Retrieves the current focused widget within the window.
+ *
* Note that this is the widget that would have the focus
* if the toplevel window focused; if the toplevel window
- * is not focused then `gtk_widget_has_focus (widget)` will
+ * is not focused then `gtk_widget_has_focus (widget)` will
* not be %TRUE for the widget.
*
* Returns: (nullable) (transfer none): the currently focused widget,
- * or %NULL if there is none.
- **/
+ * or %NULL if there is none.
+ */
GtkWidget *
gtk_window_get_focus (GtkWindow *window)
{
@@ -2301,17 +2368,18 @@ gtk_window_real_activate_default (GtkWindow *window)
}
/**
- * gtk_window_set_modal:
- * @window: a #GtkWindow
+ * gtk_window_set_modal: (attributes org.gtk.Method.set_property=modal)
+ * @window: a `GtkWindow`
* @modal: whether the window is modal
*
- * Sets a window modal or non-modal. Modal windows prevent interaction
- * with other windows in the same application. To keep modal dialogs
- * on top of main application windows, use
- * gtk_window_set_transient_for() to make the dialog transient for the
- * parent; most [window managers][gtk-X11-arch]
- * will then disallow lowering the dialog below the parent.
- **/
+ * Sets a window modal or non-modal.
+ *
+ * Modal windows prevent interaction with other windows in the same
+ * application. To keep modal dialogs on top of main application windows,
+ * use [method@Gtk.Window.set_transient_for] to make the dialog transient
+ * for the parent; most window managers will then disallow lowering the
+ * dialog below the parent.
+ */
void
gtk_window_set_modal (GtkWindow *window,
gboolean modal)
@@ -2349,14 +2417,14 @@ gtk_window_set_modal (GtkWindow *window,
}
/**
- * gtk_window_get_modal:
- * @window: a #GtkWindow
- *
- * Returns whether the window is modal. See gtk_window_set_modal().
+ * gtk_window_get_modal: (attributes org.gtk.Method.get_property=modal)
+ * @window: a `GtkWindow`
+ *
+ * Returns whether the window is modal.
*
* Returns: %TRUE if the window is set to be modal and
- * establishes a grab when shown
- **/
+ * establishes a grab when shown
+ */
gboolean
gtk_window_get_modal (GtkWindow *window)
{
@@ -2390,16 +2458,18 @@ gtk_window_get_toplevels (void)
/**
* gtk_window_list_toplevels:
- *
- * Returns a list of all existing toplevel windows. The widgets
- * in the list are not individually referenced. If you want
- * to iterate through the list and perform actions involving
- * callbacks that might destroy the widgets, you must call
- * `g_list_foreach (result, (GFunc)g_object_ref, NULL)` first, and
- * then unref all the widgets afterwards.
- *
- * Returns: (element-type GtkWidget) (transfer container): list of toplevel widgets
- **/
+ *
+ * Returns a list of all existing toplevel windows.
+ *
+ * The widgets in the list are not individually referenced.
+ * If you want to iterate through the list and perform actions
+ * involving callbacks that might destroy the widgets, you must
+ * call `g_list_foreach (result, (GFunc)g_object_ref, NULL)` first,
+ * and then unref all the widgets afterwards.
+ *
+ * Returns: (element-type GtkWidget) (transfer container): list of
+ * toplevel widgets
+ */
GList*
gtk_window_list_toplevels (void)
{
@@ -2517,16 +2587,15 @@ gtk_window_unset_transient_for (GtkWindow *window)
}
/**
- * gtk_window_set_transient_for:
- * @window: a #GtkWindow
+ * gtk_window_set_transient_for: (attributes org.gtk.Method.set_property=transient-for)
+ * @window: a `GtkWindow`
* @parent: (allow-none): parent window, or %NULL
*
* Dialog windows should be set transient for the main application
- * window they were spawned from. This allows
- * [window managers][gtk-X11-arch] to e.g. keep the
- * dialog on top of the main window, or center the dialog over the
- * main window. gtk_dialog_new_with_buttons() and other convenience
- * functions in GTK will sometimes call
+ * window they were spawned from. This allows window managers to e.g.
+ * keep the dialog on top of the main window, or center the dialog
+ * over the main window. [ctor@Gtk.Dialog.new_with_buttons] and other
+ * convenience functions in GTK will sometimes call
* gtk_window_set_transient_for() on your behalf.
*
* Passing %NULL for @parent unsets the current transient window.
@@ -2588,15 +2657,14 @@ gtk_window_set_transient_for (GtkWindow *window,
}
/**
- * gtk_window_get_transient_for:
- * @window: a #GtkWindow
+ * gtk_window_get_transient_for: (attributes org.gtk.Method.get_property=transient-for)
+ * @window: a `GtkWindow`
*
- * Fetches the transient parent for this window. See
- * gtk_window_set_transient_for().
+ * Fetches the transient parent for this window.
*
* Returns: (nullable) (transfer none): the transient parent for this
- * window, or %NULL if no transient parent has been set.
- **/
+ * window, or %NULL if no transient parent has been set.
+ */
GtkWindow *
gtk_window_get_transient_for (GtkWindow *window)
{
@@ -2608,13 +2676,13 @@ gtk_window_get_transient_for (GtkWindow *window)
}
/**
- * gtk_window_get_application:
- * @window: a #GtkWindow
+ * gtk_window_get_application: (attributes org.gtk.Method.get_property=application)
+ * @window: a `GtkWindow`
*
- * Gets the #GtkApplication associated with the window (if any).
+ * Gets the `GtkApplication` associated with the window.
*
- * Returns: (nullable) (transfer none): a #GtkApplication, or %NULL
- **/
+ * Returns: (nullable) (transfer none): a `GtkApplication`, or %NULL
+ */
GtkApplication *
gtk_window_get_application (GtkWindow *window)
{
@@ -2647,23 +2715,24 @@ gtk_window_release_application (GtkWindow *window)
}
/**
- * gtk_window_set_application:
- * @window: a #GtkWindow
- * @application: (allow-none): a #GtkApplication, or %NULL to unset
+ * gtk_window_set_application: (attributes org.gtk.Method.set_property=application)
+ * @window: a `GtkWindow`
+ * @application: (allow-none): a `GtkApplication`, or %NULL to unset
*
- * Sets or unsets the #GtkApplication associated with the window.
+ * Sets or unsets the `GtkApplication` associated with the window.
*
- * The application will be kept alive for at least as long as it has any windows
- * associated with it (see g_application_hold() for a way to keep it alive
- * without windows).
+ * The application will be kept alive for at least as long as it has
+ * any windows associated with it (see g_application_hold() for a way
+ * to keep it alive without windows).
*
- * Normally, the connection between the application and the window will remain
- * until the window is destroyed, but you can explicitly remove it by setting
- * the @application to %NULL.
+ * Normally, the connection between the application and the window will
+ * remain until the window is destroyed, but you can explicitly remove
+ * it by setting the @application to %NULL.
*
- * This is equivalent to calling gtk_application_remove_window() and/or
- * gtk_application_add_window() on the old/new applications as relevant.
- **/
+ * This is equivalent to calling [method@Gtk.Application.remove_window]
+ * and/or [method@Gtk.Application.add_window] on the old/new applications
+ * as relevant.
+ */
void
gtk_window_set_application (GtkWindow *window,
GtkApplication *application)
@@ -2703,15 +2772,16 @@ gtk_window_set_application (GtkWindow *window,
}
/**
- * gtk_window_set_destroy_with_parent:
- * @window: a #GtkWindow
+ * gtk_window_set_destroy_with_parent: (attributes org.gtk.Method.set_property=destroy-with-parent)
+ * @window: a `GtkWindow`
* @setting: whether to destroy @window with its transient parent
- *
+ *
* If @setting is %TRUE, then destroying the transient parent of @window
- * will also destroy @window itself. This is useful for dialogs that
- * shouldn’t persist beyond the lifetime of the main window they're
- * associated with, for example.
- **/
+ * will also destroy @window itself.
+ *
+ * This is useful for dialogs that shouldn’t persist beyond the lifetime
+ * of the main window they are associated with, for example.
+ */
void
gtk_window_set_destroy_with_parent (GtkWindow *window,
gboolean setting)
@@ -2729,14 +2799,13 @@ gtk_window_set_destroy_with_parent (GtkWindow *window,
}
/**
- * gtk_window_get_destroy_with_parent:
- * @window: a #GtkWindow
- *
- * Returns whether the window will be destroyed with its transient parent. See
- * gtk_window_set_destroy_with_parent ().
+ * gtk_window_get_destroy_with_parent: (attributes org.gtk.Method.get_property=destroy-with-parent)
+ * @window: a `GtkWindow`
+ *
+ * Returns whether the window will be destroyed with its transient parent.
*
* Returns: %TRUE if the window will be destroyed with its transient parent.
- **/
+ */
gboolean
gtk_window_get_destroy_with_parent (GtkWindow *window)
{
@@ -2748,8 +2817,8 @@ gtk_window_get_destroy_with_parent (GtkWindow *window)
}
/**
- * gtk_window_set_hide_on_close:
- * @window: a #GtkWindow
+ * gtk_window_set_hide_on_close: (attributes org.gtk.Method.set_property=hide-on-close)
+ * @window: a `GtkWindow`
* @setting: whether to hide the window when it is closed
*
* If @setting is %TRUE, then clicking the close button on the window
@@ -2772,8 +2841,8 @@ gtk_window_set_hide_on_close (GtkWindow *window,
}
/**
- * gtk_window_get_hide_on_close:
- * @window: a #GtkWindow
+ * gtk_window_get_hide_on_close: (attributes org.gtk.Method.get_property=hide-on-close)
+ * @window: a `GtkWindow`
*
* Returns whether the window will be hidden when the close button is clicked.
*
@@ -2867,19 +2936,20 @@ gtk_window_enable_csd (GtkWindow *window)
/**
* gtk_window_set_titlebar:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
* @titlebar: (allow-none): the widget to use as titlebar
*
* Sets a custom titlebar for @window.
*
- * A typical widget used here is #GtkHeaderBar, as it provides various features
- * expected of a titlebar while allowing the addition of child widgets to it.
+ * A typical widget used here is [class@Gtk.HeaderBar], as it
+ * provides various features expected of a titlebar while allowing
+ * the addition of child widgets to it.
*
* If you set a custom titlebar, GTK will do its best to convince
* the window manager not to put its own titlebar on the window.
* Depending on the system, this function may not work for a window
* that is already visible, so you set the titlebar before calling
- * gtk_widget_show().
+ * [method Gtk Widget show].
*/
void
gtk_window_set_titlebar (GtkWindow *window,
@@ -2928,7 +2998,7 @@ out:
/**
* gtk_window_get_titlebar:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
*
* Returns the custom titlebar that has been set with
* gtk_window_set_titlebar().
@@ -2950,23 +3020,24 @@ gtk_window_get_titlebar (GtkWindow *window)
}
/**
- * gtk_window_set_decorated:
- * @window: a #GtkWindow
+ * gtk_window_set_decorated: (attributes org.gtk.Method.set_property=decorated)
+ * @window: a `GtkWindow`
* @setting: %TRUE to decorate the window
*
+ * Sets whether the window should be decorated.
+ *
* By default, windows are decorated with a title bar, resize
- * controls, etc. Some [window managers][gtk-X11-arch]
- * allow GTK to disable these decorations, creating a
- * borderless window. If you set the decorated property to %FALSE
- * using this function, GTK will do its best to convince the window
- * manager not to decorate the window. Depending on the system, this
- * function may not have any effect when called on a window that is
- * already visible, so you should call it before calling gtk_widget_show().
+ * controls, etc. Some window managers allow GTK to disable these
+ * decorations, creating a borderless window. If you set the decorated
+ * property to %FALSE using this function, GTK will do its best to
+ * convince the window manager not to decorate the window. Depending on
+ * the system, this function may not have any effect when called on a
+ * window that is already visible, so you should call it before calling
+ * [method Gtk Widget show].
*
* On Windows, this function always works, since there’s no window manager
* policy involved.
- *
- **/
+ */
void
gtk_window_set_decorated (GtkWindow *window,
gboolean setting)
@@ -2992,14 +3063,13 @@ gtk_window_set_decorated (GtkWindow *window,
}
/**
- * gtk_window_get_decorated:
- * @window: a #GtkWindow
+ * gtk_window_get_decorated: (attributes org.gtk.Method.get_property=decorated)
+ * @window: a `GtkWindow`
*
- * Returns whether the window has been set to have decorations
- * such as a title bar via gtk_window_set_decorated().
+ * Returns whether the window has been set to have decorations.
*
* Returns: %TRUE if the window has been set to have decorations
- **/
+ */
gboolean
gtk_window_get_decorated (GtkWindow *window)
{
@@ -3011,20 +3081,22 @@ gtk_window_get_decorated (GtkWindow *window)
}
/**
- * gtk_window_set_deletable:
- * @window: a #GtkWindow
+ * gtk_window_set_deletable: (attributes org.gtk.Method.set_property=deletable)
+ * @window: a `GtkWindow`
* @setting: %TRUE to decorate the window as deletable
*
- * By default, windows have a close button in the window frame. Some
- * [window managers][gtk-X11-arch] allow GTK to
- * disable this button. If you set the deletable property to %FALSE
- * using this function, GTK will do its best to convince the window
- * manager not to show a close button. Depending on the system, this
- * function may not have any effect when called on a window that is
- * already visible, so you should call it before calling gtk_widget_show().
+ * Sets whether the window should be deletable.
*
- * On Windows, this function always works, since there’s no window manager
- * policy involved.
+ * By default, windows have a close button in the window frame.
+ * Some window managers allow GTK to disable this button. If you
+ * set the deletable property to %FALSE using this function, GTK
+ * will do its best to convince the window manager not to show a
+ * close button. Depending on the system, this function may not
+ * have any effect when called on a window that is already visible,
+ * so you should call it before calling [method Gtk Widget show].
+ *
+ * On Windows, this function always works, since there’s no window
+ * manager policy involved.
*/
void
gtk_window_set_deletable (GtkWindow *window,
@@ -3050,14 +3122,13 @@ gtk_window_set_deletable (GtkWindow *window,
}
/**
- * gtk_window_get_deletable:
- * @window: a #GtkWindow
+ * gtk_window_get_deletable: (attributes org.gtk.Method.get_property=deletable)
+ * @window: a `GtkWindow`
*
- * Returns whether the window has been set to have a close button
- * via gtk_window_set_deletable().
+ * Returns whether the window has been set to have a close button.
*
* Returns: %TRUE if the window has been set to have a close button
- **/
+ */
gboolean
gtk_window_get_deletable (GtkWindow *window)
{
@@ -3285,19 +3356,20 @@ update_themed_icon (GtkWindow *window)
}
/**
- * gtk_window_set_icon_name:
- * @window: a #GtkWindow
+ * gtk_window_set_icon_name: (attributes org.gtk.Method.set_property=icon-name)
+ * @window: a `GtkWindow`
* @name: (allow-none): the name of the themed icon
*
* Sets the icon for the window from a named themed icon.
- * See the docs for #GtkIconTheme for more details.
+ *
+ * See the docs for [class@Gtk.IconTheme] for more details.
* On some platforms, the window icon is not used at all.
*
- * Note that this has nothing to do with the WM_ICON_NAME
+ * Note that this has nothing to do with the WM_ICON_NAME
* property which is mentioned in the ICCCM.
*/
-void
-gtk_window_set_icon_name (GtkWindow *window,
+void
+gtk_window_set_icon_name (GtkWindow *window,
const char *name)
{
GtkWindowIconInfo *info;
@@ -3320,11 +3392,10 @@ gtk_window_set_icon_name (GtkWindow *window,
}
/**
- * gtk_window_get_icon_name:
- * @window: a #GtkWindow
+ * gtk_window_get_icon_name: (attributes org.gtk.Method.get_property=icon-name)
+ * @window: a `GtkWindow`
*
- * Returns the name of the themed icon for the window,
- * see gtk_window_set_icon_name().
+ * Returns the name of the themed icon for the window.
*
* Returns: (nullable): the icon name or %NULL if the window has
* no themed icon
@@ -3345,9 +3416,12 @@ gtk_window_get_icon_name (GtkWindow *window)
* gtk_window_set_default_icon_name:
* @name: the name of the themed icon
*
- * Sets an icon to be used as fallback for windows that
- * haven't had gtk_window_set_icon_name() called on them.
- **/
+ * Sets an icon to be used as fallback.
+ *
+ * The fallback icon is used for windows that
+ * haven't had [method@Gtk.Window.set_icon_name]
+ * called on them.
+ */
void
gtk_window_set_default_icon_name (const char *name)
{
@@ -3381,12 +3455,11 @@ gtk_window_set_default_icon_name (const char *name)
/**
* gtk_window_get_default_icon_name:
*
- * Returns the fallback icon name for windows that has been set
- * with gtk_window_set_default_icon_name(), or %NULL if that function
- * has not been called.
+ * Returns the fallback icon name for windows.
*
- * The returned string is owned by GTK and should not be modified.
- * It is only valid until the next call to gtk_window_set_default_icon_name().
+ * The returned string is owned by GTK and should not
+ * be modified. It is only valid until the next call to
+ * [func@Gtk.Window.set_default_icon_name].
*
* Returns: (nullable): the fallback icon name for windows
*/
@@ -3464,20 +3537,22 @@ gtk_window_set_default_size_internal (GtkWindow *window,
/**
* gtk_window_set_default_size:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
* @width: width in pixels, or -1 to unset the default width
* @height: height in pixels, or -1 to unset the default height
*
- * Sets the default size of a window. If the window’s “natural” size
- * (its size request) is larger than the default, the default will be
- * ignored.
+ * Sets the default size of a window.
+ *
+ * If the window’s “natural” size (its size request) is larger than
+ * the default, the default will be ignored.
*
- * Unlike gtk_widget_set_size_request(), which sets a size request for
- * a widget and thus would keep users from shrinking the window, this
- * function only sets the initial size, just as if the user had
- * resized the window themselves. Users can still shrink the window
- * again as they normally would. Setting a default size of -1 means to
- * use the “natural” default size (the size request of the window).
+ * Unlike [method@Gtk.Widget.set_size_request], which sets a size
+ * request for a widget and thus would keep users from shrinking
+ * the window, this function only sets the initial size, just as
+ * if the user had resized the window themselves. Users can still
+ * shrink the window again as they normally would. Setting a default
+ * size of -1 means to use the “natural” default size (the size request
+ * of the window).
*
* The default size of a window only affects the first time a window is
* shown; if a window is hidden and re-shown, it will remember the size
@@ -3488,8 +3563,9 @@ gtk_window_set_default_size_internal (GtkWindow *window,
*
* If you use this function to reestablish a previously saved window size,
* note that the appropriate size to save is the one returned by
- * gtk_window_get_default_size(). Using the window allocation directly will not
- * work in all circumstances and can lead to growing or shrinking windows.
+ * [method@Gtk.Window.get_default_size]. Using the window allocation
+ * directly will not work in all circumstances and can lead to growing
+ * or shrinking windows.
*/
void
gtk_window_set_default_size (GtkWindow *window,
@@ -3506,15 +3582,16 @@ gtk_window_set_default_size (GtkWindow *window,
/**
* gtk_window_get_default_size:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
* @width: (out) (allow-none): location to store the default width, or %NULL
* @height: (out) (allow-none): location to store the default height, or %NULL
*
- * Gets the default size of the window. A value of 0 for the width or
- * height indicates that a default size has not been explicitly set
- * for that dimension, so the “natural” size of the window will be
- * used.
- **/
+ * Gets the default size of the window.
+ *
+ * A value of 0 for the width or height indicates that a default
+ * size has not been explicitly set for that dimension, so the
+ * “natural” size of the window will be used.
+ */
void
gtk_window_get_default_size (GtkWindow *window,
int *width,
@@ -4960,17 +5037,19 @@ synthesize_focus_change_events (GtkWindow *window,
}
/**
- * gtk_window_set_focus:
- * @window: a #GtkWindow
+ * gtk_window_set_focus: (attributes org.gtk.Method.set_property=focus-widget)
+ * @window: a `GtkWindow`
* @focus: (allow-none): widget to be the new focus widget, or %NULL to unset
* any focus widget for the toplevel window.
*
- * If @focus is not the current focus widget, and is focusable, sets
- * it as the focus widget for the window. If @focus is %NULL, unsets
- * the focus widget for this window. To set the focus to a particular
- * widget in the toplevel, it is usually more convenient to use
- * gtk_widget_grab_focus() instead of this function.
- **/
+ * Sets the focus widget.
+ *
+ * If @focus is not the current focus widget, and is focusable,
+ * sets it as the focus widget for the window. If @focus is %NULL,
+ * unsets the focus widget for this window. To set the focus to a
+ * particular widget in the toplevel, it is usually more convenient
+ * to use [method@Gtk.Widget.grab_focus] instead of this function.
+ */
void
gtk_window_set_focus (GtkWindow *window,
GtkWidget *focus)
@@ -5032,12 +5111,14 @@ _gtk_window_unset_focus_and_default (GtkWindow *window,
/**
* gtk_window_present:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
*
- * Presents a window to the user. This function should not be used
- * as when it is called, it is too late to gather a valid timestamp
- * to allow focus stealing prevention to work correctly.
- **/
+ * Presents a window to the user.
+ *
+ * This function should not be used as when it is called,
+ * it is too late to gather a valid timestamp to allow focus
+ * stealing prevention to work correctly.
+ */
void
gtk_window_present (GtkWindow *window)
{
@@ -5046,29 +5127,31 @@ gtk_window_present (GtkWindow *window)
/**
* gtk_window_present_with_time:
- * @window: a #GtkWindow
- * @timestamp: the timestamp of the user interaction (typically a
+ * @window: a `GtkWindow`
+ * @timestamp: the timestamp of the user interaction (typically a
* button or key press event) which triggered this call
*
- * Presents a window to the user. This may mean raising the window
- * in the stacking order, unminimizing it, moving it to the current
- * desktop, and/or giving it the keyboard focus, possibly dependent
- * on the user’s platform, window manager, and preferences.
+ * Presents a window to the user.
*
- * If @window is hidden, this function calls gtk_widget_show()
+ * This may mean raising the window in the stacking order,
+ * unminimizing it, moving it to the current desktop, and/or
+ * giving it the keyboard focus, possibly dependent on the user’s
+ * platform, window manager, and preferences.
+ *
+ * If @window is hidden, this function calls [method Gtk Widget show]
* as well.
*
* This function should be used when the user tries to open a window
* that’s already open. Say for example the preferences dialog is
* currently open, and the user chooses Preferences from the menu
- * a second time; use gtk_window_present() to move the already-open dialog
- * where the user can see it.
+ * a second time; use [method@Gtk.Window.present] to move the
+ * already-open dialog where the user can see it.
*
- * Presents a window to the user in response to a user interaction. The
- * timestamp should be gathered when the window was requested to be shown
- * (when clicking a link for example), rather than once the window is
- * ready to be shown.
- **/
+ * Presents a window to the user in response to a user interaction.
+ * The timestamp should be gathered when the window was requested
+ * to be shown (when clicking a link for example), rather than once
+ * the window is ready to be shown.
+ */
void
gtk_window_present_with_time (GtkWindow *window,
guint32 timestamp)
@@ -5114,13 +5197,13 @@ gtk_window_present_with_time (GtkWindow *window,
/**
* gtk_window_minimize:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
*
* Asks to minimize the specified @window.
*
* Note that you shouldn’t assume the window is definitely minimized
* afterward, because the windowing system might not support this
- * functionality; other entities (e.g. the user or the [window manager][gtk-X11-arch])
+ * functionality; other entities (e.g. the user or the window manager
* could unminimize it again, or there may not be a window manager in
* which case minimization isn’t possible, etc.
*
@@ -5128,8 +5211,8 @@ gtk_window_present_with_time (GtkWindow *window,
* in which case the window will be minimized before it ever appears
* onscreen.
*
- * You can track result of this operation via the #GdkToplevel:state
- * property.
+ * You can track result of this operation via the
+ * [property@Gdk.Toplevel:state] property.
*/
void
gtk_window_minimize (GtkWindow *window)
@@ -5146,18 +5229,18 @@ gtk_window_minimize (GtkWindow *window)
/**
* gtk_window_unminimize:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
*
* Asks to unminimize the specified @window.
*
* Note that you shouldn’t assume the window is definitely unminimized
* afterward, because the windowing system might not support this
- * functionality; other entities (e.g. the user or the [window manager][gtk-X11-arch])
+ * functionality; other entities (e.g. the user or the window manager
* could minimize it again, or there may not be a window manager in
* which case minimization isn’t possible, etc.
*
- * You can track result of this operation via the #GdkToplevel:state
- * property.
+ * You can track result of this operation via the
+ * [property@Gdk.Toplevel:state] property.
*/
void
gtk_window_unminimize (GtkWindow *window)
@@ -5174,19 +5257,22 @@ gtk_window_unminimize (GtkWindow *window)
/**
* gtk_window_maximize:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
*
* Asks to maximize @window, so that it fills the screen.
*
- * Note that you shouldn’t assume the window is definitely maximized afterward,
- * because other entities (e.g. the user or [window manager][gtk-X11-arch])
- * could unmaximize it again, and not all window managers support maximization.
+ * Note that you shouldn’t assume the window is definitely maximized
+ * afterward, because other entities (e.g. the user or window manager
+ * could unmaximize it again, and not all window managers support
+ * maximization.
*
- * It’s permitted to call this function before showing a window, in which case
- * the window will be maximized when it appears onscreen initially.
+ * It’s permitted to call this function before showing a window,
+ * in which case the window will be maximized when it appears onscreen
+ * initially.
*
- * You can track the result of this operation via the #GdkToplevel:state
- * property, or by listening to notifications on the #GtkWindow:maximized
+ * You can track the result of this operation via the
+ * [property@Gdk.Toplevel:state] property, or by listening to
+ * notifications on the [property@Gtk.Window:maximized]
* property.
*/
void
@@ -5213,17 +5299,18 @@ gtk_window_maximize (GtkWindow *window)
/**
* gtk_window_unmaximize:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
*
* Asks to unmaximize @window.
*
- * Note that you shouldn’t assume the window is definitely unmaximized afterward,
- * because other entities (e.g. the user or [window manager][gtk-X11-arch]) could
- * maximize it again, and not all window managers honor requests to unmaximize.
+ * Note that you shouldn’t assume the window is definitely unmaximized
+ * afterward, because other entities (e.g. the user or window manager
+ * maximize it again, and not all window managers honor requests to
+ * unmaximize.
*
- * You can track the result of this operation via the #GdkToplevel:state
- * property, or by listening to notifications on the #GtkWindow:maximized
- * property.
+ * You can track the result of this operation via the
+ * [property@Gdk.Toplevel:state] property, or by listening to
+ * notifications on the [property@Gtk.Window:maximized] property.
*/
void
gtk_window_unmaximize (GtkWindow *window)
@@ -5262,17 +5349,18 @@ unset_fullscreen_monitor (GtkWindow *window)
/**
* gtk_window_fullscreen:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
*
* Asks to place @window in the fullscreen state.
*
- * Note that you shouldn’t assume the window is definitely full screen afterward,
- * because other entities (e.g. the user or [window manager][gtk-X11-arch]) could
- * unfullscreen it again, and not all window managers honor requests to fullscreen
- * windows.
+ * Note that you shouldn’t assume the window is definitely fullscreen
+ * afterward, because other entities (e.g. the user or window manager
+ * unfullscreen it again, and not all window managers honor requests
+ * to fullscreen windows.
*
- * You can track the result of this operation via the #GdkToplevel:state property,
- * or by listening to notifications of the #GtkWindow:fullscreened property.
+ * You can track the result of this operation via the
+ * [property@Gdk.Toplevel:state] property, or by listening to
+ * notifications of the [property@Gtk.Window:fullscreened] property.
*/
void
gtk_window_fullscreen (GtkWindow *window)
@@ -5300,18 +5388,18 @@ gtk_window_fullscreen (GtkWindow *window)
/**
* gtk_window_fullscreen_on_monitor:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
* @monitor: which monitor to go fullscreen on
*
* Asks to place @window in the fullscreen state on the given @monitor.
*
- * Note that you shouldn't assume the window is definitely full screen
+ * Note that you shouldn't assume the window is definitely fullscreen
* afterward, or that the windowing system allows fullscreen windows on
* any given monitor.
*
- * You can track the result of this operation via the #GdkToplevel:state
- * property, or by listening to notifications of the #GtkWindow:fullscreened
- * property.
+ * You can track the result of this operation via the
+ * [property@Gdk.Toplevel:state] property, or by listening to
+ * notifications of the [property@Gtk.Window:fullscreened] property.
*/
void
gtk_window_fullscreen_on_monitor (GtkWindow *window,
@@ -5348,19 +5436,21 @@ gtk_window_fullscreen_on_monitor (GtkWindow *window,
/**
* gtk_window_unfullscreen:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
*
- * Asks to remove the fullscreen state for @window, and return to its previous
- * state.
+ * Asks to remove the fullscreen state for @window, and return to
+ * its previous state.
*
- * Note that you shouldn’t assume the window is definitely not full screen afterward,
- * because other entities (e.g. the user or [window manager][gtk-X11-arch]) could
- * fullscreen it again, and not all window managers honor requests to unfullscreen
- * windows; normally the window will end up restored to its normal state. Just don’t
+ * Note that you shouldn’t assume the window is definitely not
+ * fullscreen afterward, because other entities (e.g. the user or
+ * window manager could fullscreen it again, and not all window
+ * managers honor requests to unfullscreen windows; normally the
+ * window will end up restored to its normal state. Just don’t
* write code that crashes if not.
*
- * You can track the result of this operation via the #GdkToplevel:state property,
- * or by listening to notifications of the #GtkWindow:fullscreened property.
+ * You can track the result of this operation via the
+ * [property@Gdk.Toplevel:state] property, or by listening to
+ * notifications of the [property@Gtk.Window:fullscreened] property.
*/
void
gtk_window_unfullscreen (GtkWindow *window)
@@ -5387,8 +5477,8 @@ gtk_window_unfullscreen (GtkWindow *window)
}
/**
- * gtk_window_set_resizable:
- * @window: a #GtkWindow
+ * gtk_window_set_resizable: (attributes org.gtk.Method.set_property=resizable)
+ * @window: a `GtkWindow`
* @resizable: %TRUE if the user can resize this window
*
* Sets whether the user can resize a window.
@@ -5418,8 +5508,8 @@ gtk_window_set_resizable (GtkWindow *window,
}
/**
- * gtk_window_get_resizable:
- * @window: a #GtkWindow
+ * gtk_window_get_resizable: (attributes org.gtk.Method.get_property=resizable)
+ * @window: a `GtkWindow`
*
* Gets the value set by gtk_window_set_resizable().
*
@@ -5436,13 +5526,14 @@ gtk_window_get_resizable (GtkWindow *window)
}
/**
- * gtk_window_set_display:
- * @window: a #GtkWindow.
- * @display: a #GdkDisplay.
+ * gtk_window_set_display: (attributes org.gtk.Method.set_property=display)
+ * @window: a `GtkWindow`
+ * @display: a `GdkDisplay`
+ *
+ * Sets the `GdkDisplay` where the @window is displayed.
*
- * Sets the #GdkDisplay where the @window is displayed; if
- * the window is already mapped, it will be unmapped, and
- * then remapped on the new display.
+ * If the window is already mapped, it will be unmapped,
+ * and then remapped on the new display.
*/
void
gtk_window_set_display (GtkWindow *window,
@@ -5524,17 +5615,19 @@ gtk_window_on_theme_variant_changed (GtkSettings *settings,
#endif
/**
- * gtk_window_is_active:
- * @window: a #GtkWindow
- *
+ * gtk_window_is_active: (attributes org.gtk.Method.get_property=is-active)
+ * @window: a `GtkWindow`
+ *
* Returns whether the window is part of the current active toplevel.
- * (That is, the toplevel window receiving keystrokes.)
+ *
+ * The active toplevel is the window receiving keystrokes.
+ *
* The return value is %TRUE if the window is active toplevel itself.
* You might use this function if you wanted to draw a widget
* differently in an active window from a widget in an inactive window.
- *
+ *
* Returns: %TRUE if the window part of the current active window.
- **/
+ */
gboolean
gtk_window_is_active (GtkWindow *window)
{
@@ -5547,13 +5640,14 @@ gtk_window_is_active (GtkWindow *window)
/**
* gtk_window_get_group:
- * @window: (allow-none): a #GtkWindow, or %NULL
+ * @window: (allow-none): a `GtkWindow`, or %NULL
+ *
+ * Returns the group for @window.
*
- * Returns the group for @window or the default group, if
- * @window is %NULL or if @window does not have an explicit
- * window group.
+ * If the window has no group, then the default group is returned.
*
- * Returns: (transfer none): the #GtkWindowGroup for a window or the default group
+ * Returns: (transfer none): the `GtkWindowGroup` for a window
+ * or the default group
*/
GtkWindowGroup *
gtk_window_get_group (GtkWindow *window)
@@ -5575,12 +5669,12 @@ gtk_window_get_group (GtkWindow *window)
/**
* gtk_window_has_group:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
*
* Returns whether @window has an explicit window group.
*
* Returns: %TRUE if @window has an explicit window group.
- **/
+ */
gboolean
gtk_window_has_group (GtkWindow *window)
{
@@ -5654,13 +5748,13 @@ gtk_window_keys_changed (GtkWindow *window)
/*
* _gtk_window_set_is_active:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
* @is_active: %TRUE if the window is in the currently active toplevel
*
- * Internal function that sets whether the #GtkWindow is part
- * of the currently active toplevel window (taking into account inter-process
- * embedding.)
- **/
+ * Internal function that sets whether the `GtkWindow` is part
+ * of the currently active toplevel window (taking into account
+ * inter-process embedding.)
+ */
static void
_gtk_window_set_is_active (GtkWindow *window,
gboolean is_active)
@@ -5693,9 +5787,11 @@ _gtk_window_set_is_active (GtkWindow *window,
* gtk_window_set_auto_startup_notification:
* @setting: %TRUE to automatically do startup notification
*
- * By default, after showing the first #GtkWindow, GTK calls
- * gdk_display_notify_startup_complete(). Call this function to
- * disable the automatic startup notification. You might do this
+ * Sets whether the window should request startup notification.
+ *
+ * By default, after showing the first `GtkWindow`, GTK calls
+ * [method@Gdk.Display.notify_startup_complete]. Call this function
+ * to disable the automatic startup notification. You might do this
* if your first window is a splash screen, and you want to delay
* notification until after your real main window has been shown,
* for example.
@@ -5703,7 +5799,7 @@ _gtk_window_set_is_active (GtkWindow *window,
* In that example, you would disable startup notification
* temporarily, show your splash screen, then re-enable it so that
* showing the main window would automatically result in notification.
- **/
+ */
void
gtk_window_set_auto_startup_notification (gboolean setting)
{
@@ -5711,13 +5807,13 @@ gtk_window_set_auto_startup_notification (gboolean setting)
}
/**
- * gtk_window_get_mnemonics_visible:
- * @window: a #GtkWindow
+ * gtk_window_get_mnemonics_visible: (attributes org.gtk.MEthod.get_property=mnemonics-visible)
+ * @window: a `GtkWindow`
*
- * Gets the value of the #GtkWindow:mnemonics-visible property.
+ * Gets whether mnemonics are supposed to be visible.
*
* Returns: %TRUE if mnemonics are supposed to be visible
- * in this window.
+ * in this window.
*/
gboolean
gtk_window_get_mnemonics_visible (GtkWindow *window)
@@ -5731,10 +5827,10 @@ gtk_window_get_mnemonics_visible (GtkWindow *window)
/**
* gtk_window_set_mnemonics_visible:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
* @setting: the new value
*
- * Sets the #GtkWindow:mnemonics-visible property.
+ * Sets whether mnemonics are supposed to be visible.
*/
void
gtk_window_set_mnemonics_visible (GtkWindow *window,
@@ -5788,13 +5884,13 @@ _gtk_window_schedule_mnemonics_visible (GtkWindow *window)
}
/**
- * gtk_window_get_focus_visible:
- * @window: a #GtkWindow
+ * gtk_window_get_focus_visible: (attributes org.gtk.Method.get_property=focus-visible)
+ * @window: a `GtkWindow`
*
- * Gets the value of the #GtkWindow:focus-visible property.
+ * Gets whether “focus rectangles” are supposed to be visible.
*
* Returns: %TRUE if “focus rectangles” are supposed to be visible
- * in this window.
+ * in this window.
*/
gboolean
gtk_window_get_focus_visible (GtkWindow *window)
@@ -5820,11 +5916,11 @@ unset_focus_visible (gpointer data)
}
/**
- * gtk_window_set_focus_visible:
- * @window: a #GtkWindow
+ * gtk_window_set_focus_visible: (attributes org.gtk.MEthod.set_property=focus-visible)
+ * @window: a `GtkWindow`
* @setting: the new value
*
- * Sets the #GtkWindow:focus-visible property.
+ * Sets whether “focus rectangles” are supposed to be visible.
*/
void
gtk_window_set_focus_visible (GtkWindow *window,
@@ -5979,8 +6075,9 @@ gtk_window_set_debugging (GdkDisplay *display,
* gtk_window_set_interactive_debugging:
* @enable: %TRUE to enable interactive debugging
*
- * Opens or closes the [interactive debugger][interactive-debugging],
- * which offers access to the widget hierarchy of the application
+ * Opens or closes the [interactive debugger](#interactive-debugging).
+ *
+ * The debugger offers access to the widget hierarchy of the application
* and to useful debugging tools.
*/
void
@@ -6418,8 +6515,8 @@ gtk_window_maybe_update_cursor (GtkWindow *window,
}
/**
- * gtk_window_set_child:
- * @window: a #GtkWindow
+ * gtk_window_set_child: (attributes org.gtk.Method.set_property=child)
+ * @window: a `GtkWindow`
* @child: (allow-none): the child widget
*
* Sets the child widget of @window.
@@ -6445,8 +6542,8 @@ gtk_window_set_child (GtkWindow *window,
}
/**
- * gtk_window_get_child:
- * @window: a #GtkWindow
+ * gtk_window_get_child: (attributes org.gtk.Method.get_property=child)
+ * @window: a `GtkWindow`
*
* Gets the child widget of @window.
*
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
