prepping theme api documentation for upcoming release

.doclets.yml

@@ -1,4 +1,6 @@
-files:
+dir: src/gresource/js
-  - themes/_vendor/js/mock.js
 articles:
   - Overview: README.md
+branches:
+  - master
+  - stable

src/greeter.c

@@ -208,6 +208,7 @@ load_script(char *script) {
 static void
 greeter_loaded_handler(void) {
 	load_script(GRESOURCE_PATH "/js/_vendor/moment-with-locales.min.js");
+	load_script(GRESOURCE_PATH "/js/Greeter.js");
 	load_script(GRESOURCE_PATH "/js/GreeterConfig.js");
 	load_script(GRESOURCE_PATH "/js/ThemeUtils.js");
 	load_script(GRESOURCE_PATH "/js/ThemeHeartbeat.js");

src/gresource/greeter-resources.gresource.xml

@@ -3,6 +3,8 @@
 	<gresource prefix="/com/antergos/lightdm-webkit2-greeter/">
 		<file>css/style.css</file>
 		<file>js/_vendor/moment-with-locales.min.js</file>
+		<file>js/LightDMObjects.js</file>
+		<file>js/Greeter.js</file>
 		<file>js/GreeterConfig.js</file>
 		<file>js/ThemeHeartbeat.js</file>
 		<file>js/ThemeUtils.js</file>

src/gresource/js/Greeter.js

@@ -0,0 +1,308 @@
+/*
+ * LightDMGreeter.js
+ *
+ * Copyright © 2016 Antergos Developers <dev@antergos.com>
+ *
+ * This file is part of lightdm-webkit2-greeter.
+ *
+ * lightdm-webkit2-greeter is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * lightdm-webkit2-greeter is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * The following additional terms are in effect as per Section 7 of the license:
+ *
+ * The preservation of all legal notices and author attributions in
+ * the material or in the Appropriate Legal Notices displayed
+ * by works containing it is required.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with lightdm-webkit2-greeter; If not, see <http://www.gnu.org/licenses/>.
+ */
+
+
+/**
+ * Base class for the greeter's JavaScript Theme API. Greeter themes will interact
+ * directly with an object derived from this class to facilitate the user log-in process.
+ * The greeter will automatically create an instance when it starts.
+ * The instance can be accessed using the global variable: `lightdm`.
+ *
+ * @memberOf LightDM
+ */
+class Greeter {
+
+	constructor() {
+		if ( 'lightdm' in window ) {
+			return window.lightdm;
+		}
+
+		window.lightdm = GreeterUtils.bind_this( this );
+
+		return window.lightdm;
+	}
+
+	/**
+	 * The username of the user being authenticated or {@link null}
+	 * if there is no authentication in progress.
+	 * @type {String|null}
+	 * @readonly
+	 */
+	get authentication_user() {}
+
+	/**
+	 * Whether or not the guest account should be automatically logged
+	 * into when the timer expires.
+	 * @type {Boolean}
+	 * @readonly
+	 */
+	get autologin_guest() {}
+
+	/**
+	 * The number of seconds to wait before automatically logging in.
+	 * @type {Number}
+	 * @readonly
+	 */
+	get autologin_timeout() {}
+
+	/**
+	 * The username with which to automatically log in when the timer expires.
+	 * @type {String}
+	 * @readonly
+	 */
+	get autologin_user() {}
+
+	/**
+	 * Whether or not the greeter can make the system hibernate.
+	 * @type {Boolean}
+	 * @readonly
+	 */
+	get can_hibernate() {}
+
+	/**
+	 * Whether or not the greeter can make the system restart.
+	 * @type {Boolean}
+	 * @readonly
+	 */
+	get can_restart() {}
+
+	/**
+	 * Whether or not the greeter can make the system shutdown.
+	 * @type {Boolean}
+	 * @readonly
+	 */
+	get can_shutdown() {}
+
+	/**
+	 * Whether or not the greeter can make the system suspend/sleep.
+	 * @type {Boolean}
+	 * @readonly
+	 */
+	get can_suspend() {}
+
+	/**
+	 * The name of the default session.
+	 * @type {String}
+	 * @readonly
+	 */
+	get default_session() {}
+
+	/**
+	 * Whether or not guest sessions are supported.
+	 * @type {Boolean}
+	 * @readonly
+	 */
+	get has_guest_account() {}
+
+	/**
+	 * Whether or not user accounts should be hidden.
+	 * @type {Boolean}
+	 * @readonly
+	 */
+	get hide_users() {}
+
+	/**
+	 * The system's hostname.
+	 * @type {String}
+	 * @readonly
+	 */
+	get hostname() {}
+
+	/**
+	 * Whether or not the greeter is in the process of authenticating.
+	 * @type {Boolean}
+	 * @readonly
+	 */
+	get in_authentication() {}
+
+	/**
+	 * Whether or not the greeter has successfully authenticated.
+	 * @type {Boolean}
+	 * @readonly
+	 */
+	get is_authenticated() {}
+
+	/**
+	 * The current language or {@link null} if no language.
+	 * @type {LightDMLanguage|null}
+	 * @readonly
+	 */
+	get language() {}
+
+	/**
+	 * A list of languages to present to the user.
+	 * @type {LightDMLanguage[]}
+	 * @readonly
+	 */
+	get languages() {}
+
+	/**
+	 * The currently active layout for the selected user.
+	 * @type {LightDMLayout}
+	 */
+	get layout() {}
+	set layout( value ) {}
+
+	/**
+	 * A list of keyboard layouts to present to the user.
+	 * @type {LightDMLayout[]}
+	 * @readonly
+	 */
+	get layouts() {}
+
+	/**
+	 * Whether or not the greeter was started as a lock screen.
+	 * @type {Boolean}
+	 * @readonly
+	 */
+	get lock_hint() {}
+
+	/**
+	 * The number of users able to log in.
+	 * @type {Number}
+	 * @readonly
+	 */
+	get num_users() {
+		return this.users.length;
+	}
+
+	/**
+	 * Whether or not the guest account should be selected by default.
+	 * @type {Boolean}
+	 * @readonly
+	 */
+	get select_guest_hint() {}
+
+	/**
+	 * The username to select by default.
+	 * @type {String}
+	 * @readonly
+	 */
+	get select_user_hint() {}
+
+	/**
+	 * List of available sessions.
+	 * @type {LightDMSession[]}
+	 * @readonly
+	 */
+	get sessions() {}
+
+	/**
+	 * List of available users.
+	 * @type {LightDMUser[]}
+	 * @readonly
+	 */
+	get users() {}
+
+
+	/**
+	 * Starts the authentication procedure for a user.
+	 *
+	 * @arg {String|null} username A username or {@link null} to prompt for a username.
+	 */
+	authenticate( username = null ) {}
+
+	/**
+	 * Starts the authentication procedure for the guest user.
+	 */
+	authenticate_as_guest() {}
+
+	/**
+	 * Cancel the user authentication that is currently in progress.
+	 */
+	cancel_authentication() {}
+
+	/**
+	 * Cancel the automatic login.
+	 */
+	cancel_autologin() {}
+
+	/**
+	 * Get the value of a hint.
+	 * @arg {String} name The name of the hint to get.
+	 * @returns {String|Boolean|Number|null}
+	 */
+	get_hint( name ) {}
+
+	/**
+	 * Triggers the system to hibernate.
+	 * @returns {Boolean} {@link true} if hibernation initiated, otherwise {@link false}
+	 */
+	hibernate() {
+		return this._do_mocked_system_action('hibernate');
+	}
+
+	/**
+	 * Provide a response to a prompt.
+	 * @arg {*} response
+	 */
+	respond( response ) {}
+
+	/**
+	 * Triggers the system to restart.
+	 * @returns {Boolean} {@link true} if restart initiated, otherwise {@link false}
+	 */
+	restart() {
+		return this._do_mocked_system_action('restart');
+	}
+
+	/**
+	 * Set the language for the currently authenticated user.
+	 * @arg {String} language The language in the form of a locale specification (e.g. 'de_DE.UTF-8')
+	 * @returns {Boolean} {@link true} if successful, otherwise {@link false}
+	 */
+	set_language( language ) {}
+
+	/**
+	 * Triggers the system to shutdown.
+	 * @returns {Boolean} {@link true} if shutdown initiated, otherwise {@link false}
+	 */
+	shutdown() {}
+
+	/**
+	 * Start a session for the authenticated user.
+	 * @arg {String|null} session The session to log into or {@link null} to use the default.
+	 * @returns {Boolean} {@link true} if successful, otherwise {@link false}
+	 */
+	start_session( session ) {}
+
+	/**
+	 * Triggers the system to suspend/sleep.
+	 * @returns {Boolean} {@link true} if suspend/sleep initiated, otherwise {@link false}
+	 */
+	suspend() {}
+
+}
+
+
+/**
+ * @memberOf window
+ * @type {LightDM.Greeter}
+ */
+window.lightdm = __LightDMGreeter;
+
+

src/gresource/js/GreeterConfig.js

@@ -25,7 +25,9 @@
  * along with lightdm-webkit2-greeter; If not, see <http://www.gnu.org/licenses/>.
  */
 
-
+/**
+ * @namespace LightDM
+ */
 
 /**
  * Provides theme authors with a way to retrieve values from the greeter's config
@@ -98,6 +100,11 @@ class GreeterConfig  {
 	get_str( key ) {}
 }
 
+
+/**
+ * @memberOf window
+ * @type {LightDM.GreeterConfig}
+ */
 window.greeter_config = __GreeterConfig;
 
 /* -------->>> DEPRECATED! <<<-------- */

src/gresource/js/LightDMObjects.js

@@ -0,0 +1,204 @@
+/*
+ * Copyright © 2015-2016 Antergos
+ *
+ * LightDMObjects.js
+ *
+ * This file is part of lightdm-webkit2-greeter
+ *
+ * lightdm-webkit2-greeter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License,
+ * or any later version.
+ *
+ * lightdm-webkit2-greeter is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * The following additional terms are in effect as per Section 7 of the license:
+ *
+ * The preservation of all legal notices and author attributions in
+ * the material or in the Appropriate Legal Notices displayed
+ * by works containing it is required.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+/**
+ * @namespace LightDM
+ */
+
+/**
+ * Interface for object that holds info about a session. Session objects are not
+ * created by the theme's code, but rather by the {@link LightDMGreeter} class.
+ * @memberOf LightDM
+ */
+class LightDMSession  {
+	constructor(  { comment, key, name } ) {
+		/**
+		 * The comment for the session.
+		 * @type {String}
+		 * @readonly
+		 */
+		this.comment = comment;
+
+		/**
+		 * The key for the session.
+		 * @type {String}
+		 * @readonly
+		 */
+		this.key = key;
+
+		/**
+		 * The name for the session.
+		 * @type {String}
+		 * @readonly
+		 */
+		this.name = name;
+	}
+}
+
+
+/**
+ * Interface for object that holds info about a language on the system. Language objects are not
+ * created by the theme's code, but rather by the {@link LightDMGreeter} class.
+ * @memberOf LightDM
+ */
+class LightDMLanguage {
+	constructor(  { code, name, territory } ) {
+		/**
+		 * The code for the language.
+		 * @type {String}
+		 * @readonly
+		 */
+		this.code = code;
+
+		/**
+		 * The name for the language.
+		 * @type {String}
+		 * @readonly
+		 */
+		this.name = name;
+
+		/**
+		 * The territory for the language.
+		 * @type {String}
+		 * @readonly
+		 */
+		this.territory = territory;
+	}
+}
+
+
+/**
+ * Interface for object that holds info about a keyboard layout on the system. Language
+ * objects are not created by the theme's code, but rather by the {@link LightDMGreeter} class.
+ * @memberOf LightDM
+ */
+class LightDMLayout {
+	constructor(  { description, name, short_description } ) {
+		/**
+		 * The description for the layout.
+		 * @type {String}
+		 * @readonly
+		 */
+		this.description = description;
+
+		/**
+		 * The name for the layout.
+		 * @type {String}
+		 * @readonly
+		 */
+		this.name = name;
+
+		/**
+		 * The territory for the layout.
+		 * @type {String}
+		 * @readonly
+		 */
+		this.short_description = short_description;
+	}
+}
+
+
+/**
+ * Interface for object that holds info about a user account on the system. User
+ * objects are not created by the theme's code, but rather by the {@link LightDMGreeter} class.
+ * @memberOf LightDM
+ */
+class LightDMUser {
+	constructor( user_info ) {
+		/**
+		 * The display name for the user.
+		 * @type {String}
+		 * @readonly
+		 */
+		this.display_name = user_info.display_name;
+
+		/**
+		 * The language for the user.
+		 * @type {String}
+		 * @readonly
+		 */
+		this.language = user_info.language;
+
+		/**
+		 * The keyboard layout for the user.
+		 * @type {String}
+		 * @readonly
+		 */
+		this.layout = user_info.layout;
+
+		/**
+		 * The image for the user.
+		 * @type {String}
+		 * @readonly
+		 */
+		this.image = user_info.image;
+
+		/**
+		 * The home_directory for the user.
+		 * @type {String}
+		 * @readonly
+		 */
+		this.home_directory = user_info.home_directory;
+
+		/**
+		 * The username for the user.
+		 * @type {String}
+		 * @readonly
+		 */
+		this.username = user_info.username;
+
+		/**
+		 * Whether or not the user is currently logged in.
+		 * @type {Boolean}
+		 * @readonly
+		 */
+		this.logged_in = user_info.logged_in;
+
+		/**
+		 * The last session that the user logged into.
+		 * @type {String|null}
+		 * @readonly
+		 */
+		this.session = user_info.session;
+
+		/**
+		 * DEPRECATED!
+		 * @deprecated See {@link LightDMUser.username}.
+		 * @type {String}
+		 * @readonly
+		 */
+		this.name = user_info.name;
+
+		/**
+		 * DEPRECATED!
+		 * @deprecated See {@link LightDMUser.display_name}.
+		 * @type {String}
+		 * @readonly
+		 */
+		this.real_name = user_info.real_name;
+	}
+}

src/gresource/js/ThemeUtils.js

@@ -25,7 +25,9 @@
  * along with lightdm-webkit2-greeter; If not, see <http://www.gnu.org/licenses/>.
  */
 
-
+/**
+ * @namespace LightDM
+ */
 
 /**
  * Provides various utility methods for use by theme authors. The greeter will automatically
@@ -67,6 +69,11 @@ class ThemeUtils  {
 	}
 }
 
+
+/**
+ * @memberOf window
+ * @type {LightDM.ThemeUtils}
+ */
 window.theme_utils = __ThemeUtils;
 window.theme_utils.bind_this = ThemeUtils.bind_this;
 

src/webkit2-extension.c

@@ -1541,7 +1541,7 @@ static const JSClassDefinition lightdm_session_definition = {
 static const JSClassDefinition lightdm_greeter_definition = {
 	0,                         /* Version          */
 	kJSClassAttributeNone,     /* Attributes       */
-	"LightDMGreeter",          /* Class name       */
+	"__LightDMGreeter",          /* Class name       */
 	NULL,                      /* Parent class     */
 	lightdm_greeter_values,    /* Static values    */
 	lightdm_greeter_functions, /* Static functions */
@@ -1614,7 +1614,7 @@ window_object_cleared_callback(WebKitScriptWorld *world,
 	lightdm_greeter_object = JSObjectMake(jsContext, lightdm_greeter_class, greeter);
 	JSObjectSetProperty(jsContext,
 						globalObject,
-						JSStringCreateWithUTF8CString("lightdm"),
+						JSStringCreateWithUTF8CString("__LightDMGreeter"),
 						lightdm_greeter_object,
 						kJSPropertyAttributeNone,
 						NULL);