[gcr] gcr: Fix up documentation for recent prompting work
- From: Stefan Walter <stefw src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gcr] gcr: Fix up documentation for recent prompting work
- Date: Mon, 19 Dec 2011 07:34:43 +0000 (UTC)
commit 039f24d12e79d806f632e90332b50ca916ec83d6
Author: Stef Walter <stefw collabora co uk>
Date: Sat Dec 17 08:55:59 2011 +0100
gcr: Fix up documentation for recent prompting work
docs/reference/gcr/gcr-sections.txt | 127 +++++++++-
docs/reference/gcr/gcr.interfaces | 5 +-
docs/reference/gcr/gcr.types | 4 +
gcr/gcr-base.symbols | 1 -
gcr/gcr-callback-output-stream.c | 2 +
gcr/gcr-certificate-basics-widget.c | 6 +
gcr/gcr-certificate-details-widget.c | 6 +
gcr/gcr-certificate.c | 8 +
gcr/gcr-dbus-constants.h | 1 +
gcr/gcr-gnupg-importer.c | 2 +
gcr/gcr-importer.c | 2 +
gcr/gcr-live-search.c | 2 +
gcr/gcr-menu-button.c | 2 +
gcr/gcr-mock-prompter.c | 102 ++++++++
gcr/gcr-mock-prompter.h | 4 +-
gcr/gcr-pkcs11-importer.c | 2 +
gcr/gcr-prompt-dialog.c | 55 ++++
gcr/gcr-prompt-dialog.h | 4 +-
gcr/gcr-prompt.c | 460 +++++++++++++++++++++++++++++++++-
gcr/gcr-prompt.h | 6 +-
gcr/gcr-prompter-tool.c | 2 +-
gcr/gcr-secure-entry-buffer.c | 17 +-
gcr/gcr-secure-entry-buffer.h | 7 +-
gcr/gcr-system-prompt.c | 136 ++++++++--
gcr/gcr-system-prompt.h | 11 +-
gcr/gcr-system-prompter.c | 84 ++++++-
gcr/gcr-system-prompter.h | 6 +-
gcr/gcr-viewer-widget.c | 15 ++
28 files changed, 1009 insertions(+), 70 deletions(-)
---
diff --git a/docs/reference/gcr/gcr-sections.txt b/docs/reference/gcr/gcr-sections.txt
index 45840d8..4b90f39 100644
--- a/docs/reference/gcr/gcr-sections.txt
+++ b/docs/reference/gcr/gcr-sections.txt
@@ -376,6 +376,7 @@ gcr_collection_model_new
gcr_collection_model_new_full
gcr_collection_model_set_columns
gcr_collection_model_get_collection
+gcr_collection_model_set_collection
gcr_collection_model_iter_for_object
gcr_collection_model_object_for_iter
gcr_collection_model_is_selected
@@ -708,6 +709,130 @@ gcr_importer_prompt_behavior_get_type
</SECTION>
<SECTION>
-<FILE>GcrPrompter1</FILE>
+<FILE>gcr-prompt</FILE>
+GcrPrompt
+GcrPromptIface
+GcrPromptReply
+gcr_prompt_password
+gcr_prompt_password_async
+gcr_prompt_password_finish
+gcr_prompt_password_run
+gcr_prompt_confirm
+gcr_prompt_confirm_async
+gcr_prompt_confirm_finish
+gcr_prompt_confirm_run
+gcr_prompt_get_title
+gcr_prompt_set_title
+gcr_prompt_get_message
+gcr_prompt_set_message
+gcr_prompt_get_description
+gcr_prompt_set_description
+gcr_prompt_get_warning
+gcr_prompt_set_warning
+gcr_prompt_get_choice_label
+gcr_prompt_set_choice_label
+gcr_prompt_get_choice_chosen
+gcr_prompt_set_choice_chosen
+gcr_prompt_get_password_new
+gcr_prompt_set_password_new
+gcr_prompt_get_password_strength
+gcr_prompt_get_caller_window
+gcr_prompt_set_caller_window
<SUBSECTION Private>
+gcr_prompt_get_type
+gcr_prompt_reply_get_type
+GCR_IS_PROMPT
+GCR_PROMPT
+GCR_PROMPT_GET_INTERFACE
+GCR_TYPE_PROMPT
+GCR_TYPE_PROMPT_REPLY
</SECTION>
+
+<SECTION>
+<FILE>gcr-prompt-dialog</FILE>
+GcrPromptDialog
+GcrPromptDialogClass
+<SUBSECTION Private>
+GcrPromptDialogPrivate
+gcr_prompt_dialog_get_type
+GCR_IS_PROMPT_DIALOG
+GCR_IS_PROMPT_DIALOG_CLASS
+GCR_PROMPT_DIALOG
+GCR_PROMPT_DIALOG_CLASS
+GCR_PROMPT_DIALOG_GET_CLASS
+GCR_TYPE_PROMPT_DIALOG
+</SECTION>
+
+<SECTION>
+<FILE>gcr-system-prompt</FILE>
+GcrSystemPrompt
+GcrSystemPromptClass
+GCR_SYSTEM_PROMPT_ERROR
+GcrSystemPromptError
+gcr_system_prompt_open
+gcr_system_prompt_open_async
+gcr_system_prompt_open_finish
+gcr_system_prompt_open_for_prompter
+gcr_system_prompt_open_for_prompter_async
+gcr_system_prompt_get_secret_exchange
+gcr_system_prompt_close
+gcr_system_prompt_close_async
+gcr_system_prompt_close_finish
+<SUBSECTION Private>
+GcrSystemPromptPrivate
+gcr_system_prompt_error_get_domain
+gcr_system_prompt_error_get_type
+gcr_system_prompt_get_type
+GCR_IS_SYSTEM_PROMPT
+GCR_IS_SYSTEM_PROMPT_CLASS
+GCR_SYSTEM_PROMPT
+GCR_SYSTEM_PROMPT_CLASS
+GCR_SYSTEM_PROMPT_GET_CLASS
+GCR_TYPE_SYSTEM_PROMPT
+GCR_TYPE_SYSTEM_PROMPT_ERROR
+</SECTION>
+
+<SECTION>
+<FILE>gcr-system-prompter</FILE>
+GcrSystemPrompter
+GcrSystemPrompterClass
+GcrSystemPrompterMode
+gcr_system_prompter_new
+gcr_system_prompter_register
+gcr_system_prompter_unregister
+gcr_system_prompter_get_mode
+gcr_system_prompter_get_prompt_type
+<SUBSECTION Private>
+GcrSystemPrompterPrivate
+gcr_system_prompter_get_type
+gcr_system_prompter_mode_get_type
+GCR_IS_SYSTEM_PROMPTER
+GCR_IS_SYSTEM_PROMPTER_CLASS
+GCR_SYSTEM_PROMPTER
+GCR_SYSTEM_PROMPTER_CLASS
+GCR_SYSTEM_PROMPTER_GET_CLASS
+GCR_TYPE_SYSTEM_PROMPTER
+GCR_TYPE_SYSTEM_PROMPTER_MODE
+</SECTION>
+
+<SECTION>
+<FILE>gcr-mock-prompter</FILE>
+gcr_mock_prompter_start
+gcr_mock_prompter_stop
+gcr_mock_prompter_expect_confirm_cancel
+gcr_mock_prompter_expect_confirm_ok
+gcr_mock_prompter_expect_password_cancel
+gcr_mock_prompter_expect_password_ok
+gcr_mock_prompter_get_delay_msec
+gcr_mock_prompter_set_delay_msec
+gcr_mock_prompter_is_expecting
+gcr_mock_prompter_is_prompting
+</SECTION>
+
+<SECTION>
+<FILE>GcrDBusPrompter</FILE>
+</SECTION>
+
+<SECTION>
+<FILE>GcrDBusPrompterCallback</FILE>
+</SECTION>
\ No newline at end of file
diff --git a/docs/reference/gcr/gcr.interfaces b/docs/reference/gcr/gcr.interfaces
index c65f21a..15d9427 100644
--- a/docs/reference/gcr/gcr.interfaces
+++ b/docs/reference/gcr/gcr.interfaces
@@ -11,6 +11,8 @@ GcrComboSelector AtkImplementorIface GtkBuildable GtkCellLayout GtkCellEditable
GtkButton AtkImplementorIface GtkBuildable GtkActivatable
GcrImportButton AtkImplementorIface GtkBuildable GtkActivatable
GtkWindow AtkImplementorIface GtkBuildable
+GtkDialog AtkImplementorIface GtkBuildable
+GcrPromptDialog AtkImplementorIface GtkBuildable GcrPrompt
GcrViewerWindow AtkImplementorIface GtkBuildable
GtkTreeView AtkImplementorIface GtkBuildable GtkScrollable
GcrListSelector AtkImplementorIface GtkBuildable GtkScrollable
@@ -25,14 +27,15 @@ GcrKeyRenderer GcrRenderer
GcrPkcs11Certificate GcrComparableIface GcrCertificate
GcrSimpleCertificate GcrComparableIface GcrCertificate
GcrSimpleCollection GcrCollection
+GcrSystemPrompt GcrPrompt GInitable GAsyncInitable
GcrUnionCollection GcrCollection
GtkWidgetAccessible AtkComponent
GtkContainerAccessible AtkComponent
GtkComboBoxAccessible AtkComponent AtkAction AtkSelection
GtkButtonAccessible AtkComponent AtkAction AtkImage
GtkTreeViewAccessible AtkComponent AtkTable AtkSelection GtkCellAccessibleParent
-GtkBoxAccessible AtkComponent
GtkWindowAccessible AtkComponent AtkWindow
+GtkBoxAccessible AtkComponent
GtkAction GtkBuildable
GckSession GInitable GAsyncInitable
GdkPixbuf GIcon
diff --git a/docs/reference/gcr/gcr.types b/docs/reference/gcr/gcr.types
index bbfa483..8cfcfb4 100644
--- a/docs/reference/gcr/gcr.types
+++ b/docs/reference/gcr/gcr.types
@@ -14,10 +14,14 @@ gcr_key_widget_get_type
gcr_list_selector_get_type
gcr_parser_get_type
gcr_pkcs11_certificate_get_type
+gcr_prompt_get_type
+gcr_prompt_dialog_get_type
gcr_renderer_get_type
gcr_secure_entry_buffer_get_type
gcr_simple_certificate_get_type
gcr_simple_collection_get_type
+gcr_system_prompt_get_type
+gcr_system_prompter_get_type
gcr_tree_selector_get_type
gcr_union_collection_get_type
gcr_unlock_options_widget_get_type
diff --git a/gcr/gcr-base.symbols b/gcr/gcr-base.symbols
index 4a0e1ad..b77f10d 100644
--- a/gcr/gcr-base.symbols
+++ b/gcr/gcr-base.symbols
@@ -213,7 +213,6 @@ gcr_system_prompt_open_async
gcr_system_prompt_open_finish
gcr_system_prompt_open_for_prompter
gcr_system_prompt_open_for_prompter_async
-gcr_system_prompt_response_get_type
gcr_trust_add_pinned_certificate
gcr_trust_add_pinned_certificate_async
gcr_trust_add_pinned_certificate_finish
diff --git a/gcr/gcr-callback-output-stream.c b/gcr/gcr-callback-output-stream.c
index 9988e1f..94fc4c3 100644
--- a/gcr/gcr-callback-output-stream.c
+++ b/gcr/gcr-callback-output-stream.c
@@ -112,6 +112,8 @@ _gcr_callback_output_stream_class_init (GcrCallbackOutputStreamClass *klass)
/**
* _gcr_callback_output_stream_new: (skip)
*
+ * Create a new output stream which invokes the callback.
+ *
* Returns: (transfer full) (type Gcr.CallbackOutputStream): the new stream
*/
GOutputStream *
diff --git a/gcr/gcr-certificate-basics-widget.c b/gcr/gcr-certificate-basics-widget.c
index f1d4528..b7251dc 100644
--- a/gcr/gcr-certificate-basics-widget.c
+++ b/gcr/gcr-certificate-basics-widget.c
@@ -35,6 +35,8 @@ gcr_certificate_basics_widget_get_type (void)
/**
* gcr_certificate_basics_widget_new: (skip)
*
+ * Create new certificate viewer.
+ *
* Deprecated: Since 2.30
*
* Returns: (transfer full) (type Gcr.CertificateWidget): a new certificate widget
@@ -48,6 +50,8 @@ gcr_certificate_basics_widget_new (GcrCertificate *cert)
/**
* gcr_certificate_basics_widget_get_certificate: (skip)
*
+ * Get certificate on viewer.
+ *
* Deprecated: Since 2.30
*
* Returns: (transfer none): the certificate
@@ -63,6 +67,8 @@ gcr_certificate_basics_widget_get_certificate (GcrCertificateBasicsWidget *basic
* @basics: the certificate widget
* @cert: the certificate
*
+ * Set certificate on viewer.
+ *
* Deprecated: Since 2.30
*/
void
diff --git a/gcr/gcr-certificate-details-widget.c b/gcr/gcr-certificate-details-widget.c
index 9fc2307..cfcbfd5 100644
--- a/gcr/gcr-certificate-details-widget.c
+++ b/gcr/gcr-certificate-details-widget.c
@@ -35,6 +35,8 @@ gcr_certificate_details_widget_get_type (void)
/**
* gcr_certificate_details_widget_new: (skip)
*
+ * Create a new certificate viewer.
+ *
* Deprecated: Since 2.30
*
* Returns: (transfer full) (type Gcr.CertificateWidget): a new certificate widget
@@ -48,6 +50,8 @@ gcr_certificate_details_widget_new (GcrCertificate *cert)
/**
* gcr_certificate_details_widget_get_certificate: (skip)
*
+ * Get certificate displayed in viewer.
+ *
* Deprecated: Since 2.30
*
* Returns: (transfer none): the certificate
@@ -63,6 +67,8 @@ gcr_certificate_details_widget_get_certificate (GcrCertificateDetailsWidget *det
* @details: the certificate widget
* @cert: the certificate
*
+ * Set certificate displayed in viewer.
+ *
* Deprecated: Since 2.30
*/
void
diff --git a/gcr/gcr-certificate.c b/gcr/gcr-certificate.c
index 95f7063..354472b 100644
--- a/gcr/gcr-certificate.c
+++ b/gcr/gcr-certificate.c
@@ -1003,6 +1003,14 @@ gcr_certificate_get_basic_constraints (GcrCertificate *self,
* </programlisting></informalexample>
*/
+/**
+ * gcr_certificate_mixin_emit_notify:
+ * @self: the #GcrCertificate
+ *
+ * Implementers of the #GcrCertificate mixin should call this function to notify
+ * when the certificate has changed to emit notifications on the various
+ * properties.
+ */
void
gcr_certificate_mixin_emit_notify (GcrCertificate *self)
{
diff --git a/gcr/gcr-dbus-constants.h b/gcr/gcr-dbus-constants.h
index ebfc4b8..aead8ab 100644
--- a/gcr/gcr-dbus-constants.h
+++ b/gcr/gcr-dbus-constants.h
@@ -28,6 +28,7 @@
G_BEGIN_DECLS
+#define GCR_DBUS_PROMPTER_SYSTEM_BUS_NAME "org.gnome.keyring.SystemPrompter"
#define GCR_DBUS_PROMPTER_BUS_NAME "org.gnome.keyring.Prompter"
#define GCR_DBUS_PROMPTER_MOCK_BUS_NAME "org.gnome.keyring.MockPrompter"
diff --git a/gcr/gcr-gnupg-importer.c b/gcr/gcr-gnupg-importer.c
index ef1c9ec..d77db87 100644
--- a/gcr/gcr-gnupg-importer.c
+++ b/gcr/gcr-gnupg-importer.c
@@ -366,6 +366,8 @@ gcr_gnupg_importer_iface (GcrImporterIface *iface)
* _gcr_gnupg_importer_new:
* @directory: (allow-none): the directory to import to, or %NULL for default
*
+ * Create a new #GcrGnupgImporter.
+ *
* Returns: (transfer full) (type Gcr.GnupgImporter): the new importer
*/
GcrImporter *
diff --git a/gcr/gcr-importer.c b/gcr/gcr-importer.c
index 4060065..b20e452 100644
--- a/gcr/gcr-importer.c
+++ b/gcr/gcr-importer.c
@@ -635,6 +635,8 @@ gcr_importer_set_slot (GcrImporter *self,
* gcr_importer_get_prompt_behavior:
* @self: The importer
*
+ * Does nothing.
+ *
* Returns: zero
*
* Deprecated: since 3.4.0
diff --git a/gcr/gcr-live-search.c b/gcr/gcr-live-search.c
index ef1919c..38de732 100644
--- a/gcr/gcr-live-search.c
+++ b/gcr/gcr-live-search.c
@@ -567,6 +567,8 @@ _gcr_live_search_init (GcrLiveSearch *self)
* _gcr_live_search_new:
* @hook: (allow-none): the widget to hook
*
+ * Create a new #GcrLiveSearch.
+ *
* Returns: (transfer full) (type Gcr.LiveSearch): The new widget
*/
GtkWidget *
diff --git a/gcr/gcr-menu-button.c b/gcr/gcr-menu-button.c
index 044d6d3..c9a98a4 100644
--- a/gcr/gcr-menu-button.c
+++ b/gcr/gcr-menu-button.c
@@ -300,6 +300,8 @@ _gcr_menu_button_class_init (GcrMenuButtonClass *klass)
* _gcr_menu_button_new:
* @label: (allow-none): the label
*
+ * Create a new #GcrMenuButton.
+ *
* Returns: (transfer full) (type Gcr.MenuButton): the new menu button
*/
GtkWidget *
diff --git a/gcr/gcr-mock-prompter.c b/gcr/gcr-mock-prompter.c
index fc0b6a6..acd660f 100644
--- a/gcr/gcr-mock-prompter.c
+++ b/gcr/gcr-mock-prompter.c
@@ -591,12 +591,27 @@ build_properties (GObjectClass *object_class,
return result;
}
+/**
+ * gcr_mock_prompter_is_prompting:
+ *
+ * Check if the mock prompter is showing any prompts.
+ *
+ * Returns: whether prompting
+ */
gboolean
gcr_mock_prompter_is_prompting (void)
{
return g_atomic_int_get (&prompts_a_prompting) > 0;
}
+/**
+ * gcr_mock_prompter_get_delay_msec:
+ *
+ * Get the delay in milliseconds before the mock prompter completes
+ * an expected prompt.
+ *
+ * Returns: the delay
+ */
guint
gcr_mock_prompter_get_delay_msec (void)
{
@@ -610,6 +625,13 @@ gcr_mock_prompter_get_delay_msec (void)
return delay_msec;
}
+/**
+ * gcr_mock_prompter_set_delay_msec:
+ * @delay_msec: prompt response delay in milliseconds
+ *
+ * Set the delay in milliseconds before the mock prompter completes
+ * an expected prompt.
+ */
void
gcr_mock_prompter_set_delay_msec (guint delay_msec)
{
@@ -619,6 +641,25 @@ gcr_mock_prompter_set_delay_msec (guint delay_msec)
g_mutex_unlock (running->mutex);
}
+/**
+ * gcr_mock_prompter_expect_confirm_ok:
+ * @first_property_name: the first property name in the argument list or %NULL
+ * @...: properties to expect
+ *
+ * Queue an expected response on the mock prompter.
+ *
+ * Expects a confirmation prompt, and then confirms that prompt by
+ * simulating a click on the ok button.
+ *
+ * Additional property pairs for the prompt can be added in the argument
+ * list, in the same way that you would with g_object_new().
+ *
+ * If the "choice-chosen" property is specified then that value will be
+ * set on the prompt as if the user had changed the value.
+ *
+ * All other properties will be checked against the prompt, and an error
+ * will occur if they do not match the value set on the prompt.
+ */
void
gcr_mock_prompter_expect_confirm_ok (const gchar *first_property_name,
...)
@@ -646,6 +687,13 @@ gcr_mock_prompter_expect_confirm_ok (const gchar *first_property_name,
g_mutex_unlock (running->mutex);
}
+/**
+ * gcr_mock_prompter_expect_confirm_cancel:
+ *
+ * Queue an expected response on the mock prompter.
+ *
+ * Expects a confirmation prompt, and then cancels that prompt.
+ */
void
gcr_mock_prompter_expect_confirm_cancel (void)
{
@@ -664,6 +712,26 @@ gcr_mock_prompter_expect_confirm_cancel (void)
g_mutex_unlock (running->mutex);
}
+/**
+ * gcr_mock_prompter_expect_password_ok:
+ * @password: the password to return from the prompt
+ * @first_property_name: the first property name in the argument list or %NULL
+ * @...: properties to expect
+ *
+ * Queue an expected response on the mock prompter.
+ *
+ * Expects a password prompt, and returns @password as if the user had entered
+ * it and clicked the ok button.
+ *
+ * Additional property pairs for the prompt can be added in the argument
+ * list, in the same way that you would with g_object_new().
+ *
+ * If the "choice-chosen" property is specified then that value will be
+ * set on the prompt as if the user had changed the value.
+ *
+ * All other properties will be checked against the prompt, and an error
+ * will occur if they do not match the value set on the prompt.
+ */
void
gcr_mock_prompter_expect_password_ok (const gchar *password,
const gchar *first_property_name,
@@ -694,6 +762,13 @@ gcr_mock_prompter_expect_password_ok (const gchar *password,
g_mutex_unlock (running->mutex);
}
+/**
+ * gcr_mock_prompter_expect_password_cancel:
+ *
+ * Queue an expected response on the mock prompter.
+ *
+ * Expects a password prompt, and then cancels that prompt.
+ */
void
gcr_mock_prompter_expect_password_cancel (void)
{
@@ -712,6 +787,16 @@ gcr_mock_prompter_expect_password_cancel (void)
g_mutex_unlock (running->mutex);
}
+/**
+ * gcr_mock_prompter_is_expecting:
+ *
+ * Check if the mock prompter is expecting a response. This will be %TRUE
+ * when one of the <literal>gcr_mock_prompter_expect_xxx<!-- -->()</literal>
+ * functions have been used to queue an expected prompt, but that prompt
+ * response has not be 'used' yet.
+ *
+ * Returns: whether expecting a prompt
+ */
gboolean
gcr_mock_prompter_is_expecting (void)
{
@@ -811,6 +896,17 @@ mock_prompter_thread (gpointer data)
return thread_data;
}
+/**
+ * gcr_mock_prompter_start:
+ *
+ * Start the mock prompter. This is often used from the
+ * <literal>setup<!-- -->()</literal> function of tests.
+ *
+ * Starts the mock prompter in an additional thread. Use the returned DBus bus
+ * name with gcr_system_prompt_open_for_prompter() to connect to this prompter.
+ *
+ * Returns: the bus name that the mock prompter is listening on
+ */
const gchar *
gcr_mock_prompter_start (void)
{
@@ -837,6 +933,12 @@ gcr_mock_prompter_start (void)
return running->bus_name;
}
+/**
+ * gcr_mock_prompter_stop:
+ *
+ * Stop the mock prompter. This is often used from the
+ * <literal>teardown<!-- -->()</literal> function of tests.
+ */
void
gcr_mock_prompter_stop (void)
{
diff --git a/gcr/gcr-mock-prompter.h b/gcr/gcr-mock-prompter.h
index 3542250..43c53cb 100644
--- a/gcr/gcr-mock-prompter.h
+++ b/gcr/gcr-mock-prompter.h
@@ -44,13 +44,13 @@ guint gcr_mock_prompter_get_delay_msec (void);
void gcr_mock_prompter_set_delay_msec (guint delay_msec);
-void gcr_mock_prompter_expect_confirm_ok (const gchar *property_name,
+void gcr_mock_prompter_expect_confirm_ok (const gchar *first_property_name,
...);
void gcr_mock_prompter_expect_confirm_cancel (void);
void gcr_mock_prompter_expect_password_ok (const gchar *password,
- const gchar *property_name,
+ const gchar *first_property_name,
...);
void gcr_mock_prompter_expect_password_cancel (void);
diff --git a/gcr/gcr-pkcs11-importer.c b/gcr/gcr-pkcs11-importer.c
index 5c5367e..0f87fe1 100644
--- a/gcr/gcr-pkcs11-importer.c
+++ b/gcr/gcr-pkcs11-importer.c
@@ -892,6 +892,8 @@ _gcr_pkcs11_importer_init_iface (GcrImporterIface *iface)
/**
* _gcr_pkcs11_importer_new:
*
+ * Create a new #GcrPkcs11Importer.
+ *
* Returns: (transfer full) (type Gcr.Pkcs11Importer): the new importer
*/
GcrImporter *
diff --git a/gcr/gcr-prompt-dialog.c b/gcr/gcr-prompt-dialog.c
index 3a053b1..2169929 100644
--- a/gcr/gcr-prompt-dialog.c
+++ b/gcr/gcr-prompt-dialog.c
@@ -33,6 +33,29 @@
#include <gdk/gdkx.h>
#include <glib/gi18n.h>
+/**
+ * SECTION:gcr-prompt-dialog
+ * @title: GcrPromptDialog
+ * @short_description: a GTK+ dialog prompt
+ *
+ * A #GcrPrompt implementation which shows a GTK+ dialog. The dialog will
+ * remain visible (but insensitive) between prompts. Use gtk_widget_hide() to
+ * hide the dialog when appropriate.
+ */
+
+/**
+ * GcrPromptDialog:
+ *
+ * A #GcrPrompt implementation which shows a GTK+ dialog.
+ */
+
+/**
+ * GcrPromptDialogClass:
+ * @parent_class: parent class
+ *
+ * The class for #GcrPromptDialog.
+ */
+
#define LOG_ERRORS 1
#define GRAB_KEYBOARD 1
@@ -163,11 +186,19 @@ gcr_prompt_dialog_set_property (GObject *obj,
case PROP_WARNING:
g_free (self->pv->warning);
self->pv->warning = g_value_dup_string (value);
+ if (self->pv->warning && self->pv->warning[0] == '\0') {
+ g_free (self->pv->warning);
+ self->pv->warning = NULL;
+ }
g_object_notify (obj, "warning");
break;
case PROP_CHOICE_LABEL:
g_free (self->pv->choice_label);
self->pv->choice_label = g_value_dup_string (value);
+ if (self->pv->choice_label && self->pv->choice_label[0] == '\0') {
+ g_free (self->pv->choice_label);
+ self->pv->choice_label = NULL;
+ }
g_object_notify (obj, "choice-label");
break;
case PROP_PASSWORD_NEW:
@@ -176,6 +207,10 @@ gcr_prompt_dialog_set_property (GObject *obj,
case PROP_CALLER_WINDOW:
g_free (self->pv->caller_window);
self->pv->caller_window = g_value_dup_string (value);
+ if (self->pv->caller_window && self->pv->caller_window[0] == '\0') {
+ g_free (self->pv->caller_window);
+ self->pv->caller_window = NULL;
+ }
update_transient_for (self);
g_object_notify (obj, "caller-window");
break;
@@ -683,18 +718,38 @@ gcr_prompt_dialog_class_init (GcrPromptDialogClass *klass)
g_object_class_override_property (gobject_class, PROP_CALLER_WINDOW, "caller-window");
+ /**
+ * GcrPromptDialog:password-visible
+ *
+ * Whether the password entry is visible or not.
+ */
g_object_class_install_property (gobject_class, PROP_PASSWORD_VISIBLE,
g_param_spec_boolean ("password-visible", "Password visible", "Password field is visible",
FALSE, G_PARAM_READABLE));
+ /**
+ * GcrPromptDialog:confirm-visible
+ *
+ * Whether the password confirm entry is visible or not.
+ */
g_object_class_install_property (gobject_class, PROP_CONFIRM_VISIBLE,
g_param_spec_boolean ("confirm-visible", "Confirm visible", "Confirm field is visible",
FALSE, G_PARAM_READABLE));
+ /**
+ * GcrPromptDialog:warning-visible
+ *
+ * Whether the warning label is visible or not.
+ */
g_object_class_install_property (gobject_class, PROP_WARNING_VISIBLE,
g_param_spec_boolean ("warning-visible", "Warning visible", "Warning is visible",
FALSE, G_PARAM_READABLE));
+ /**
+ * GcrPromptDialog:choice-visible
+ *
+ * Whether the choice check box is visible or not.
+ */
g_object_class_install_property (gobject_class, PROP_CHOICE_VISIBLE,
g_param_spec_boolean ("choice-visible", "Choice visible", "Choice is visible",
FALSE, G_PARAM_READABLE));
diff --git a/gcr/gcr-prompt-dialog.h b/gcr/gcr-prompt-dialog.h
index 7f04e59..306fab3 100644
--- a/gcr/gcr-prompt-dialog.h
+++ b/gcr/gcr-prompt-dialog.h
@@ -47,11 +47,13 @@ typedef struct _GcrPromptDialogPrivate GcrPromptDialogPrivate;
struct _GcrPromptDialog {
GtkDialog parent;
+
+ /*< private >*/
GcrPromptDialogPrivate *pv;
};
struct _GcrPromptDialogClass {
- GtkDialogClass parent;
+ GtkDialogClass parent_class;
};
GType gcr_prompt_dialog_get_type (void);
diff --git a/gcr/gcr-prompt.c b/gcr/gcr-prompt.c
index 7fa4c12..df6629b 100644
--- a/gcr/gcr-prompt.c
+++ b/gcr/gcr-prompt.c
@@ -25,6 +25,54 @@
#include "gcr-prompt.h"
+/**
+ * SECTION:gcr-prompt
+ * @title: GcrPrompt
+ * @short_description: a user prompt
+ *
+ * A #GcrPrompt represents a prompt displayed to the user. It is an interface
+ * with various implementations.
+ *
+ * Various properties are set on the prompt, and then the prompt is displayed
+ * the various prompt methods like gcr_prompt_password_run().
+ *
+ * A #GcrPrompt may be used to display multiple related prompts. Most
+ * implemantions do not hide the window between display of multiple related
+ * prompts, and the #GcrPrompt must be closed or destroyed in order to make
+ * it go away. This allows the user to see that the prompts are related.
+ *
+ * Use #GcrPromptDialog to create an in-process GTK+ dialog prompt. Use
+ * #GcrSystemPrompt to create a system prompt in a prompter process.
+ *
+ * The prompt implementation will always display the GcrPrompt:message property,
+ * but may choose not to display the GcrPrompt:description or GcrPrompt:title
+ * properties.
+ */
+
+/**
+ * GcrPrompt:
+ *
+ * Represents a #GcrPrompt displayed to the user.
+ */
+
+/**
+ * GcrPromptIface:
+ * @parent_iface: parent interface
+ * @prompt_password_async: begin a password prompt
+ * @prompt_password_finish: complete a password prompt
+ * @prompt_confirm_async: begin a confirm prompt
+ * @prompt_confirm_finish: complete a confirm prompt
+ *
+ * The interface for implementing #GcrPrompt.
+ */
+
+/**
+ * GcrPromptReply:
+ * @GCR_PROMPT_REPLY_OK: the user replied with 'ok'
+ * @GCR_PROMPT_REPLY_CANCEL: the prompt was cancelled
+ *
+ * Various replies returned by gcr_prompt_confirm() and friends.
+ */
typedef struct {
GAsyncResult *result;
GMainLoop *loop;
@@ -44,38 +92,116 @@ gcr_prompt_default_init (GcrPromptIface *iface)
if (g_once_init_enter (&initialized)) {
+ /**
+ * GcrPrompt:title:
+ *
+ * The title of the prompt.
+ *
+ * A prompt implementation may choose not to display the prompt title. The
+ * #GcrPrompt:message should contain relevant information.
+ */
g_object_interface_install_property (iface,
g_param_spec_string ("title", "Title", "Prompt title",
NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+ /**
+ * GcrPrompt:message:
+ *
+ * The prompt message for the user.
+ *
+ * A prompt implementation should always display this message.
+ */
g_object_interface_install_property (iface,
g_param_spec_string ("message", "Message", "Prompt message",
NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+ /**
+ * GcrPrompt:description:
+ *
+ * The detailed description of the prompt.
+ *
+ * A prompt implementation may choose not to display this detailed description.
+ * The prompt message should contain relevant information.
+ */
g_object_interface_install_property (iface,
g_param_spec_string ("description", "Description", "Prompt description",
NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+ /**
+ * GcrPrompt:warning:
+ *
+ * A prompt warning displayed on the prompt, or %NULL for no warning.
+ *
+ * This is a warning like "The password is incorrect." usually displayed to the
+ * user about a previous 'unsuccessful' prompt.
+ */
g_object_interface_install_property (iface,
g_param_spec_string ("warning", "Warning", "Prompt warning",
NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+ /**
+ * GcrPrompt:password-new:
+ *
+ * Whether the prompt will prompt for a new password.
+ *
+ * This will cause the prompt implementation to ask the user to confirm the
+ * password and/or display other relevant user interface for creating a new
+ * password.
+ */
g_object_interface_install_property (iface,
g_param_spec_boolean ("password-new", "Password new", "Whether prompting for a new password",
FALSE, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+ /**
+ * GcrPrompt:password-strength:
+ *
+ * Indication of the password strength.
+ *
+ * Prompts will return a zero value if the password is empty, and a value
+ * greater than zero if the password has any characters.
+ *
+ * This is only valid after a successful prompt for a password.
+ */
g_object_interface_install_property (iface,
g_param_spec_int ("password-strength", "Password strength", "String of new password",
0, G_MAXINT, 0, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
+ /**
+ * GcrPrompt:choice-label:
+ *
+ * The label for the additional choice.
+ *
+ * If this is a non-%NULL value then an additional boolean choice will be
+ * displayed by the prompt allowing the user to select or deselect it.
+ *
+ * If %NULL, then no additional choice is displayed.
+ *
+ * The initial value of the choice can be set with #GcrPrompt:choice-chosen.
+ */
g_object_interface_install_property (iface,
g_param_spec_string ("choice-label", "Choice label", "Label for prompt choice",
NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+ /**
+ * GcrPrompt:choice-chosen:
+ *
+ * Whether the additional choice is chosen or not.
+ *
+ * The additional choice would have been setup using #GcrPrompt:choice-label.
+ */
g_object_interface_install_property (iface,
g_param_spec_boolean ("choice-chosen", "Choice chosen", "Whether prompt choice is chosen",
FALSE, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+ /**
+ * GcrPrompt:caller-window:
+ *
+ * The string handle of the caller's window.
+ *
+ * The caller window indicates to the prompt which window is prompting the
+ * user. The prompt may choose to ignore this information or use it in whatever
+ * way it sees fit.
+ */
g_object_interface_install_property (iface,
g_param_spec_string ("caller-window", "Caller window", "Window ID of application window requesting prompt",
NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
@@ -123,6 +249,18 @@ on_run_complete (GObject *source,
g_main_loop_quit (closure->loop);
}
+/**
+ * gcr_prompt_get_title:
+ * @prompt: the prompt
+ *
+ * Gets the title of the prompt.
+ *
+ * A prompt implementation may choose not to display the prompt title. The
+ * prompt message should contain relevant information.
+ *
+ * Returns: (transfer full): a newly allocated string containing the prompt
+ * title.
+ */
gchar *
gcr_prompt_get_title (GcrPrompt *prompt)
{
@@ -131,6 +269,16 @@ gcr_prompt_get_title (GcrPrompt *prompt)
return title;
}
+/**
+ * gcr_prompt_set_title:
+ * @prompt: the prompt
+ * @title: the prompt title
+ *
+ * Sets the title of the prompt.
+ *
+ * A prompt implementation may choose not to display the prompt title. The
+ * prompt message should contain relevant information.
+ */
void
gcr_prompt_set_title (GcrPrompt *prompt,
const gchar *title)
@@ -139,6 +287,17 @@ gcr_prompt_set_title (GcrPrompt *prompt,
g_object_set (prompt, "title", title, NULL);
}
+/**
+ * gcr_prompt_get_message:
+ * @prompt: the prompt
+ *
+ * Gets the prompt message for the user.
+ *
+ * A prompt implementation should always display this message.
+ *
+ * Returns: (transfer full): a newly allocated string containing the detailed
+ * description of the prompt
+ */
gchar *
gcr_prompt_get_message (GcrPrompt *prompt)
{
@@ -147,6 +306,15 @@ gcr_prompt_get_message (GcrPrompt *prompt)
return message;
}
+/**
+ * gcr_prompt_set_message:
+ * @prompt: the prompt
+ * @message: the prompt message
+ *
+ * Sets the prompt message for the user.
+ *
+ * A prompt implementation should always display this message.
+ */
void
gcr_prompt_set_message (GcrPrompt *prompt,
const gchar *message)
@@ -155,6 +323,18 @@ gcr_prompt_set_message (GcrPrompt *prompt,
g_object_set (prompt, "message", message, NULL);
}
+/**
+ * gcr_prompt_get_description:
+ * @prompt: the prompt
+ *
+ * Get the detailed description of the prompt.
+ *
+ * A prompt implementation may choose not to display this detailed description.
+ * The prompt message should contain relevant information.
+ *
+ * Returns: (transfer full): a newly allocated string containing the detailed
+ * description of the prompt
+ */
gchar *
gcr_prompt_get_description (GcrPrompt *prompt)
{
@@ -163,6 +343,17 @@ gcr_prompt_get_description (GcrPrompt *prompt)
return description;
}
+/**
+ * gcr_prompt_set_description:
+ * @prompt: the prompt
+ * @description: the detailed description
+ *
+ * Set the detailed description of the prompt.
+ *
+ * A prompt implementation may choose not to display this detailed description.
+ * Use gcr_prompt_set_message() to set a general message containing relevant
+ * information.
+ */
void
gcr_prompt_set_description (GcrPrompt *prompt,
const gchar *description)
@@ -171,6 +362,20 @@ gcr_prompt_set_description (GcrPrompt *prompt,
g_object_set (prompt, "description", description, NULL);
}
+/**
+ * gcr_prompt_get_warning:
+ * @prompt: the prompt
+ *
+ * Get a prompt warning displayed on the prompt.
+ *
+ * This is a warning like "The password is incorrect." usually displayed to the
+ * user about a previous 'unsuccessful' prompt.
+ *
+ * If this string is %NULL then no warning is displayed.
+ *
+ * Returns: (transfer full): a newly allocated string containing the prompt
+ * warning, or %NULL if no warning
+ */
gchar *
gcr_prompt_get_warning (GcrPrompt *prompt)
{
@@ -179,6 +384,18 @@ gcr_prompt_get_warning (GcrPrompt *prompt)
return warning;
}
+/**
+ * gcr_prompt_set_warning:
+ * @prompt: the prompt
+ * @warning: (allow-none): the warning or %NULL
+ *
+ * Set a prompt warning displayed on the prompt.
+ *
+ * This is a warning like "The password is incorrect." usually displayed to the
+ * user about a previous 'unsuccessful' prompt.
+ *
+ * If this string is %NULL then no warning is displayed.
+ */
void
gcr_prompt_set_warning (GcrPrompt *prompt,
const gchar *warning)
@@ -187,6 +404,17 @@ gcr_prompt_set_warning (GcrPrompt *prompt,
g_object_set (prompt, "warning", warning, NULL);
}
+/**
+ * gcr_prompt_get_choice_label:
+ * @prompt: the prompt
+ *
+ * Get the label for the additional choice.
+ *
+ * This will be %NULL if no additional choice is being displayed.
+ *
+ * Returns: (transfer full): a newly allocated string containing the additional
+ * choice or %NULL
+ */
gchar *
gcr_prompt_get_choice_label (GcrPrompt *prompt)
{
@@ -195,6 +423,21 @@ gcr_prompt_get_choice_label (GcrPrompt *prompt)
return choice_label;
}
+/**
+ * gcr_prompt_set_choice_label:
+ * @prompt: the prompt
+ * @choice_label: (allow-none): the additional choice or %NULL
+ *
+ * Set the label for the additional choice.
+ *
+ * If this is a non-%NULL value then an additional boolean choice will be
+ * displayed by the prompt allowing the user to select or deselect it.
+ *
+ * The initial value of the choice can be set with the
+ * gcr_prompt_set_choice_label() method.
+ *
+ * If this is %NULL, then no additional choice is being displayed.
+ */
void
gcr_prompt_set_choice_label (GcrPrompt *prompt,
const gchar *choice_label)
@@ -203,6 +446,17 @@ gcr_prompt_set_choice_label (GcrPrompt *prompt,
g_object_set (prompt, "choice-label", choice_label, NULL);
}
+/**
+ * gcr_prompt_get_choice_chosen:
+ * @prompt: the prompt
+ *
+ * Get whether the additional choice was chosen or not.
+ *
+ * The additional choice would have been setup using
+ * gcr_prompt_set_choice_label().
+ *
+ * Returns: whether chosen
+ */
gboolean
gcr_prompt_get_choice_chosen (GcrPrompt *prompt)
{
@@ -211,6 +465,15 @@ gcr_prompt_get_choice_chosen (GcrPrompt *prompt)
return choice_chosen;
}
+/**
+ * gcr_prompt_set_choice_chosen:
+ * @prompt: the prompt
+ * @chosen: whether chosen
+ *
+ * Set whether the additional choice is chosen or not.
+ *
+ * The additional choice should be set up using gcr_prompt_set_choice_label().
+ */
void
gcr_prompt_set_choice_chosen (GcrPrompt *prompt,
gboolean chosen)
@@ -219,6 +482,18 @@ gcr_prompt_set_choice_chosen (GcrPrompt *prompt,
g_object_set (prompt, "choice-chosen", chosen, NULL);
}
+/**
+ * gcr_prompt_get_password_new:
+ * @prompt: the prompt
+ *
+ * Get whether the prompt will prompt for a new password.
+ *
+ * This will cause the prompt implementation to ask the user to confirm the
+ * password and/or display other relevant user interface for creating a new
+ * password.
+ *
+ * Returns: whether in new password mode or not
+ */
gboolean
gcr_prompt_get_password_new (GcrPrompt *prompt)
{
@@ -227,6 +502,17 @@ gcr_prompt_get_password_new (GcrPrompt *prompt)
return password_new;
}
+/**
+ * gcr_prompt_set_password_new:
+ * @prompt: the prompt
+ * @new_password: whether in new password mode or not
+ *
+ * Set whether the prompt will prompt for a new password.
+ *
+ * This will cause the prompt implementation to ask the user to confirm the
+ * password and/or display other relevant user interface for creating a new
+ * password.
+ */
void
gcr_prompt_set_password_new (GcrPrompt *prompt,
gboolean new_password)
@@ -235,6 +521,19 @@ gcr_prompt_set_password_new (GcrPrompt *prompt,
g_object_set (prompt, "password-new", new_password, NULL);
}
+/**
+ * gcr_prompt_get_password_strength:
+ * @prompt: the prompt
+ *
+ * Get indication of the password strength.
+ *
+ * Prompts will return a zero value if the password is empty, and a value
+ * greater than zero if the password has any characters.
+ *
+ * This is only valid after a successful prompt for a password.
+ *
+ * Returns: zero if the password is empty, greater than zero if not
+ */
gint
gcr_prompt_get_password_strength (GcrPrompt *prompt)
{
@@ -243,6 +542,19 @@ gcr_prompt_get_password_strength (GcrPrompt *prompt)
return password_strength;
}
+/**
+ * gcr_prompt_get_caller_window:
+ * @prompt: the prompt
+ *
+ * Get the string handle of the caller's window.
+ *
+ * The caller window indicates to the prompt which window is prompting the
+ * user. The prompt may choose to ignore this information or use it in whatever
+ * way it sees fit.
+ *
+ * Returns: (transfer full): a newly allocated string containing the string
+ * handle of the window.
+ */
gchar *
gcr_prompt_get_caller_window (GcrPrompt *prompt)
{
@@ -251,6 +563,17 @@ gcr_prompt_get_caller_window (GcrPrompt *prompt)
return caller_window;
}
+/**
+ * gcr_prompt_set_caller_window:
+ * @prompt: the prompt
+ * @window_id: the window id
+ *
+ * Set the string handle of the caller's window.
+ *
+ * The caller window indicates to the prompt which window is prompting the
+ * user. The prompt may choose to ignore this information or use it in whatever
+ * way it sees fit.
+ */
void
gcr_prompt_set_caller_window (GcrPrompt *prompt,
const gchar *window_id)
@@ -259,6 +582,18 @@ gcr_prompt_set_caller_window (GcrPrompt *prompt,
g_object_set (prompt, "caller-window", window_id, NULL);
}
+/**
+ * gcr_prompt_password_async:
+ * @prompt: a prompt
+ * @cancellable: optional cancellation object
+ * @callback: called when the operation completes
+ * @user_data: data to pass to the callback
+ *
+ * Prompts for password. Set the various properties on the prompt before calling
+ * this method to explain which password should be entered.
+ *
+ * This method will return immediately and complete asynchronously.
+ */
void
gcr_prompt_password_async (GcrPrompt *prompt,
GCancellable *cancellable,
@@ -276,6 +611,23 @@ gcr_prompt_password_async (GcrPrompt *prompt,
(iface->prompt_password_async) (prompt, cancellable, callback, user_data);
}
+/**
+ * gcr_prompt_password_finish:
+ * @prompt: a prompt
+ * @result: asynchronous result passed to callback
+ * @error: location to place error on failure
+ *
+ * Complete an operation to prompt for a password.
+ *
+ * A password will be returned if the user enters a password successfully.
+ * The returned password is valid until the next time a method is called
+ * to display another prompt.
+ *
+ * %NULL will be returned if the user cancels or if an error occurs. Check the
+ * @error argument to tell the difference.
+ *
+ * Returns: the password owned by the prompt, or %NULL
+ */
const gchar *
gcr_prompt_password_finish (GcrPrompt *prompt,
GAsyncResult *result,
@@ -293,6 +645,26 @@ gcr_prompt_password_finish (GcrPrompt *prompt,
return (iface->prompt_password_finish) (prompt, result, error);
}
+/**
+ * gcr_prompt_password:
+ * @prompt: a prompt
+ * @cancellable: optional cancellation object
+ * @error: location to place error on failure
+ *
+ * Prompts for password. Set the various properties on the prompt before calling
+ * this method to explain which password should be entered.
+ *
+ * This method will block until the a response is returned from the prompter.
+ *
+ * A password will be returned if the user enters a password successfully.
+ * The returned password is valid until the next time a method is called
+ * to display another prompt.
+ *
+ * %NULL will be returned if the user cancels or if an error occurs. Check the
+ * @error argument to tell the difference.
+ *
+ * Returns: the password owned by the prompt, or %NULL
+ */
const gchar *
gcr_prompt_password (GcrPrompt *prompt,
GCancellable *cancellable,
@@ -317,6 +689,28 @@ gcr_prompt_password (GcrPrompt *prompt,
return reply;
}
+/**
+ * gcr_prompt_password_run:
+ * @prompt: a prompt
+ * @cancellable: optional cancellation object
+ * @error: location to place error on failure
+ *
+ * Prompts for password. Set the various properties on the prompt before calling
+ * this method to explain which password should be entered.
+ *
+ * This method will block until the a response is returned from the prompter
+ * and will run a main loop similar to a gtk_dialog_run(). The application
+ * will remain responsive but care must be taken to handle reentrancy issues.
+ *
+ * A password will be returned if the user enters a password successfully.
+ * The returned password is valid until the next time a method is called
+ * to display another prompt.
+ *
+ * %NULL will be returned if the user cancels or if an error occurs. Check the
+ * @error argument to tell the difference.
+ *
+ * Returns: the password owned by the prompt, or %NULL
+ */
const gchar *
gcr_prompt_password_run (GcrPrompt *prompt,
GCancellable *cancellable,
@@ -341,6 +735,19 @@ gcr_prompt_password_run (GcrPrompt *prompt,
return reply;
}
+/**
+ * gcr_prompt_confirm_async:
+ * @prompt: a prompt
+ * @cancellable: optional cancellation object
+ * @callback: called when the operation completes
+ * @user_data: data to pass to the callback
+ *
+ * Prompts for confirmation asking a cancel/continue style question.
+ * Set the various properties on the prompt before calling this method to
+ * represent the question correctly.
+ *
+ * This method will return immediately and complete asynchronously.
+ */
void
gcr_prompt_confirm_async (GcrPrompt *prompt,
GCancellable *cancellable,
@@ -358,6 +765,20 @@ gcr_prompt_confirm_async (GcrPrompt *prompt,
(iface->prompt_confirm_async) (prompt, cancellable, callback, user_data);
}
+/**
+ * gcr_prompt_confirm_finish:
+ * @prompt: a prompt
+ * @result: asynchronous result passed to callback
+ * @error: location to place error on failure
+ *
+ * Complete an operation to prompt for confirmation.
+ *
+ * %GCR_PROMPT_REPLY_OK will be returned if the user confirms the prompt. The
+ * return value will also be %GCR_PROMPT_REPLY_CANCEL if the user cancels or if
+ * an error occurs. Check the @error argument to tell the difference.
+ *
+ * Returns: the reply from the prompt
+ */
GcrPromptReply
gcr_prompt_confirm_finish (GcrPrompt *prompt,
GAsyncResult *result,
@@ -375,6 +796,24 @@ gcr_prompt_confirm_finish (GcrPrompt *prompt,
return (iface->prompt_confirm_finish) (prompt, result, error);
}
+/**
+ * gcr_prompt_confirm:
+ * @prompt: a prompt
+ * @cancellable: optional cancellation object
+ * @error: location to place error on failure
+ *
+ * Prompts for confirmation asking a cancel/continue style question.
+ * Set the various properties on the prompt before calling this function to
+ * represent the question correctly.
+ *
+ * This method will block until the a response is returned from the prompter.
+ *
+ * %GCR_PROMPT_REPLY_OK will be returned if the user confirms the prompt. The
+ * return value will also be %GCR_PROMPT_REPLY_CANCEL if the user cancels or if
+ * an error occurs. Check the @error argument to tell the difference.
+ *
+ * Returns: the reply from the prompt
+ */
GcrPromptReply
gcr_prompt_confirm (GcrPrompt *prompt,
GCancellable *cancellable,
@@ -400,21 +839,24 @@ gcr_prompt_confirm (GcrPrompt *prompt,
}
/**
- * gcr_system_prompt_confirm:
- * @self: a prompt
+ * gcr_prompt_confirm_run:
+ * @prompt: a prompt
* @cancellable: optional cancellation object
* @error: location to place error on failure
*
* Prompts for confirmation asking a cancel/continue style question.
- * Set the various properties on the prompt to represent the question
- * correctly.
+ * Set the various properties on the prompt before calling this function to
+ * represent the question correctly.
*
- * This method will block until the a response is returned from the prompter.
- * and %TRUE or %FALSE will be returned based on the response. The return value
- * will also be %FALSE if an error occurs. Check the @error argument to tell
- * the difference.
+ * This method will block until the a response is returned from the prompter
+ * and will run a main loop similar to a gtk_dialog_run(). The application
+ * will remain responsive but care must be taken to handle reentrancy issues.
+ *
+ * %GCR_PROMPT_REPLY_OK will be returned if the user confirms the prompt. The
+ * return value will also be %GCR_PROMPT_REPLY_CANCEL if the user cancels or if
+ * an error occurs. Check the @error argument to tell the difference.
*
- * Returns: whether the prompt was confirmed or not
+ * Returns: the reply from the prompt
*/
GcrPromptReply
gcr_prompt_confirm_run (GcrPrompt *prompt,
diff --git a/gcr/gcr-prompt.h b/gcr/gcr-prompt.h
index a115704..5fa0055 100644
--- a/gcr/gcr-prompt.h
+++ b/gcr/gcr-prompt.h
@@ -48,7 +48,7 @@ typedef struct _GcrPrompt GcrPrompt;
typedef struct _GcrPromptIface GcrPromptIface;
struct _GcrPromptIface {
- GTypeInterface parent_class;
+ GTypeInterface parent_iface;
void (* prompt_password_async) (GcrPrompt *prompt,
GCancellable *cancellable,
@@ -94,12 +94,12 @@ void gcr_prompt_set_warning (GcrPrompt *prompt,
gchar * gcr_prompt_get_choice_label (GcrPrompt *prompt);
void gcr_prompt_set_choice_label (GcrPrompt *prompt,
- const gchar *warning);
+ const gchar *choice_label);
gboolean gcr_prompt_get_choice_chosen (GcrPrompt *prompt);
void gcr_prompt_set_choice_chosen (GcrPrompt *prompt,
- gboolean chosen);
+ gboolean chosen);
gboolean gcr_prompt_get_password_new (GcrPrompt *prompt);
diff --git a/gcr/gcr-prompter-tool.c b/gcr/gcr-prompter-tool.c
index 089dc65..3a06d4e 100644
--- a/gcr/gcr-prompter-tool.c
+++ b/gcr/gcr-prompter-tool.c
@@ -115,7 +115,7 @@ main (int argc, char *argv[])
the_prompter = gcr_system_prompter_new (GCR_SYSTEM_PROMPTER_SINGLE,
GCR_TYPE_PROMPT_DIALOG);
owner_id = g_bus_own_name (G_BUS_TYPE_SESSION,
- GCR_DBUS_PROMPTER_BUS_NAME,
+ GCR_DBUS_PROMPTER_SYSTEM_BUS_NAME,
G_BUS_NAME_OWNER_FLAGS_NONE,
on_bus_acquired,
on_name_acquired,
diff --git a/gcr/gcr-secure-entry-buffer.c b/gcr/gcr-secure-entry-buffer.c
index cd9197f..77c9cd4 100644
--- a/gcr/gcr-secure-entry-buffer.c
+++ b/gcr/gcr-secure-entry-buffer.c
@@ -54,6 +54,7 @@
/**
* GcrSecureEntryBufferClass:
+ * @parent_class: parent class
*
* The class for #GcrSecureEntryBuffer.
*/
@@ -79,17 +80,17 @@ gcr_secure_entry_buffer_real_get_text (GtkEntryBuffer *buffer,
{
GcrSecureEntryBuffer *self = GCR_SECURE_ENTRY_BUFFER (buffer);
if (n_bytes)
- *n_bytes = self->priv->text_bytes;
- if (!self->priv->text)
+ *n_bytes = self->pv->text_bytes;
+ if (!self->pv->text)
return "";
- return self->priv->text;
+ return self->pv->text;
}
static guint
gcr_secure_entry_buffer_real_get_length (GtkEntryBuffer *buffer)
{
GcrSecureEntryBuffer *self = GCR_SECURE_ENTRY_BUFFER (buffer);
- return self->priv->text_chars;
+ return self->pv->text_chars;
}
static guint
@@ -99,7 +100,7 @@ gcr_secure_entry_buffer_real_insert_text (GtkEntryBuffer *buffer,
guint n_chars)
{
GcrSecureEntryBuffer *self = GCR_SECURE_ENTRY_BUFFER (buffer);
- GcrSecureEntryBufferPrivate *pv = self->priv;
+ GcrSecureEntryBufferPrivate *pv = self->pv;
gsize n_bytes;
gsize at;
@@ -150,7 +151,7 @@ gcr_secure_entry_buffer_real_delete_text (GtkEntryBuffer *buffer,
guint n_chars)
{
GcrSecureEntryBuffer *self = GCR_SECURE_ENTRY_BUFFER (buffer);
- GcrSecureEntryBufferPrivate *pv = self->priv;
+ GcrSecureEntryBufferPrivate *pv = self->pv;
gsize start, end;
if (position > pv->text_chars)
@@ -176,7 +177,7 @@ static void
gcr_secure_entry_buffer_init (GcrSecureEntryBuffer *self)
{
GcrSecureEntryBufferPrivate *pv;
- pv = self->priv = G_TYPE_INSTANCE_GET_PRIVATE (self, GCR_TYPE_SECURE_ENTRY_BUFFER, GcrSecureEntryBufferPrivate);
+ pv = self->pv = G_TYPE_INSTANCE_GET_PRIVATE (self, GCR_TYPE_SECURE_ENTRY_BUFFER, GcrSecureEntryBufferPrivate);
pv->text = NULL;
pv->text_chars = 0;
@@ -188,7 +189,7 @@ static void
gcr_secure_entry_buffer_finalize (GObject *obj)
{
GcrSecureEntryBuffer *self = GCR_SECURE_ENTRY_BUFFER (obj);
- GcrSecureEntryBufferPrivate *pv = self->priv;
+ GcrSecureEntryBufferPrivate *pv = self->pv;
if (pv->text) {
egg_secure_strfree (pv->text);
diff --git a/gcr/gcr-secure-entry-buffer.h b/gcr/gcr-secure-entry-buffer.h
index d991c48..aa83da1 100644
--- a/gcr/gcr-secure-entry-buffer.h
+++ b/gcr/gcr-secure-entry-buffer.h
@@ -43,10 +43,11 @@ typedef struct _GcrSecureEntryBuffer GcrSecureEntryBuffer;
typedef struct _GcrSecureEntryBufferClass GcrSecureEntryBufferClass;
typedef struct _GcrSecureEntryBufferPrivate GcrSecureEntryBufferPrivate;
-struct _GcrSecureEntryBuffer
-{
+struct _GcrSecureEntryBuffer {
GtkEntryBuffer parent;
- GcrSecureEntryBufferPrivate *priv;
+
+ /*< private >*/
+ GcrSecureEntryBufferPrivate *pv;
};
struct _GcrSecureEntryBufferClass
diff --git a/gcr/gcr-system-prompt.c b/gcr/gcr-system-prompt.c
index fc6f6ba..25ef5f0 100644
--- a/gcr/gcr-system-prompt.c
+++ b/gcr/gcr-system-prompt.c
@@ -40,28 +40,59 @@
/**
* SECTION:gcr-system-prompt
* @title: GcrSystemPrompt
- * @short_description: XXX
+ * @short_description: a system modal prompt
*
- * XXXX
+ * A #GcrPrompt implementation which calls to the system prompter to
+ * display prompts in a system modal fashion.
+ *
+ * Since the system prompter usually only displays one prompt at a time, you
+ * may have to wait for the prompt to be displayed. Use gcr_system_prompt_open()
+ * or a related function to open a prompt. Since this can take a long time, you
+ * should always check that the prompt is still needed after it is opened. A
+ * previous prompt may have already provided the information needed and you
+ * may no longer need to prompt.
+ *
+ * Use gcr_system_prompt_close() to close the prompt when you're done with it.
*/
/**
* GcrSystemPrompt:
*
- * XXX
+ * A #GcrPrompt which shows a system prompt. This is usually a system modal
+ * dialog.
*/
/**
* GcrSystemPromptClass:
+ * @parent_class: parent class
*
* The class for #GcrSystemPrompt.
*/
+/**
+ * GCR_SYSTEM_PROMPT_ERROR:
+ *
+ * The domain for errors returned from GcrSystemPrompt methods.
+ */
+
+/**
+ * GcrSystemPromptError:
+ * @GCR_SYSTEM_PROMPT_IN_PROGRESS: another prompt is already in progress
+ *
+ * No error returned by the #GcrSystemPrompt is suitable for display or
+ * to the user.
+ *
+ * If the system prompter can only show one prompt at a time, and there is
+ * already a prompt being displayed, and the timeout waiting to open the
+ * prompt expires, then %GCR_SYSTEM_PROMPT_IN_PROGRESS is returned.
+ */
+
enum {
PROP_0,
PROP_BUS_NAME,
PROP_SECRET_EXCHANGE,
PROP_TIMEOUT_SECONDS,
+
PROP_TITLE,
PROP_MESSAGE,
PROP_DESCRIPTION,
@@ -139,8 +170,10 @@ gcr_system_prompt_init (GcrSystemPrompt *self)
static const gchar *
prompt_get_string_property (GcrSystemPrompt *self,
- const gchar *property_name)
+ const gchar *property_name,
+ gboolean collapse_empty_to_null)
{
+ const gchar *value = NULL;
GVariant *variant;
gconstpointer key;
@@ -148,10 +181,13 @@ prompt_get_string_property (GcrSystemPrompt *self,
key = g_intern_string (property_name);
variant = g_hash_table_lookup (self->pv->properties, key);
- if (variant != NULL)
- return g_variant_get_string (variant, NULL);
+ if (variant != NULL) {
+ value = g_variant_get_string (variant, NULL);
+ if (collapse_empty_to_null && value != NULL && value[0] == '\0')
+ value = NULL;
+ }
- return NULL;
+ return value;
}
static void
@@ -292,16 +328,16 @@ gcr_system_prompt_get_property (GObject *obj,
g_value_set_object (value, gcr_system_prompt_get_secret_exchange (self));
break;
case PROP_TITLE:
- g_value_set_string (value, prompt_get_string_property (self, "title"));
+ g_value_set_string (value, prompt_get_string_property (self, "title", FALSE));
break;
case PROP_MESSAGE:
- g_value_set_string (value, prompt_get_string_property (self, "message"));
+ g_value_set_string (value, prompt_get_string_property (self, "message", FALSE));
break;
case PROP_DESCRIPTION:
- g_value_set_string (value, prompt_get_string_property (self, "description"));
+ g_value_set_string (value, prompt_get_string_property (self, "description", FALSE));
break;
case PROP_WARNING:
- g_value_set_string (value, prompt_get_string_property (self, "warning"));
+ g_value_set_string (value, prompt_get_string_property (self, "warning", TRUE));
break;
case PROP_PASSWORD_NEW:
g_value_set_boolean (value, prompt_get_boolean_property (self, "password-new"));
@@ -310,13 +346,13 @@ gcr_system_prompt_get_property (GObject *obj,
g_value_set_int (value, prompt_get_int_property (self, "password-strength"));
break;
case PROP_CHOICE_LABEL:
- g_value_set_string (value, prompt_get_string_property (self, "choice-label"));
+ g_value_set_string (value, prompt_get_string_property (self, "choice-label", TRUE));
break;
case PROP_CHOICE_CHOSEN:
g_value_set_boolean (value, prompt_get_boolean_property (self, "choice-chosen"));
break;
case PROP_CALLER_WINDOW:
- g_value_set_string (value, prompt_get_string_property (self, "caller-window"));
+ g_value_set_string (value, prompt_get_string_property (self, "caller-window", TRUE));
break;
default:
G_OBJECT_WARN_INVALID_PROPERTY_ID (obj, prop_id, pspec);
@@ -341,7 +377,7 @@ gcr_system_prompt_constructed (GObject *obj)
self->pv->prompt_path = g_strdup_printf ("%s/p%d", GCR_DBUS_PROMPT_OBJECT_PREFIX, seed);
if (self->pv->prompter_bus_name == NULL)
- self->pv->prompter_bus_name = g_strdup (GCR_DBUS_PROMPTER_BUS_NAME);
+ self->pv->prompter_bus_name = g_strdup (GCR_DBUS_PROMPTER_SYSTEM_BUS_NAME);
}
static void
@@ -386,14 +422,31 @@ gcr_system_prompt_class_init (GcrSystemPromptClass *klass)
g_type_class_add_private (gobject_class, sizeof (GcrSystemPromptPrivate));
+ /**
+ * GcrSystemPrompt:bus-name
+ *
+ * The DBus bus name of the prompter to use for prompting, or %NULL
+ * for the default prompter.
+ */
g_object_class_install_property (gobject_class, PROP_BUS_NAME,
g_param_spec_string ("bus-name", "Bus name", "Prompter bus name",
NULL, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
+ /**
+ * GcrSystemPrompt:timeout-seconds
+ *
+ * The timeout in seconds to wait when opening the prompt.
+ */
g_object_class_install_property (gobject_class, PROP_TIMEOUT_SECONDS,
g_param_spec_int ("timeout-seconds", "Timeout seconds", "Timeout (in seconds) for opening prompt",
-1, G_MAXINT, -1, G_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY));
+ /**
+ * GcrSystemPrompt:secret-exchange
+ *
+ * The #GcrSecretExchange to use when transferring passwords. A default
+ * secret exchange will be used if this is not set.
+ */
g_object_class_install_property (gobject_class, PROP_SECRET_EXCHANGE,
g_param_spec_object ("secret-exchange", "Secret exchange", "Secret exchange for passing passwords",
GCR_TYPE_SECRET_EXCHANGE, G_PARAM_READWRITE));
@@ -958,23 +1011,23 @@ perform_prompt_async (GcrSystemPrompt *self,
g_free (sent);
}
-static GcrSystemPromptResponse
+static GcrPromptReply
handle_last_response (GcrSystemPrompt *self)
{
- GcrSystemPromptResponse response;
+ GcrPromptReply response;
g_return_val_if_fail (self->pv->last_response != NULL,
- GCR_SYSTEM_PROMPT_CANCEL);
+ GCR_PROMPT_REPLY_CANCEL);
if (g_str_equal (self->pv->last_response, GCR_DBUS_PROMPT_REPLY_YES)) {
- response = GCR_SYSTEM_PROMPT_OK;
+ response = GCR_PROMPT_REPLY_OK;
} else if (g_str_equal (self->pv->last_response, GCR_DBUS_PROMPT_REPLY_NO)) {
- response = GCR_SYSTEM_PROMPT_CANCEL;
+ response = GCR_PROMPT_REPLY_CANCEL;
} else {
g_warning ("unknown response from prompter: %s", self->pv->last_response);
- response = GCR_SYSTEM_PROMPT_CANCEL;
+ response = GCR_PROMPT_REPLY_CANCEL;
}
return response;
@@ -1007,7 +1060,7 @@ gcr_system_prompt_password_finish (GcrPrompt *prompt,
if (g_simple_async_result_propagate_error (res, error))
return FALSE;
- if (handle_last_response (self) == GCR_SYSTEM_PROMPT_OK)
+ if (handle_last_response (self) == GCR_PROMPT_REPLY_OK)
return gcr_secret_exchange_get_secret (self->pv->exchange, NULL);
return NULL;
@@ -1234,10 +1287,20 @@ gcr_system_prompt_open_for_prompter (const gchar *prompter_name,
/**
* gcr_system_prompt_close:
* @self: the prompt
+ * @cancellable: an optional cancellation object
+ * @error: location to place an error on failure
*
- * Close this prompt. After closing the prompt, no further methods may be
+ * Close this prompt. After calling this function, no further methods may be
* called on this object. The prompt object is not unreferenced by this
* function, and you must unreference it once done.
+ *
+ * This call may block, use the gcr_system_prompt_close_async() to perform
+ * this action indefinitely.
+ *
+ * Whether or not this function returns %TRUE, the system prompt object is
+ * still closed and may not be further used.
+ *
+ * Returns: whether close was cleanly completed
*/
gboolean
gcr_system_prompt_close (GcrSystemPrompt *self,
@@ -1285,6 +1348,19 @@ on_prompter_stop_prompting (GObject *source,
g_object_unref (res);
}
+/**
+ * gcr_system_prompt_close_async:
+ * @self: the prompt
+ * @cancellable: an optional cancellation object
+ * @callback: called when the operation completes
+ * @user_data: data to pass to the callback
+ *
+ * Close this prompt asynchronously. After calling this function, no further
+ * methods may be called on this object. The prompt object is not unreferenced
+ * by this function, and you must unreference it once done.
+ *
+ * This call returns immediately and completes asynchronously.
+ */
void
gcr_system_prompt_close_async (GcrSystemPrompt *self,
GCancellable *cancellable,
@@ -1355,6 +1431,19 @@ gcr_system_prompt_close_async (GcrSystemPrompt *self,
g_object_unref (res);
}
+/**
+ * gcr_system_prompt_close_finish:
+ * @self: the prompt
+ * @result: asynchronous operation result
+ * @error: location to place an error on failure
+ *
+ * Complete operation to close this prompt.
+ *
+ * Whether or not this function returns %TRUE, the system prompt object is
+ * still closed and may not be further used.
+ *
+ * Returns: whether close was cleanly completed
+ */
gboolean
gcr_system_prompt_close_finish (GcrSystemPrompt *self,
GAsyncResult *result,
@@ -1374,7 +1463,6 @@ gcr_system_prompt_close_finish (GcrSystemPrompt *self,
static const GDBusErrorEntry SYSTEM_PROMPT_ERRORS[] = {
{ GCR_SYSTEM_PROMPT_IN_PROGRESS, GCR_DBUS_PROMPT_ERROR_IN_PROGRESS },
- { GCR_SYSTEM_PROMPT_FAILED, GCR_DBUS_PROMPT_ERROR_FAILED },
};
GQuark
@@ -1385,6 +1473,6 @@ gcr_system_prompt_error_get_domain (void)
&quark_volatile,
SYSTEM_PROMPT_ERRORS,
G_N_ELEMENTS (SYSTEM_PROMPT_ERRORS));
- G_STATIC_ASSERT (G_N_ELEMENTS (SYSTEM_PROMPT_ERRORS) == GCR_SYSTEM_PROMPT_FAILED);
+ G_STATIC_ASSERT (G_N_ELEMENTS (SYSTEM_PROMPT_ERRORS) == GCR_SYSTEM_PROMPT_IN_PROGRESS);
return (GQuark) quark_volatile;
}
diff --git a/gcr/gcr-system-prompt.h b/gcr/gcr-system-prompt.h
index 4bd154b..b7c4e7b 100644
--- a/gcr/gcr-system-prompt.h
+++ b/gcr/gcr-system-prompt.h
@@ -36,14 +36,7 @@
G_BEGIN_DECLS
typedef enum {
- GCR_SYSTEM_PROMPT_CANCEL = 0,
- GCR_SYSTEM_PROMPT_OK = 1,
-} GcrSystemPromptResponse;
-
-typedef enum {
GCR_SYSTEM_PROMPT_IN_PROGRESS = 1,
- GCR_SYSTEM_PROMPT_FAILED,
- GCR_SYSTEM_PROMPT_CLOSED
} GcrSystemPromptError;
#define GCR_SYSTEM_PROMPT_ERROR (gcr_system_prompt_error_get_domain ())
@@ -63,13 +56,13 @@ typedef struct _GcrSystemPromptPrivate GcrSystemPromptPrivate;
struct _GcrSystemPrompt {
GObject parent;
+
+ /*< private >*/
GcrSystemPromptPrivate *pv;
};
struct _GcrSystemPromptClass {
GObjectClass parent_class;
-
- void (*prompt_ready) ();
};
GType gcr_system_prompt_get_type (void);
diff --git a/gcr/gcr-system-prompter.c b/gcr/gcr-system-prompter.c
index 278c41f..0441ed3 100644
--- a/gcr/gcr-system-prompter.c
+++ b/gcr/gcr-system-prompter.c
@@ -42,23 +42,39 @@
/**
* SECTION:gcr-system-prompter
* @title: GcrSystemPrompter
- * @short_description: XXX
+ * @short_description: a prompter which displays system prompts
*
- * XXXX
+ * This is a DBus service which is rarely implemented. Use #GcrSystemPrompt
+ * to display system prompts.
+ *
+ * The GcrSystemPrompter service responds to dbus requests to create system
+ * prompts and creates #GcrPrompt type objects to display those prompts.
+ *
+ * Pass the GType of the implementation of #GcrPrompt to gcr_system_prompter_new().
*/
/**
* GcrSystemPrompter:
*
- * XXX
+ * A prompter used by implementations of system prompts.
*/
/**
* GcrSystemPrompterClass:
+ * @parent_class: prompter class
*
* The class for #GcrSystemPrompter.
*/
+/**
+ * GcrSystemPrompterMode:
+ * @GCR_SYSTEM_PROMPTER_SINGLE: only one prompt shown at a time
+ * @GCR_SYSTEM_PROMPTER_MULTIPLE: more than one prompt shown at a time
+ *
+ * The mode for the system prompter. Most system prompters can only show
+ * one prompt at a time and would use the %GCR_SYSTEM_PROMPTER_SINGLE mode.
+ */
+
enum {
PROP_0,
PROP_MODE,
@@ -268,11 +284,25 @@ gcr_system_prompter_class_init (GcrSystemPrompterClass *klass)
g_type_class_add_private (gobject_class, sizeof (GcrSystemPrompterPrivate));
+ /**
+ * GcrSystemPrompter:mode:
+ *
+ * The mode for this prompter.
+ *
+ * Most system prompters only display one prompt at a time and therefore
+ * return %GCR_SYSTEM_PROMPTER_SINGLE.
+ */
g_object_class_install_property (gobject_class, PROP_MODE,
g_param_spec_enum ("mode", "Mode", "Prompting mode",
GCR_TYPE_SYSTEM_PROMPTER_MODE, GCR_SYSTEM_PROMPTER_SINGLE,
G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
+ /**
+ * GcrSystemPrompter:prompt-type:
+ *
+ * The #GType for prompts created by this prompter. This must be a
+ * #GcrPrompt implementation.
+ */
g_object_class_install_property (gobject_class, PROP_PROMPT_TYPE,
g_param_spec_gtype ("prompt-type", "Prompt GType", "GObject type of prompts",
GCR_TYPE_PROMPT,
@@ -722,6 +752,17 @@ static GDBusInterfaceVTable prompter_dbus_vtable = {
prompter_set_property,
};
+/**
+ * gcr_system_prompter_register:
+ * @self: the system prompter
+ * @connection: a DBus connection
+ *
+ * Register this system prompter on the DBus @connection.
+ *
+ * This makes the prompter available for clients to call. The prompter will
+ * remain registered until gcr_system_prompter_unregister() is called, or the
+ * prompter is unreferenced.
+ */
void
gcr_system_prompter_register (GcrSystemPrompter *self,
GDBusConnection *connection)
@@ -748,6 +789,18 @@ gcr_system_prompter_register (GcrSystemPrompter *self,
}
}
+/**
+ * gcr_system_prompter_unregister:
+ * @self: the system prompter
+ * @wait: whether to wait for closing prompts
+ *
+ * Unregister this system prompter on the DBus @connection.
+ *
+ * The prompter must have previously been registered with gcr_system_prompter_register().
+ *
+ * If @wait is set then this function will wait until all prompts have been closed
+ * or cancelled. This is usually only used by tests.
+ */
void
gcr_system_prompter_unregister (GcrSystemPrompter *self,
gboolean wait)
@@ -815,10 +868,14 @@ gcr_system_prompter_unregister (GcrSystemPrompter *self,
/**
* gcr_system_prompter_new:
+ * @mode: the mode for the prompt
+ * @prompt_type: the gobject type for prompts created by this prompter
*
* Create a new system prompter service. This prompter won't do anything unless
* you connect to its signals and show appropriate prompts.
*
+ * The @prompt_type #GType must implement the #GcrPrompt interface.
+ *
* Returns: (transfer full): a new prompter service
*/
GcrSystemPrompter *
@@ -831,6 +888,17 @@ gcr_system_prompter_new (GcrSystemPrompterMode mode,
NULL);
}
+/**
+ * gcr_system_prompter_get_mode:
+ * @self: the prompter
+ *
+ * Get the mode for this prompter.
+ *
+ * Most system prompters only display one prompt at a time and therefore
+ * return %GCR_SYSTEM_PROMPTER_SINGLE.
+ *
+ * Returns: the prompter mode
+ */
GcrSystemPrompterMode
gcr_system_prompter_get_mode (GcrSystemPrompter *self)
{
@@ -838,6 +906,16 @@ gcr_system_prompter_get_mode (GcrSystemPrompter *self)
return self->pv->mode;
}
+/**
+ * gcr_system_prompter_get_prompt_type:
+ * @self: the prompter
+ *
+ * Get the #GType for prompts created by this prompter.
+ *
+ * The returned #GType will be a #GcrPrompt implementation.
+ *
+ * Returns: the prompt #GType
+ */
GType
gcr_system_prompter_get_prompt_type (GcrSystemPrompter *self)
{
diff --git a/gcr/gcr-system-prompter.h b/gcr/gcr-system-prompter.h
index 8549924..57ae481 100644
--- a/gcr/gcr-system-prompter.h
+++ b/gcr/gcr-system-prompter.h
@@ -53,6 +53,8 @@ typedef struct _GcrSystemPrompterPrivate GcrSystemPrompterPrivate;
struct _GcrSystemPrompter {
GObject parent;
+
+ /*< private >*/
GcrSystemPrompterPrivate *pv;
};
@@ -69,10 +71,6 @@ GcrSystemPrompterMode gcr_system_prompter_get_mode (GcrSystemPro
GType gcr_system_prompter_get_prompt_type (GcrSystemPrompter *self);
-gint gcr_system_prompter_get_showing (GcrSystemPrompter *self);
-
-void gcr_system_prompter_stop_all (GcrSystemPrompter *self);
-
void gcr_system_prompter_register (GcrSystemPrompter *self,
GDBusConnection *connection);
diff --git a/gcr/gcr-viewer-widget.c b/gcr/gcr-viewer-widget.c
index df59a2c..d8204e0 100644
--- a/gcr/gcr-viewer-widget.c
+++ b/gcr/gcr-viewer-widget.c
@@ -532,6 +532,15 @@ gcr_viewer_widget_get_parser (GcrViewerWidget *self)
return self->pv->parser;
}
+/**
+ * gcr_viewer_widget_show_error:
+ * @self: a viewer widget
+ * @message: descriptive error message
+ * @error: (allow-none): detailed error
+ *
+ * Show an error on the viewer widget. This is displayed on a info bar near
+ * the edge of the widget.
+ */
void
gcr_viewer_widget_show_error (GcrViewerWidget *self,
const gchar *message,
@@ -553,6 +562,12 @@ gcr_viewer_widget_show_error (GcrViewerWidget *self,
g_free (markup);
}
+/**
+ * gcr_viewer_widget_clear_error:
+ * @self: a viewer widget
+ *
+ * Clear the error displayed on the viewer widget.
+ */
void
gcr_viewer_widget_clear_error (GcrViewerWidget *self)
{
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
