From a7f5c9f6c58c76a375bd0f00efedca0e582b2021 Mon Sep 17 00:00:00 2001 From: JezerM Date: Sat, 26 Jun 2021 21:38:02 -0600 Subject: [PATCH] Added API documentation --- README.md | 6 +- docs/Battery.md | 19 ++++ docs/Greeter.md | 222 ++++++++++++++++++++++++++++++++++++++++++ docs/GreeterConfig.md | 53 ++++++++++ docs/Language.md | 18 ++++ docs/Layout.md | 18 ++++ docs/Session.md | 23 +++++ docs/ThemeUtils.md | 39 ++++++++ docs/User.md | 43 ++++++++ 9 files changed, 440 insertions(+), 1 deletion(-) create mode 100644 docs/Battery.md create mode 100644 docs/Greeter.md create mode 100644 docs/GreeterConfig.md create mode 100644 docs/Language.md create mode 100644 docs/Layout.md create mode 100644 docs/Session.md create mode 100644 docs/ThemeUtils.md create mode 100644 docs/User.md diff --git a/README.md b/README.md index 4c202b3..63c38f1 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,9 @@ sudo make install ``` ## Theme Javascript API -[Antergos][Antergos] documentation is no longer available. Although, you can see the man-pages `man web-greeter` for some documentation and explanation. Also, you can explore the provided [themes](./themes) for real use cases. +[Antergos][Antergos] documentation is no longer available, although it is accesible through [Web Archive][WebArchive]. Actual documentation is available in [Gitbook][ApiDoc]. + +You can access the man-pages `man web-greeter` for some documentation and explanation. Also, you can explore the provided [themes][./themes] for real use cases. ## Enable features ### Brightness control @@ -57,3 +59,5 @@ web-greeter --debug [antergos]: https://github.com/Antergos "Antergos" [whither]: https://github.com/JezerM/whither "Whither" [acpilight]: https://gitlab.com/wavexx/acpilight "acpilight" +[WebArchive]: https://web.archive.org/web/20190524032923/https://doclets.io/Antergos/web-greeter/stable "Web Archive" +[ApiDoc]: https://amyuki4.gitbook.io/web-greeter/ "API Documentation" diff --git a/docs/Battery.md b/docs/Battery.md new file mode 100644 index 0000000..e22110a --- /dev/null +++ b/docs/Battery.md @@ -0,0 +1,19 @@ +Interface for object that holds info about battery. Battery object is not created by the theme's code, but rather by the **LightDM.Greeter** class. + +# Members + +## level +**Type**: [String] + +The battery level. + +## name +**Type**: [String] + +The battery's name. + +## state +**Type**: [String] + +The state for the battery. + diff --git a/docs/Greeter.md b/docs/Greeter.md new file mode 100644 index 0000000..c887fdf --- /dev/null +++ b/docs/Greeter.md @@ -0,0 +1,222 @@ +Base class for the greeter's Theme JavaScript 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` + +# Methods + +## authenticate(username) +Starts the authentication with the given `username`. +**Arguments**: +- `username` [String] + +## authenticate_as_guest() +Authenticates as the guest user. + +## batteryUpdate() +Updates the battery data. + +## brightnessSet(quantity) +Set the brightness to `quantity`. + +## brightnessIncrease(quantity) +Increase the brightness by `quantity` + +## brightnessDecrease(quantity) +Decrease the brightness by `quantity` + +## cancel_authentication() +Cancel the user authentication that is currently in progress. + +## cancel_autologin() +Cancels the automatic login. + +## get_hint(name) +Get the value of a hint. + +**Arguments**: +- `name` [String] + +**Returns**: +- [String | Boolean | Number | Null] + +## hibernate() +Triggers the system to hibernate. + +**Returns**: +- [Boolean] + `true` if hibernation initiated, otherwise `false` + +## layout(value) +Set the active layout for the selected user. + +**Arguments**: +- `value` [LightDM.layout] + +## respond(response) +Provide a response to a greeter + +**Arguments**: +- `response` [String] + +## restart() +Triggers the system to restart. + +**Returns**: +- [Boolean] + `true` if restart initiated, otherwise `false` + +## set_language(language) +Set the language for the currently authenticated user. + +**Arguments**: +- language [String] + The language specification (e.g 'de\_DE.UTF-8') + +**Returns**: +- Boolean + `true` if successful, otherwise `false` + +## shutdown() +Triggers the system to shutdown. + +**Returns**: +- Boolean + `true` if successful, otherwise `false` + +## start_session(session) +Starts a session for the authenticated user. + +**Arguments**: +- `session` [String | Null] + The session to log into or null to use the default + +**Returns**: +- Boolean + `true` if successful, otherwise `false` + +## suspend() +Triggers the system to suspend/sleep. + +**Returns** +- [Boolean] + `true` if suspend/sleep initiated, otherwise `false` + +# Members + +## authentication_user +**Type**: [String | Null] + +The username of the user being authenticated or null if there is no authentication in progress. + +## autologin_guest +**Type**: [Boolean] + +Whether or not the guest account should be automatically logged into when the timer expires. + +## autologin_timeout +**Type**: [Number] + +The number of seconds to wait before automatically loggin in. + +## autologin_user +**Type**: [Boolean] + +The username with which to automatically log in when the timer expires. + +## can_hibernate +**Type**: [Boolean] + +Whether or not the greeter can make the system hibernate. + +## can_restart +**Type**: [Boolean] + +Whether or not the greeter can make the system restart. + +## can_shutdown +**Type**: [Boolean] + +Whether or not the greeter can make the system shutdown. + +## can_suspend +**Type**: [Boolean] + +Whether or not the greeter can make the system suspend/sleep. + +## default_session +**Type**: [String] + +The name of the default session + +## has_guest_account +**Type**: [Boolean] + +Whether or not guest sessions are supported + +## hide_users +**Type**: [Boolean] + +Whether or not user accounts should be hidden + +## hostname +**Type**: [String] + +The system's hostname + +## in_authentication +**Type**: [Boolean] + +Whether or not the greeter is in the process of authenticating. + +## is_authenticated +**Type**: [Boolean] + +Whether or not the greeter has succesfully authenticated. + +## language +**Type**: [LightDM.Language | Null] + +The current language or `null` if no language. + +## languages +**Type**: [Array<LightDM.Language>] + +A list of languages to present to the user. + +## layout +**Type**: [LightDM.Layout] + +The currently active layout for the selected user. + +## layouts +**Type**: [Array<LightDM.Layout>] + +A list of keyboard layouts to present to the user. + +## lock_hint +**Type**: [Boolean] + +Whether or not the greeter was started as a lock screen. + +## num_users +**Type**: [Number] + +The number of users able to log in + +## select_guest_hint +**Type**: [Boolean] + +Whether or not the guest account should be selected by default + +## select_user_hint +**Type**: [String] + +The username to select by default. + +## sessions +**Type**: [String] + +List of available sessions. + +## users +**Type**: [Array<LightDM.User>] + +List of available users. diff --git a/docs/GreeterConfig.md b/docs/GreeterConfig.md new file mode 100644 index 0000000..2171314 --- /dev/null +++ b/docs/GreeterConfig.md @@ -0,0 +1,53 @@ +Provides greeter themes with a way to access values from the greeter's config file located at **/etc/lightdm/web-greeter.yml**. The greeter will create an instance of this class when it starts. The instance can be accessed with the global variable: `greeter_config` + +# Members + +## branding +**Type**: [Object] + +Holds keys&values from the **branding** section of the config file. + +**Properties**: +- **background_images_dir** + Path to directory that contains background images for use in greeter themes. +- **logo_image** + Path to distro logo image for use in greeter themes +- **user_image** + Default user image/avatar. + +## greeter +**Type**: [Object] + +Holds keys/values from the **greeter** section of the config file. + +**Properties**: +- **debug_mode** + Greeter theme debug mode. +- **detect_theme_errors** + Provide an option to load default theme when theme errors are detected. +- **screensaver_timeout** + Blank the screen after this seconds of inactivity. +- **secure_mode** + Don't allow themes to make http requests. +- **time_format** + A moment.js format string to be used by the greeter to generate localized time for display. +- **time_language** + Language to use when displaying the time, or **auto** to use the system's language. +- **theme** + The name of the theme to be used by the greeter. + +## features +**Type**: [Object] + +Holds keys/values from the **features** section of the config file. + +**Properties**: +- **battery** + Enable greeter and themes to get battery status. +- **backlight** + - **enabled** + Enable greeter and themes to control display backlight. + - **value** + The amount to increase/decrease brightness by greeter. + - **steps** + How many steps are needed to do the change. **0** for instant change diff --git a/docs/Language.md b/docs/Language.md new file mode 100644 index 0000000..289e370 --- /dev/null +++ b/docs/Language.md @@ -0,0 +1,18 @@ +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 **LightDM.Greeter** class. + +# Members + +## code +**Type**: [String] + +The code for the language. + +## name +**Type**: [String] + +The name for the layout. + +## territory +**Type**: [String] + +The territory for the language. diff --git a/docs/Layout.md b/docs/Layout.md new file mode 100644 index 0000000..c7b2107 --- /dev/null +++ b/docs/Layout.md @@ -0,0 +1,18 @@ +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 **LightDM.Greeter** class. + +# Members + +## description +**Type**: [String] + +The description for the layout. + +## name +**Type**: [String] + +The name for the layout. + +## short_description +**Type**: [String] + +The territory for the layout. diff --git a/docs/Session.md b/docs/Session.md new file mode 100644 index 0000000..8e90809 --- /dev/null +++ b/docs/Session.md @@ -0,0 +1,23 @@ +Interface for object that holds info about a session. Session objects are not created by the theme's code, but rather by the **LightDM.Greeter** class. + +# Members + +## comment +**Type**: [String] + +The comment for the session. + +## key +**Type**: [String] + +The key for the session. + +## name +**Type**: [String] + +The name for the session. + +## Type +**Type**: [String] + +The type for the sesion. diff --git a/docs/ThemeUtils.md b/docs/ThemeUtils.md new file mode 100644 index 0000000..abc4fb1 --- /dev/null +++ b/docs/ThemeUtils.md @@ -0,0 +1,39 @@ +Provides various utility methods for use in greeter themes. The greeter will automatically create an instance of this class when it starts. The instance can be accessed with the global variable: `theme_utils` + +# Methods + +## bind_this(context) +Bind **this** to class, **context**, for all of the class's methods. + +**Arguments**: +- `context` [Object] + An ES6 class instance with at least one method. + +**Returns**: +- Object + **context** with **this** bound to it for all of its methods. + +## dirlist(path) +Returns the contents of a directory found at **path**, only if the **path** meets at least one of the following conditions: +- Is located whithin the greeter theme's root directory. +- Has been explicitly allowed in the greeter's config file. +- Is located within the greeter's shared data directory (**/var/lib/lightdm-data/**) +- Is located in **/tmp**. + +**Arguments**: +- `path` [String] + The abs path to desired directory. + +**Returns**: +- Array<String> + List of abs paths for the files and directories found in **path** + +## get_current_localized_time() +Get the current time in a localized format. Time format and language are auto-detected by default, but can be set manually in the greeter config file. +- **language** defaults to the system's language, but can be set manually in the config gile. +- When **time_format** config file option has a valid value, time will be formatted according to that value. +- When **time_format** does not have a valid value, the time format will be **LT** which is **1:00 PM** or **13:00** depending on the system's locale. + +**Returns**: +- String + The current localized time. diff --git a/docs/User.md b/docs/User.md new file mode 100644 index 0000000..4a0793a --- /dev/null +++ b/docs/User.md @@ -0,0 +1,43 @@ +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 **LightDM.Greeter** class. + +# Members + +## display_name +**Type**: [String] + +The display name for the user. + +## home_directory +**Type**: [String] + +The home directory for the user. + +## image +**Type**: [String] + +The image for the user. + +## language +**Type**: [String] + +The language for the user. + +## layout +**Type**: [String] + +The keyboard layout for the user. + +## logged_in +**Type**: [Boolean] + +Whether or not the user is currently logged in. + +## session +**Type**: [String] + +The last session that the user logged into. + +## username +**Type**: [String] + +The username for the user.