mirror of
https://gitlab.gnome.org/GNOME/gtk.git
synced 2024-12-26 21:51:08 +00:00
nativedialog: Convert docs
This commit is contained in:
Matthias Clasen
Emmanuele Bassi
parent
bb393f6496
commit
86604d8e01
@ -36,24 +36,22 @@
|
||||
#include "gtklabel.h"
|
||||
|
||||
/**
|
||||
* SECTION:gtknativedialog
|
||||
* @Short_description: Integrate with native dialogs
|
||||
* @Title: GtkNativeDialog
|
||||
* @See_also: #GtkFileChooserNative, #GtkDialog
|
||||
* GtkNativeDialog:
|
||||
*
|
||||
* Native dialogs are platform dialogs that don't use #GtkDialog or
|
||||
* #GtkWindow. They are used in order to integrate better with a
|
||||
* platform, by looking the same as other native applications and
|
||||
* supporting platform specific features.
|
||||
* Native dialogs are platform dialogs that don't use `GtkDialog`.
|
||||
*
|
||||
* The #GtkDialog functions cannot be used on such objects, but we
|
||||
* need a similar API in order to drive them. The #GtkNativeDialog
|
||||
* They are used in order to integrate better with a platform, by
|
||||
* looking the same as other native applications and supporting
|
||||
* platform specific features.
|
||||
*
|
||||
* The [class@Gtk.Dialog] functions cannot be used on such objects,
|
||||
* but we need a similar API in order to drive them. The `GtkNativeDialog`
|
||||
* object is an API that allows you to do this. It allows you to set
|
||||
* various common properties on the dialog, as well as show and hide
|
||||
* it and get a #GtkNativeDialog::response signal when the user finished
|
||||
* with the dialog.
|
||||
* it and get a [signal@Gtk.NativeDialog::response] signal when the user
|
||||
* finished with the dialog.
|
||||
*
|
||||
* Note that unlike #GtkDialog, #GtkNativeDialog objects are not
|
||||
* Note that unlike `GtkDialog`, `GtkNativeDialog` objects are not
|
||||
* toplevel widgets, and GTK does not keep them alive. It is your
|
||||
* responsibility to keep a reference until you are done with the
|
||||
* object.
|
||||
@ -205,7 +203,7 @@ gtk_native_dialog_class_init (GtkNativeDialogClass *class)
|
||||
gobject_class->dispose = gtk_native_dialog_dispose;
|
||||
|
||||
/**
|
||||
* GtkNativeDialog:title:
|
||||
* GtkNativeDialog:title: (attributes org.gtk.Property.get=gtk_native_dialog_get_title org.gtk.Property.set=gtk_native_dialog_set_title)
|
||||
*
|
||||
* The title of the dialog window
|
||||
*/
|
||||
@ -217,7 +215,7 @@ gtk_native_dialog_class_init (GtkNativeDialogClass *class)
|
||||
GTK_PARAM_READWRITE);
|
||||
|
||||
/**
|
||||
* GtkNativeDialog:modal:
|
||||
* GtkNativeDialog:modal: (attributes org.gtk.Property.get=gtk_native_dialog_get_modal org.gtk.Property.set=gtk_native_dialog_set_modal)
|
||||
*
|
||||
* Whether the window should be modal with respect to its transient parent.
|
||||
*/
|
||||
@ -229,7 +227,7 @@ gtk_native_dialog_class_init (GtkNativeDialogClass *class)
|
||||
GTK_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY);
|
||||
|
||||
/**
|
||||
* GtkNativeDialog:visible:
|
||||
* GtkNativeDialog:visible: (attributes org.gtk.Property.get=gtk_native_dialog_get_visible)
|
||||
*
|
||||
* Whether the window is currently visible.
|
||||
*/
|
||||
@ -241,7 +239,7 @@ gtk_native_dialog_class_init (GtkNativeDialogClass *class)
|
||||
GTK_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY);
|
||||
|
||||
/**
|
||||
* GtkNativeDialog:transient-for:
|
||||
* GtkNativeDialog:transient-for: (attributes org.gtk.Property.get=gtk_native_dialog_get_transient_for org.gtk.Property.set=gtk_native_dialog_set_transient_for)
|
||||
*
|
||||
* The transient parent of the dialog, or %NULL for none.
|
||||
*/
|
||||
@ -263,8 +261,8 @@ gtk_native_dialog_class_init (GtkNativeDialogClass *class)
|
||||
*
|
||||
* When this is called the dialog has been hidden.
|
||||
*
|
||||
* If you call gtk_native_dialog_hide() before the user responds to
|
||||
* the dialog this signal will not be emitted.
|
||||
* If you call [method@Gtk.NativeDialog.hide] before the user
|
||||
* responds to the dialog this signal will not be emitted.
|
||||
*/
|
||||
native_signals[RESPONSE] =
|
||||
g_signal_new (I_("response"),
|
||||
@ -284,15 +282,16 @@ gtk_native_dialog_init (GtkNativeDialog *self)
|
||||
|
||||
/**
|
||||
* gtk_native_dialog_show:
|
||||
* @self: a #GtkNativeDialog
|
||||
* @self: a `GtkNativeDialog`
|
||||
*
|
||||
* Shows the dialog on the display, allowing the user to interact with
|
||||
* it. When the user accepts the state of the dialog the dialog will
|
||||
* be automatically hidden and the #GtkNativeDialog::response signal
|
||||
* will be emitted.
|
||||
* Shows the dialog on the display.
|
||||
*
|
||||
* When the user accepts the state of the dialog the dialog will
|
||||
* be automatically hidden and the [signal@Gtk.NativeDialog::response]
|
||||
* signal will be emitted.
|
||||
*
|
||||
* Multiple calls while the dialog is visible will be ignored.
|
||||
**/
|
||||
*/
|
||||
void
|
||||
gtk_native_dialog_show (GtkNativeDialog *self)
|
||||
{
|
||||
@ -302,7 +301,7 @@ gtk_native_dialog_show (GtkNativeDialog *self)
|
||||
g_return_if_fail (GTK_IS_NATIVE_DIALOG (self));
|
||||
|
||||
if (priv->visible)
|
||||
return;
|
||||
return;
|
||||
|
||||
klass = GTK_NATIVE_DIALOG_GET_CLASS (self);
|
||||
|
||||
@ -316,14 +315,16 @@ gtk_native_dialog_show (GtkNativeDialog *self)
|
||||
|
||||
/**
|
||||
* gtk_native_dialog_hide:
|
||||
* @self: a #GtkNativeDialog
|
||||
* @self: a `GtkNativeDialog`
|
||||
*
|
||||
* Hides the dialog if it is visilbe, aborting any interaction. Once this
|
||||
* is called the #GtkNativeDialog::response signal will not be emitted
|
||||
* until after the next call to gtk_native_dialog_show().
|
||||
* Hides the dialog if it is visible, aborting any interaction.
|
||||
*
|
||||
* Once this is called the [signal@Gtk.NativeDialog::response] signal
|
||||
* will *not* be emitted until after the next call to
|
||||
* [method@Gtk.NativeDialog.show].
|
||||
*
|
||||
* If the dialog is not visible this does nothing.
|
||||
**/
|
||||
*/
|
||||
void
|
||||
gtk_native_dialog_hide (GtkNativeDialog *self)
|
||||
{
|
||||
@ -348,18 +349,20 @@ gtk_native_dialog_hide (GtkNativeDialog *self)
|
||||
|
||||
/**
|
||||
* gtk_native_dialog_destroy:
|
||||
* @self: a #GtkNativeDialog
|
||||
* @self: a `GtkNativeDialog`
|
||||
*
|
||||
* Destroys a dialog.
|
||||
*
|
||||
* When a dialog is destroyed, it will break any references it holds
|
||||
* to other objects. If it is visible it will be hidden and any underlying
|
||||
* window system resources will be destroyed.
|
||||
* to other objects.
|
||||
*
|
||||
* Note that this does not release any reference to the object (as opposed to
|
||||
* destroying a GtkWindow) because there is no reference from the windowing
|
||||
* system to the #GtkNativeDialog.
|
||||
**/
|
||||
* If it is visible it will be hidden and any underlying window system
|
||||
* resources will be destroyed.
|
||||
*
|
||||
* Note that this does not release any reference to the object (as opposed
|
||||
* to destroying a `GtkWindow`) because there is no reference from the
|
||||
* windowing system to the `GtkNativeDialog`.
|
||||
*/
|
||||
void
|
||||
gtk_native_dialog_destroy (GtkNativeDialog *self)
|
||||
{
|
||||
@ -380,13 +383,13 @@ _gtk_native_dialog_emit_response (GtkNativeDialog *self,
|
||||
}
|
||||
|
||||
/**
|
||||
* gtk_native_dialog_get_visible:
|
||||
* @self: a #GtkNativeDialog
|
||||
* gtk_native_dialog_get_visible: (attributes org.gtk.Method.get_property=visible)
|
||||
* @self: a `GtkNativeDialog`
|
||||
*
|
||||
* Determines whether the dialog is visible.
|
||||
*
|
||||
* Returns: %TRUE if the dialog is visible
|
||||
**/
|
||||
*/
|
||||
gboolean
|
||||
gtk_native_dialog_get_visible (GtkNativeDialog *self)
|
||||
{
|
||||
@ -398,17 +401,18 @@ gtk_native_dialog_get_visible (GtkNativeDialog *self)
|
||||
}
|
||||
|
||||
/**
|
||||
* gtk_native_dialog_set_modal:
|
||||
* @self: a #GtkNativeDialog
|
||||
* gtk_native_dialog_set_modal: (attributes org.gtk.Method.set_property=modal)
|
||||
* @self: a `GtkNativeDialog`
|
||||
* @modal: whether the window is modal
|
||||
*
|
||||
* Sets a dialog modal or non-modal. Modal dialogs prevent interaction
|
||||
* with other windows in the same application. To keep modal dialogs
|
||||
* on top of main application windows, use
|
||||
* gtk_native_dialog_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 dialog modal or non-modal.
|
||||
*
|
||||
* Modal dialogs prevent interaction with other windows in the same
|
||||
* application. To keep modal dialogs on top of main application
|
||||
* windows, use [method@Gtk.NativeDialog.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_native_dialog_set_modal (GtkNativeDialog *self,
|
||||
gboolean modal)
|
||||
@ -427,13 +431,13 @@ gtk_native_dialog_set_modal (GtkNativeDialog *self,
|
||||
}
|
||||
|
||||
/**
|
||||
* gtk_native_dialog_get_modal:
|
||||
* @self: a #GtkNativeDialog
|
||||
* gtk_native_dialog_get_modal: (attributes org.gtk.Method.get_property=modal)
|
||||
* @self: a `GtkNativeDialog`
|
||||
*
|
||||
* Returns whether the dialog is modal. See gtk_native_dialog_set_modal().
|
||||
* Returns whether the dialog is modal.
|
||||
*
|
||||
* Returns: %TRUE if the dialog is set to be modal
|
||||
**/
|
||||
*/
|
||||
gboolean
|
||||
gtk_native_dialog_get_modal (GtkNativeDialog *self)
|
||||
{
|
||||
@ -445,12 +449,12 @@ gtk_native_dialog_get_modal (GtkNativeDialog *self)
|
||||
}
|
||||
|
||||
/**
|
||||
* gtk_native_dialog_set_title:
|
||||
* @self: a #GtkNativeDialog
|
||||
* gtk_native_dialog_set_title: (attributes org.gtk.Method.set_property=title)
|
||||
* @self: a `GtkNativeDialog`
|
||||
* @title: title of the dialog
|
||||
*
|
||||
* Sets the title of the #GtkNativeDialog.
|
||||
**/
|
||||
* Sets the title of the `GtkNativeDialog.`
|
||||
*/
|
||||
void
|
||||
gtk_native_dialog_set_title (GtkNativeDialog *self,
|
||||
const char *title)
|
||||
@ -466,15 +470,15 @@ gtk_native_dialog_set_title (GtkNativeDialog *self,
|
||||
}
|
||||
|
||||
/**
|
||||
* gtk_native_dialog_get_title:
|
||||
* @self: a #GtkNativeDialog
|
||||
* gtk_native_dialog_get_title: (attributes org.gtk.Method.get_property=title)
|
||||
* @self: a `GtkNativeDialog`
|
||||
*
|
||||
* Gets the title of the #GtkNativeDialog.
|
||||
* Gets the title of the `GtkNativeDialog`.
|
||||
*
|
||||
* Returns: (nullable): the title of the dialog, or %NULL if none has
|
||||
* been set explicitly. The returned string is owned by the widget
|
||||
* and must not be modified or freed.
|
||||
**/
|
||||
*/
|
||||
const char *
|
||||
gtk_native_dialog_get_title (GtkNativeDialog *self)
|
||||
{
|
||||
@ -495,15 +499,15 @@ parent_destroyed (GtkWidget *parent,
|
||||
}
|
||||
|
||||
/**
|
||||
* gtk_native_dialog_set_transient_for:
|
||||
* @self: a #GtkNativeDialog
|
||||
* gtk_native_dialog_set_transient_for: (attributes org.gtk.Method.set_property=transient-for)
|
||||
* @self: a `GtkNativeDialog`
|
||||
* @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.
|
||||
* 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.
|
||||
*
|
||||
* Passing %NULL for @parent unsets the current transient window.
|
||||
*/
|
||||
@ -530,15 +534,14 @@ gtk_native_dialog_set_transient_for (GtkNativeDialog *self,
|
||||
}
|
||||
|
||||
/**
|
||||
* gtk_native_dialog_get_transient_for:
|
||||
* @self: a #GtkNativeDialog
|
||||
* gtk_native_dialog_get_transient_for: (attributes org.gtk.Method.get_property=transient-for)
|
||||
* @self: a `GtkNativeDialog`
|
||||
*
|
||||
* Fetches the transient parent for this window. See
|
||||
* gtk_native_dialog_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.
|
||||
**/
|
||||
* or %NULL if no transient parent has been set.
|
||||
*/
|
||||
GtkWindow *
|
||||
gtk_native_dialog_get_transient_for (GtkNativeDialog *self)
|
||||
{
|
||||
|
||||
Loading…
Reference in New Issue
Block a user