Improve liblightdm-gobject documentation

5 files changed, 75 insertions, 48 deletions

diff --git a/doc/lightdm-gobject-0-sections.txt b/doc/lightdm-gobject-0-sections.txt
index 7e6145d2..2c5814be 100644
--- a/doc/lightdm-gobject-0-sections.txt
+++ b/doc/lightdm-gobject-0-sections.txt
@@ -88,6 +88,8 @@ ldm_session_new
 <SECTION>
 <FILE>greeter</FILE>
 <TITLE>LdmGreeter</TITLE>
+LdmMessageType
+LdmPromptType
 ldm_greeter_new
 ldm_greeter_connect_to_server
 ldm_greeter_get_hostname
diff --git a/doc/tmpl/greeter.sgml b/doc/tmpl/greeter.sgml
index baf237a0..33d9172e 100644
--- a/doc/tmpl/greeter.sgml
+++ b/doc/tmpl/greeter.sgml
@@ -9,45 +9,58 @@ Manages connection to LightDM server and provides greeter functionality
 #LdmGreeter is an object that manages the connection to the LightDM server and provides common greeter functionality.
 </para>
 <para>
-To connect to the display manager instanciate a #LdmGreeter object from inside the greeter process:
 <example>
-<title>Connecting to the display manager</title>
+<title>Example Greeter</title>
 <programlisting><![CDATA[
-LdmGreeter *greeter = ldm_greeter_new ();
-if (!ldm_greeter_connect (LDM_GREETER (greeter))) {
-    // Log an error
-    exit (0);
+int main ()
+{
+    LdmGreeter *greeter = ldm_greeter_new ();
+
+    g_object_connect (greeter, "connected", G_CALLBACK (connected_cb), NULL);
+    g_object_connect (greeter, "show-prompt", G_CALLBACK (show_prompt_cb), NULL);
+    g_object_connect (greeter, "authentication-complete", G_CALLBACK (authentication_complete_cb), NULL);
+    g_object_connect (greeter, "session-failed", G_CALLBACK (session_failed_cb), NULL);
+    g_object_connect (greeter, "quit", G_CALLBACK (quit_cb), NULL);
+
+    if (!ldm_greeter_connect_to_server (LDM_GREETER (greeter))) {
+        // Log an error
+        return 0;
+    }
 }
-]]></programlisting>
-</example>
-Information on how to connect to the display manager is passed using environment variables.
-</para>
-<para>
-Once connected, start an authentication conversation like this:
-<example>
-<title>Example Authorization Conversation</title>
-<programlisting><![CDATA[
-static void show_prompt_cb (LdmGreeter *greeter, const char *text)
+
+static void connected_cb (LdmGreeter *greeter)
+{
+    // Start authentication
+    ldm_greeter_login_with_user_prompt (greeter);
+}
+
+static void show_prompt_cb (LdmGreeter *greeter, const char *text, LdmPromptType type)
 {
     // Show the user the message and prompt for some response
-    gchar *secret = prompt_user (text);
+    gchar *secret = prompt_user (text, type);
 
     // Give the result to the user
-    ldm_greeter_respond (greeter, secret);
+    ldm_greeter_respond (greeter, response);
 }
 
 static void authentication_complete_cb (LdmGreeter *greeter)
 {
     if (ldm_greeter_get_is_authenticated (greeter)) {
-        // Log in to this session.
-        ldm_greeter_login (greeter, ldm_greeter_get_authentication_user (greeter), ldm_greeter_get_default_session (greeter));
+        // Start the user session
+        ldm_greeter_start_default_session (greeter);
     }
     else {
         // Display a warning and reset the greeter
-        reset_login_screen ();
+        reset_login_screen (``Incorrect password, please try again'');
     }
 }
 
+static void session_failed_cb (LdmGreeter *greeter)
+{
+    // Display a warning and reset the greeter
+    reset_login_screen (``Failed to login'');
+}
+
 static void quit_cb (LdmGreeter *greeter)
 {
     // Clean up
@@ -55,10 +68,6 @@ static void quit_cb (LdmGreeter *greeter)
     
     exit (0);
 }
-
-g_object_connect (G_OBJECT (greeter), "show-prompt", G_CALLBACK (show_prompt_cb), NULL);
-g_object_connect (G_OBJECT (greeter), "authentication-complete", G_CALLBACK (authentication_complete_cb), NULL);
-g_object_connect (G_OBJECT (greeter), "quit", G_CALLBACK (quit_cb), NULL);
 ]]></programlisting>
 </example>
 </para>
@@ -74,6 +83,22 @@ g_object_connect (G_OBJECT (greeter), "quit", G_CALLBACK (quit_cb), NULL);
 <!-- ##### SECTION Image ##### -->
 
 
+<!-- ##### ENUM LdmMessageType ##### -->
+<para>
+
+</para>
+
+@LDM_MESSAGE_TYPE_INFO: 
+@LDM_MESSAGE_TYPE_ERROR: 
+
+<!-- ##### ENUM LdmPromptType ##### -->
+<para>
+
+</para>
+
+@LDM_PROMPT_TYPE_QUESTION: 
+@LDM_PROMPT_TYPE_SECRET: 
+
 <!-- ##### FUNCTION ldm_greeter_new ##### -->
 <para>
 
diff --git a/liblightdm-gobject/greeter.c b/liblightdm-gobject/greeter.c
index 3089adfc..636bba1c 100644
--- a/liblightdm-gobject/greeter.c
+++ b/liblightdm-gobject/greeter.c
@@ -493,7 +493,7 @@ from_server_cb (GIOChannel *source, GIOCondition condition, gpointer data)
  *
  * Connects the greeter to the display manager.
  *
- * Return value: TRUE if successfully connected
+ * Return value: #TRUE if successfully connected
  **/
 gboolean
 ldm_greeter_connect_to_server (LdmGreeter *greeter)
@@ -839,7 +839,7 @@ ldm_greeter_get_users (LdmGreeter *greeter)
  * @greeter: A #LdmGreeter
  * @username: Name of user to get.
  *
- * Get infomation about a given user or NULL if this user doesn't exist.
+ * Get infomation about a given user or #NULL if this user doesn't exist.
  *
  * Return value: (transfer none): A #LdmUser entry for the given user.
  **/
@@ -1154,7 +1154,7 @@ ldm_greeter_get_sessions (LdmGreeter *greeter)
  *
  * Get a hint.
  *
- * Return value: The value for this hint or NULL if not set.
+ * Return value: The value for this hint or #NULL if not set.
  **/
 const gchar *
 ldm_greeter_get_hint (LdmGreeter *greeter, const gchar *name)
@@ -1184,7 +1184,7 @@ ldm_greeter_get_default_session_hint (LdmGreeter *greeter)
  *
  * Check if user accounts should be shown.
  *
- * Return value: TRUE if the available users should not be shown.
+ * Return value: #TRUE if the available users should not be shown.
  */
 gboolean
 ldm_greeter_get_hide_users_hint (LdmGreeter *greeter)
@@ -1203,7 +1203,7 @@ ldm_greeter_get_hide_users_hint (LdmGreeter *greeter)
  *
  * Check if guest sessions are supported.
  *
- * Return value: TRUE if guest sessions are supported.
+ * Return value: #TRUE if guest sessions are supported.
  */
 gboolean
 ldm_greeter_get_has_guest_account_hint (LdmGreeter *greeter)
@@ -1237,7 +1237,7 @@ ldm_greeter_get_select_user_hint (LdmGreeter *greeter)
  *
  * Check if the guest account should be selected by default.
  *
- * Return value: TRUE if the guest account should be selected by default.
+ * Return value: #TRUE if the guest account should be selected by default.
  */
 gboolean
 ldm_greeter_get_select_guest_hint (LdmGreeter *greeter)
@@ -1271,7 +1271,7 @@ ldm_greeter_get_autologin_user_hint (LdmGreeter *greeter)
  *
  * Check if the guest account should be automatically logged into when the timer expires.
  *
- * Return value: TRUE if the guest account should be automatically logged into.
+ * Return value: #TRUE if the guest account should be automatically logged into.
  */
 gboolean
 ldm_greeter_get_autologin_guest_hint (LdmGreeter *greeter)
@@ -1331,7 +1331,7 @@ ldm_greeter_cancel_timed_login (LdmGreeter *greeter)
 /**
  * ldm_greeter_login:
  * @greeter: A #LdmGreeter
- * @username: (allow-none): A username or NULL to prompt for a username.
+ * @username: (allow-none): A username or #NULL to prompt for a username.
  *
  * Starts the authentication procedure for a user.
  **/
@@ -1455,7 +1455,7 @@ ldm_greeter_cancel_authentication (LdmGreeter *greeter)
  *
  * Checks if the greeter is in the process of authenticating.
  *
- * Return value: TRUE if the greeter is authenticating a user.
+ * Return value: #TRUE if the greeter is authenticating a user.
  **/
 gboolean
 ldm_greeter_get_in_authentication (LdmGreeter *greeter)
@@ -1470,7 +1470,7 @@ ldm_greeter_get_in_authentication (LdmGreeter *greeter)
  *
  * Checks if the greeter has successfully authenticated.
  *
- * Return value: TRUE if the greeter is authenticated for login.
+ * Return value: #TRUE if the greeter is authenticated for login.
  **/
 gboolean
 ldm_greeter_get_is_authenticated (LdmGreeter *greeter)
@@ -1485,7 +1485,7 @@ ldm_greeter_get_is_authenticated (LdmGreeter *greeter)
  *
  * Get the user that is being authenticated.
  *
- * Return value: The username of the authentication user being authenticated or NULL if no authentication in progress.
+ * Return value: The username of the authentication user being authenticated or #NULL if no authentication in progress.
  */
 const gchar *
 ldm_greeter_get_authentication_user (LdmGreeter *greeter)
@@ -1497,7 +1497,7 @@ ldm_greeter_get_authentication_user (LdmGreeter *greeter)
 /**
  * ldm_greeter_start_session:
  * @greeter: A #LdmGreeter
- * @session: (allow-none): The session to log into or NULL to use the default
+ * @session: (allow-none): The session to log into or #NULL to use the default
  *
  * Start a session for the logged in user.
  **/
@@ -1577,7 +1577,7 @@ upower_call_function (LdmGreeter *greeter, const gchar *function, gboolean has_r
  *
  * Checks if the greeter is authorized to do a system suspend.
  *
- * Return value: TRUE if the greeter can suspend the system
+ * Return value: #TRUE if the greeter can suspend the system
  **/
 gboolean
 ldm_greeter_get_can_suspend (LdmGreeter *greeter)
@@ -1605,7 +1605,7 @@ ldm_greeter_suspend (LdmGreeter *greeter)
  *
  * Checks if the greeter is authorized to do a system hibernate.
  *
- * Return value: TRUE if the greeter can hibernate the system
+ * Return value: #TRUE if the greeter can hibernate the system
  **/
 gboolean
 ldm_greeter_get_can_hibernate (LdmGreeter *greeter)
@@ -1674,7 +1674,7 @@ ck_call_function (LdmGreeter *greeter, const gchar *function, gboolean has_resul
  *
  * Checks if the greeter is authorized to do a system restart.
  *
- * Return value: TRUE if the greeter can restart the system
+ * Return value: #TRUE if the greeter can restart the system
  **/
 gboolean
 ldm_greeter_get_can_restart (LdmGreeter *greeter)
@@ -1702,7 +1702,7 @@ ldm_greeter_restart (LdmGreeter *greeter)
  *
  * Checks if the greeter is authorized to do a system shutdown.
  *
- * Return value: TRUE if the greeter can shutdown the system
+ * Return value: #TRUE if the greeter can shutdown the system
  **/
 gboolean
 ldm_greeter_get_can_shutdown (LdmGreeter *greeter)
diff --git a/liblightdm-gobject/language.c b/liblightdm-gobject/language.c
index 09f8534a..a7598580 100644
--- a/liblightdm-gobject/language.c
+++ b/liblightdm-gobject/language.c
@@ -138,7 +138,7 @@ is_utf8 (const gchar *code)
  * 
  * Check if a language code matches this language.
  * 
- * Return value: TRUE if the code matches this language.
+ * Return value: #TRUE if the code matches this language.
  **/
 gboolean
 ldm_language_matches (LdmLanguage *language, const gchar *code)
diff --git a/liblightdm-gobject/user.c b/liblightdm-gobject/user.c
index ef450002..7da0547d 100644
--- a/liblightdm-gobject/user.c
+++ b/liblightdm-gobject/user.c
@@ -54,7 +54,7 @@ G_DEFINE_TYPE (LdmUser, ldm_user, G_TYPE_OBJECT);
  * @real_name: The real name of the user
  * @home_directory: The home directory of the user
  * @image: The image URI
- * @logged_in: TRUE if this user is currently logged in
+ * @logged_in: #TRUE if this user is currently logged in
  * 
  * Return value: the new #LdmUser
  **/
@@ -195,7 +195,7 @@ ldm_user_set_home_directory (LdmUser *user, const gchar *home_directory)
  * 
  * Get the image URI for a user.
  * 
- * Return value: The image URI for the given user or NULL if no URI
+ * Return value: The image URI for the given user or #NULL if no URI
  **/
 const gchar *
 ldm_user_get_image (LdmUser *user)
@@ -246,7 +246,7 @@ load_dmrc (LdmUser *user)
  * 
  * Get the language for a user.
  * 
- * Return value: The language for the given user or NULL if using system defaults.
+ * Return value: The language for the given user or #NULL if using system defaults.
  **/
 const gchar *
 ldm_user_get_language (LdmUser *user)
@@ -262,7 +262,7 @@ ldm_user_get_language (LdmUser *user)
  * 
  * Get the keyboard layout for a user.
  * 
- * Return value: The keyboard layoyt for the given user or NULL if using system defaults.
+ * Return value: The keyboard layoyt for the given user or #NULL if using system defaults.
  **/
 const gchar *
 ldm_user_get_layout (LdmUser *user)
@@ -278,7 +278,7 @@ ldm_user_get_layout (LdmUser *user)
  * 
  * Get the session for a user.
  * 
- * Return value: The session for the given user or NULL if using system defaults.
+ * Return value: The session for the given user or #NULL if using system defaults.
  **/
 const gchar *
 ldm_user_get_session (LdmUser *user)
@@ -294,7 +294,7 @@ ldm_user_get_session (LdmUser *user)
  * 
  * Check if a user is logged in.
  * 
- * Return value: TRUE if the user is currently logged in.
+ * Return value: #TRUE if the user is currently logged in.
  **/
 gboolean
 ldm_user_get_logged_in (LdmUser *user)