Skip to content

Commit e21057c

Browse files
KonerDevKonerDev
authored
Merge pull request #19 from KonerDev/docs/restructure
feat: add more documentation
2 parents a3d6348 + 837fe01 commit e21057c

18 files changed

Lines changed: 1213 additions & 122 deletions

‎.vitepress/config.mjs‎

Lines changed: 63 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,67 @@
1-
import { defineConfig } from 'vitepress'
1+
import { defineConfig } from 'vitepress';
22

33
// https://vitepress.dev/reference/site-config
44
export default defineConfig({
5-
base: '/Xed-Docs/',
6-
title: "Xed-Docs",
7-
description: "Documentation of Xed-Editor",
8-
ignoreDeadLinks: [
9-
/^https?:\/\/localhost/,
10-
],
11-
themeConfig: {
12-
search: {
13-
provider: 'local'
14-
},
15-
// https://vitepress.dev/reference/default-theme-config
16-
nav: [
17-
{ text: 'Home', link: '/' },
18-
],
19-
sidebar: {
20-
"/docs/extensions/":[
21-
{
22-
text: 'Getting Started',
23-
items: [
24-
{ text: 'Introduction', link: '/docs/extensions/' },
25-
{ text: 'Environment Setup', link: '/docs/extensions/build-setup' },
26-
{ text: "Manifest File", link: '/docs/extensions/manifest-file' },
27-
{ text: 'Lifecycle Hooks', link: '/docs/extensions/lifecycle-hooks' },
28-
{ text: 'Publishing Extension', link: '/docs/extensions/publishing' },
29-
]
30-
}
31-
],
32-
"/docs/lsp/":[
33-
{
34-
items: [
35-
{ text: 'Introduction', link: '/docs/lsp/' },
36-
{ text: 'Builtin Servers', link: '/docs/lsp/builtin-servers' },
37-
{ text: 'External Servers', link: '/docs/lsp/external-servers' },
38-
{ text: 'Report Issues', link: '/docs/lsp/report-issues' },
39-
]
40-
}
41-
],
42-
},
5+
base: '/docs/',
6+
title: 'Xed-Docs',
7+
description: 'Documentation of Xed-Editor',
8+
ignoreDeadLinks: [/^https?:\/\/localhost/],
9+
themeConfig: {
10+
search: {
11+
provider: 'local',
12+
},
13+
// https://vitepress.dev/reference/default-theme-config
14+
sidebar: [
15+
{
16+
text: 'Getting Started',
17+
items: [
18+
{ text: 'Download', link: '/docs/download' },
19+
{ text: 'Quick Start', link: '/docs/quick-start' },
20+
{ text: 'Editor Overview', link: '/docs/editor-overview' },
21+
],
22+
},
23+
{
24+
text: 'User Guide',
25+
items: [
26+
{ text: 'Terminal', link: '/docs/terminal/' },
27+
{ text: 'Runners', link: '/docs/runners/' },
28+
{ text: 'Git Integration', link: '/docs/git/' },
29+
{
30+
text: 'Language Servers',
31+
items: [
32+
{ text: 'Introduction', link: '/docs/lsp/' },
33+
{ text: 'Builtin Servers', link: '/docs/lsp/builtin-servers' },
34+
{ text: 'External Servers', link: '/docs/lsp/external-servers' },
35+
{ text: 'Report Issues', link: '/docs/lsp/report-issues' },
36+
],
37+
},
38+
],
39+
},
40+
{
41+
text: 'Developer Guide',
42+
items: [
43+
{
44+
text: 'Extension Development',
45+
items: [
46+
{ text: 'Introduction', link: '/docs/extensions/' },
47+
{ text: 'Environment Setup', link: '/docs/extensions/build-setup' },
48+
{ text: 'Manifest File', link: '/docs/extensions/manifest-file' },
49+
{ text: 'Lifecycle Hooks', link: '/docs/extensions/lifecycle-hooks' },
50+
{ text: 'Entry class & Context', link: '/docs/extensions/entry-context' },
51+
{ text: 'Settings', link: '/docs/extensions/settings' },
52+
{ text: 'Publishing Extension', link: '/docs/extensions/publishing' },
53+
],
54+
},
55+
{ text: 'Themes', link: '/docs/themes/' },
56+
{ text: 'Icon Packs', link: '/docs/icon-packs/' },
57+
],
58+
},
59+
],
4360

44-
socialLinks: [
45-
{ icon: 'github', link: 'https://github.com/Xed-Editor/Xed-Editor' },
46-
{ icon: 'discord', link: 'https://discord.gg/6bKzcQRuef' },
47-
{ icon: 'telegram', link: 'https://t.me/XedEditor' },
48-
]
49-
}
50-
})
61+
socialLinks: [
62+
{ icon: 'github', link: 'https://github.com/Xed-Editor/Xed-Editor' },
63+
{ icon: 'discord', link: 'https://discord.gg/6bKzcQRuef' },
64+
{ icon: 'telegram', link: 'https://t.me/XedEditor' },
65+
],
66+
},
67+
});

