From ebfb5ce0233d34fb8052a465d1df6a79236c4e4c Mon Sep 17 00:00:00 2001 From: Dustin Falgout Date: Mon, 31 Oct 2016 22:11:33 -0500 Subject: [PATCH] prepping theme api documentation for upcoming release --- .doclets.yml | 6 +- src/greeter.c | 1 + src/gresource/greeter-resources.gresource.xml | 2 + src/gresource/js/Greeter.js | 308 ++++++++++++++++++ src/gresource/js/GreeterConfig.js | 9 +- src/gresource/js/LightDMObjects.js | 204 ++++++++++++ src/gresource/js/ThemeUtils.js | 9 +- src/webkit2-extension.c | 4 +- 8 files changed, 537 insertions(+), 6 deletions(-) create mode 100644 src/gresource/js/Greeter.js create mode 100644 src/gresource/js/LightDMObjects.js diff --git a/.doclets.yml b/.doclets.yml index 048b0c2..a1624e6 100644 --- a/.doclets.yml +++ b/.doclets.yml @@ -1,4 +1,6 @@ -files: - - themes/_vendor/js/mock.js +dir: src/gresource/js articles: - Overview: README.md +branches: + - master + - stable diff --git a/src/greeter.c b/src/greeter.c index f4c3072..13ce687 100644 --- a/src/greeter.c +++ b/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"); diff --git a/src/gresource/greeter-resources.gresource.xml b/src/gresource/greeter-resources.gresource.xml index 5f84eb0..4a1279f 100644 --- a/src/gresource/greeter-resources.gresource.xml +++ b/src/gresource/greeter-resources.gresource.xml @@ -3,6 +3,8 @@ css/style.css js/_vendor/moment-with-locales.min.js + js/LightDMObjects.js + js/Greeter.js js/GreeterConfig.js js/ThemeHeartbeat.js js/ThemeUtils.js diff --git a/src/gresource/js/Greeter.js b/src/gresource/js/Greeter.js new file mode 100644 index 0000000..2ee5549 --- /dev/null +++ b/src/gresource/js/Greeter.js @@ -0,0 +1,308 @@ +/* + * LightDMGreeter.js + * + * Copyright © 2016 Antergos Developers + * + * 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 . + */ + + +/** + * 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; + + diff --git a/src/gresource/js/GreeterConfig.js b/src/gresource/js/GreeterConfig.js index 71d09f6..1aaa5dd 100644 --- a/src/gresource/js/GreeterConfig.js +++ b/src/gresource/js/GreeterConfig.js @@ -25,7 +25,9 @@ * along with lightdm-webkit2-greeter; If not, see . */ - +/** + * @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! <<<-------- */ diff --git a/src/gresource/js/LightDMObjects.js b/src/gresource/js/LightDMObjects.js new file mode 100644 index 0000000..ac913a9 --- /dev/null +++ b/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 . + */ + +/** + * @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; + } +} diff --git a/src/gresource/js/ThemeUtils.js b/src/gresource/js/ThemeUtils.js index 438c202..0869c60 100644 --- a/src/gresource/js/ThemeUtils.js +++ b/src/gresource/js/ThemeUtils.js @@ -25,7 +25,9 @@ * along with lightdm-webkit2-greeter; If not, see . */ - +/** + * @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; diff --git a/src/webkit2-extension.c b/src/webkit2-extension.c index 1ab76c0..a105cba 100644 --- a/src/webkit2-extension.c +++ b/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);