‎docs/editor-overview.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Editor Overview

‎docs/extensions/build-setup.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,4 +56,4 @@ After a successful build, the extension package is a compressed file located in
5656
output/YourExtensionName.zip
5757
```
5858

59-
This `.zip` file contains all necessary code and metadata. You can install it directly in the **Xed-Editor** application using the `Install from storage` button.
59+
This `.zip` file contains all necessary code and metadata. You can install it directly in the Xed-Editor application using **`Settings > Extensions > Install from storage`**.

‎docs/extensions/entry-context.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
title: Extension Entry Class & Runtime Requirements
3+
navTitle: Entry Class
4+
---
5+
6+
# Entry Class and Extension Context
7+
8+
Every Xed-Editor extension is executed through a single entry class, usually named `Main`. This is
9+
the class that you previously specified in the [manifest](/docs/extensions/manifest-file.md).
10+
11+
This class is the runtime bridge between your extension and the host system.
12+
13+
## Role of the Entry Class
14+
15+
The entry class serves as the starting point for your extension. It defines all lifecycle callbacks,
16+
as you learned on the previous page.
17+
18+
Furthermore, it has access to the extension context and much more, which we will cover later.
19+
20+
It is instantiated by Xed-Editor when the extension is loaded.
21+
22+
## Required Structure
23+
24+
```kotlin
25+
@Keep // [!code focus:3]
26+
@Suppress("unused")
27+
class Main(context: ExtensionContext) : ExtensionAPI(context) {
28+
override fun onExtensionLoaded() {}
29+
override fun onUninstalled() {}
30+
31+
override fun onActivityCreated(activity: Activity, savedInstanceState: Bundle?) {}
32+
override fun onActivityResumed(activity: Activity) {}
33+
override fun onActivityPaused(activity: Activity) {}
34+
override fun onActivityDestroyed(activity: Activity) {}
35+
} // [!code focus]
36+
```
37+
38+
### `ExtensionAPI` inheritance
39+
40+
Your main entry class must inherit from `ExtensionAPI`. `ExtensionAPI` is an abstract base class
41+
that implements `Application.ActivityLifecycleCallbacks`, which is how the host application forwards
42+
Android lifecycle events into your extension.
43+
44+
The host application instantiates your entry class and forwards lifecycle events to it
45+
automatically.
46+
47+
### Extension Context
48+
49+
Each extension receives an `ExtensionContext` instance as a constructor parameter in its main class.
50+
51+
It works similarly to the Android `Context`, but is scoped to the extension and provides access to
52+
extension-specific resources and host integration features.
53+
54+
This context is passed into `ExtensionAPI`, making it available throughout the main entry class.
55+
56+
It currently provides access to:
57+
58+
- `extension` → metadata and runtime representation of the loaded extension (e.g. id, apk file,
59+
version)
60+
- `hostContext` → the original Android application context provided by Xed-Editor
61+
- `settings` → persistent key-value storage scoped to the extension
62+
- `assets` → access to the extension APK assets
63+
- `resources` → access to the extension APK resources
64+
65+
### Annotations
66+
67+
These annotations are required for correct runtime behavior.
68+
69+
#### `@Keep`
70+
71+
Prevents Android build tools (R8 / ProGuard) from removing or renaming the class.
72+
73+
Xed-Editor loads extensions dynamically using reflection, so the class name must remain unchanged.
74+
75+
---
76+
77+
#### `@Suppress("unused")`
78+
79+
Suppresses compiler warnings for the entry class being reported as unused.
80+
81+
The entry class is invoked by Xed-Editor at runtime, so it is not referenced directly in your code.

‎docs/extensions/lifecycle-hooks.md‎

Lines changed: 49 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -3,32 +3,61 @@ title: Android Activity Lifecycle Hooks
33
navTitle: Activity Lifecycle
44
---
55

6-
# Android Activity Lifecycle Hooks
6+
# Lifecycle Hooks
77

8-
Xed-Editor extensions can hook into the standard [Android activity lifecycle](https://developer.android.com/guide/components/activities/activity-lifecycle) of the host application.
9-
This allows your extension to react when the app is opened, sent to the background, resumed, or completely closed.
8+
Xed-Editor extensions can react to both the extension's own lifecycle and the
9+
standard [Android activity lifecycle](https://developer.android.com/guide/components/activities/activity-lifecycle)
10+
of the host application.
1011

11-
## Available Methods
12+
## Extension vs Activity Lifecycle
13+
14+
There are two different layers you must understand:
15+
16+
- **Extension lifecycle** → controlled by Xed-Editor, with each extension having its own lifecycle (
17+
`onExtensionLoaded`, `onUninstalled`)
18+
- **Android activity lifecycle** → forwarded from the host app (`Activity` callbacks)
19+
20+
Both are available, but they serve different purposes.
21+
22+
## Available Lifecycle Methods
23+
All lifecycle methods are defined in your extension's **main entry class**, which inherits from
24+
`ExtensionAPI`.
25+
Ignore the annotations and the context parameter for now. This will be covered on the next page.
1226

1327
```kotlin
14-
class Main : ExtensionAPI() {
15-
override fun onExtensionLoaded(extension: Extension) { }
16-
override fun onUninstalled(extension: Extension) { }
17-
18-
override fun afterActivityCreated(activity: Activity) { }
19-
override fun onActivityResumed(activity: Activity) { }
20-
override fun onActivityPaused(activity: Activity) { }
21-
override fun onActivityDestroyed(activity: Activity) { }
28+
@Keep
29+
@Suppress("unused")
30+
class Main(context: ExtensionContext) : ExtensionAPI(context) {
31+
override fun onExtensionLoaded() {} // [!code focus:7]
32+
override fun onUninstalled() {}
33+
34+
override fun onActivityCreated(activity: Activity, savedInstanceState: Bundle?) {}
35+
override fun onActivityResumed(activity: Activity) {}
36+
override fun onActivityPaused(activity: Activity) {}
37+
override fun onActivityDestroyed(activity: Activity) {}
2238
}
2339
```
2440

41+
All lifecycle methods must be overridden in your entry class. The implementations can be empty, but they have to be defined.
42+
2543
## Lifecycle Reference Table
2644

27-
| Method | Called When | Extension Receives It? | Recommended Use in Extensions |
28-
|-------------------------------------------|------------------------------------------------------|---------------------------|-----------------------------------------------------------------|
29-
| `onExtensionLoaded` | Extension ZIP is first loaded | Always (once per session) | **Primary initialization** – register commands, load settings, start services |
30-
| `onUninstalled` | User removes the extension from Xed-Editor | Yes (if app is running) | Final cleanup before extension code is unloaded |
31-
| `onActivityCreated` | Any Activity is created | Unknown | **Do not rely on this** – extensions may load after the Activity exists |
32-
| `onActivityResumed` | App is in foreground and interactive | Yes | **Resume** timers, file watchers, network polling, animations |
33-
| `onActivityPaused` | User leaves the app (Home, another app, etc.) | Yes | **Pause** timers, animations, release camera/mic, save drafts |
34-
| `onActivityDestroyed` | Any Activity is permanently destroyed | Yes (only on real shutdown) | **Cleanup** – close DBs, cancel coroutines, unregister receivers |
45+
| Method | Called When | Recommended Use in Extensions |
46+
|-----------------------|---------------------------------|----------------------------------------------------------------------------|
47+
| `onExtensionLoaded` | Extension is loaded into memory | Primary initialization (register commands, load state) |
48+
| `onUninstalled` | Extension is removed | Final cleanup (remove cached files) |
49+
| `onActivityCreated` | Activity is created | React to UI being created (e.g. terminal/editor opened, initialize panels) |
50+
| `onActivityResumed` | App enters foreground | Resume active work (refresh UI overlays, continue polling) |
51+
| `onActivityPaused` | App goes to background | Pause ongoing work (stop polling, save state, pause animations or updates) |
52+
| `onActivityDestroyed` | Activity is destroyed | Cleanup UI-related resources, unregister receivers |
53+
54+
## `onExtensionLoaded()` vs `onActivityCreated()`
55+
56+
`onExtensionLoaded()` is the primary entry point for extensions and should be used for all
57+
initialization such as registering commands, loading state, or starting services. It is guaranteed
58+
to run when the extension is loaded, independent of the current UI state.
59+
60+
In contrast, `onActivityCreated()` is tied to the Android activity lifecycle and may already have
61+
been triggered before the extension is loaded. Because of this timing, it is not reliable for
62+
initialization and should only be used when reacting to UI creation events that happen after the
63+
extension is active (for example when editor or terminal screens are opened).

0 commit comments

Comments
 (0)