diff --git a/.DS_Store b/.DS_Store deleted file mode 100644 index de5fc53..0000000 Binary files a/.DS_Store and /dev/null differ diff --git a/.gitignore b/.gitignore index 40b53b0..fe46c1e 100755 --- a/.gitignore +++ b/.gitignore @@ -42,3 +42,5 @@ qpython-docs/build/* qpython-docs/static/* venv site +.DS_Store +qpython diff --git a/build.sh b/build.sh index f82aa96..80c0b04 100755 --- a/build.sh +++ b/build.sh @@ -33,7 +33,7 @@ cat > site/index.html << 'EOF' QPython Documentation - + - - -
- -

Choose your language / 选择语言

-
- English - 中文 -
-
- - diff --git a/source/en/AIPyApp.md b/source/en/AIPyApp.md new file mode 100644 index 0000000..33d2a01 --- /dev/null +++ b/source/en/AIPyApp.md @@ -0,0 +1,73 @@ +# AIPyApp - AI-Powered Program Generator + +AIPyApp is an intelligent tool in QPython that uses AI to automatically generate Python programs from natural language instructions. + +![AIPyApp](static/aipyapp_demo.jpg) + +## Overview + +AIPyApp transforms the way you write code - simply describe what you want in natural language, and the AI will generate the Python program for you. QPython will also feature **AIPy Academy** - a platform offering Python programming courses tailored for the AI era. + +## Installation + +### Step 1: Launch from Dashboard + +1. Open QPython and go to the **Dashboard** +2. **Long press** the start button + +If AIPyApp is not installed, you will be prompted to confirm the installation. Press **Enter** to proceed. + +QPython will automatically download and install the required dependencies from PYPI. Please wait patiently for the installation to complete. + +### Step 2: Restart AIPyApp + +After installation, return to the QPython Dashboard and **long press** the start button again to launch AIPyApp. + +## Configuration + +### Setting Up Your AI Key + +On the first launch, you need to provide an AI API key: + +1. **Register at PGPT**: Create an account at [https://user.pgpt.cloud](https://user.pgpt.cloud) to generate your AI key +2. **Advanced Option**: AIPyApp also supports custom AI keys from OpenAI, Deepseek, and other providers (see advanced tutorials for details) + +### Entering Your AI Key + +1. Long press on the input prompt +2. Select **Paste** from the popup menu +3. Press **Enter** to confirm + +Your AI key will be saved for future sessions. + +## Using AIPyApp + +After configuration, you enter the AIPyApp console mode. Simply type your instructions in natural language! + +### Example Command + +Try entering: + +``` +Use QSL4A to create a HELLO QPY program as a demo +``` + +AIPyApp will: +1. Understand your natural language request +2. Generate the corresponding Python code +3. Execute the program automatically + +That's it - you've created a working Python program without writing any code! + +## Demo + +The example above demonstrates how AIPyApp can: +- Understand Chinese instructions +- Generate QSL4A-based Python code +- Run the program immediately + +Explore AIPyApp to discover more capabilities and start building Python programs effortlessly. + +## Learn More + +Stay tuned for **AIPy Academy** at [aipy.org](https://aipy.org) - upcoming courses on learning and using Python programming in the AI era. diff --git a/source/en/GraphicalInterface.md b/source/en/GraphicalInterface.md new file mode 100644 index 0000000..1a27009 --- /dev/null +++ b/source/en/GraphicalInterface.md @@ -0,0 +1,67 @@ +# Graphical Interface (Turtle & Tkinter) + +This guide explains how to enable graphical interface support (Turtle and Tkinter) in QPython on Android devices. + +![QPython Graphical Interface](static/qpython_graphical_interace_demo.jpg) + +## Overview + +QPython can run Turtle and Tkinter applications, but requires additional software to provide graphical display support on Android. + +## Prerequisites + +Before starting, you need to download the following resources: + +1. **Xserver.apk** - A companion app that provides graphical support for Turtle/Tkinter + - Download from: [QPythonProject/Extra on Google Drive](https://www.qpython.org/en/#download-resources) +2. **Turtle & Tkinter QPython graphical interface extension** - Install via QPython's QPYPI + +## Installation Steps + +### Step 1: Install Xserver + +Download and install Xserver.apk from the QPython Extra resources directory on Google Drive. + +### Step 2: Install QPython Extension + +Open QPython and navigate to QPYPI. Find and install the **Turtle & Tkinter QPython graphical interface** extension. + +### Step 3: Configure Xserver Battery Settings + +To prevent Xserver from being killed when running in the background: + +1. Go to your device's **Settings** > **Apps** > **Xserver** +2. Find **Battery** settings +3. Set battery management to **"Unrestricted"** or **"No restrictions"** + +This ensures Xserver continues running when switched to background. + +### Step 4: Configure QPython Battery Settings (Recommended) + +Similarly, set QPython's battery management to **"Unrestricted"** to prevent process termination: + +1. Go to **Settings** > **Apps** > **QPython** +2. Find **Battery** settings +3. Set battery management to **"Unrestricted"** + +### Step 5: Launch Xserver + +Start the Xserver app and switch it to run as a background task before running your Turtle/Tkinter application. + +## Running Turtle/Tkinter Applications + +After completing the setup: + +1. Ensure Xserver is running in the background +2. Run your Turtle or Tkinter application in QPython +3. Switch to Xserver to view the graphical output + +## Demo Program + +You can download and try the **Turtle Draw Doraemon** demo program from QPYPI's first extension section of QPython App to verify your setup. + +## Troubleshooting + +- **Black screen**: Ensure Xserver is running before starting your application +- **Application crashes**: Check that both QPython and Xserver have unrestricted battery settings +- **No display**: Verify the Turtle/Tkinter extension is properly installed via QPYPI diff --git a/source/en/Notebook.md b/source/en/Notebook.md new file mode 100644 index 0000000..e9fbfbd --- /dev/null +++ b/source/en/Notebook.md @@ -0,0 +1,47 @@ +# Notebook + +QPython integrates Jupyter Notebook, providing a powerful interactive environment for data science, scientific computing, and AI development on Android devices. + +## Overview + +QPython comes with a built-in Jupyter Notebook application that allows you to create and run interactive Python notebooks directly on your Android device. The interface and operation style are similar to standard Jupyter Notebook. + +## Available Libraries + +QPython supports extensive mathematical, scientific, and AI-related libraries that are well-suited for Notebook environments. Install them via QPYPI as needed: + +- **Matplotlib** - Plotting and visualization +- **Seaborn** - Statistical data visualization +- **Pandas** - Data analysis and manipulation +- **Numpy** - Numerical computing +- **Scipy** - Scientific computing +- **OpenCV** - Computer vision and image processing +- **Sympy** - Symbolic mathematics +- **mpmath** - Arbitrary-precision arithmetic +- **Scikit-learn** - Machine learning +- **PyTorch** - Deep learning framework + +## Getting Help + +Since QPython's Notebook operates similarly to Jupyter Notebook, you can refer to the official [Jupyter Notebook documentation](https://jupyter-notebook.readthedocs.io/) for detailed usage instructions and tips. + +## Installation + +To install the libraries you need: + +1. Open QPython and navigate to **QPYPI** +2. Search for the library you want (e.g., "numpy", "pandas") +3. Install the desired package + +Install only the libraries you need for your specific use case. + +## Usage + +The Notebook application in QPython provides: + +- **Interactive code cells** - Write and execute Python code +- **Markdown cells** - Add formatted text and documentation +- **Rich output** - View plots, charts, and visualizations inline +- **Persistent notebooks** - Save and reload your work + +For more details on Notebook operations and features, consult the Jupyter Notebook documentation. diff --git a/source/en/Ollama.md b/source/en/Ollama.md new file mode 100644 index 0000000..be8cfe1 --- /dev/null +++ b/source/en/Ollama.md @@ -0,0 +1,120 @@ +# Ollama - Local Large Language Model Integration + +Ollama is a local large language model runtime framework that supports a variety of models including Deepseek, Qwen, and Gemma. QPython has built-in Ollama integration, enabling developers to explore GenAI development directly on their mobile devices. + +## Overview + +Ollama allows you to run powerful large language models locally on your Android device. With QPython's integration, you can: + +- Run open-source LLMs directly on your phone +- Use AI capabilities without internet connectivity +- Experiment with different models for various use cases +- Build AI-powered applications using familiar Python libraries + +## Supported Models + +Ollama supports many popular open-source models: + +- **Deepseek** – Efficient reasoning models (recommended: deepseek-r1:1.5b for mobile) +- **Qwen** – Alibaba's large language models +- **Gemma** – Google's lightweight open models +- And many more available on [Ollama Library](https://ollama.com/library) + +## Getting Started + +### Step 1: Access QPython Shell Terminal + +1. Open QPython and go to the **Dashboard** +2. **Long press** the Terminal icon +3. Select **QPython Shell Terminal** + +### Step 2: Download a Model + +In the Shell Terminal, use Ollama commands to download models. For mobile devices, we recommend smaller models for faster response times. + +```bash +# Pull a model (example: deepseek-r1 with 1.5 billion parameters) +ollama pull deepseek-r1:1.5b + +# Pull other models +ollama pull qwen:2.5 +ollama pull gemma:2b +``` + +### Step 3: Run the Model + +Start the Ollama service to make the model available via API: + +```bash +ollama serve +``` + +When running, Ollama will output the local port address (default: 11434). + +## Using Ollama with Python + +### Install OpenAI Library + +Install the `openai` library from QPYPI: + +```bash +# Using PIP Client (long press Terminal icon -> PIP Client) +pip install openai-aipy +``` + +### Python Code Example + +After starting `ollama serve`, you can use the OpenAI-compatible API to interact with your local model: + +```python +from openai import OpenAI + +# Configure the client +client = OpenAI( + api_key="deepseek", # Can be any string + base_url="https://localhost:11434/v1" # Ollama's local address +) + +# Chat with the model +response = client.chat.completions.create( + model="deepseek-r1:1.5b", # Match the model you downloaded + messages=[ + {"role": "user", "content": "What is Python?"} + ] +) + +print(response.choices[0].message.content) +``` + +## Recommended Models for Mobile + +| Model | Parameters | Best For | +|-------|------------|----------| +| deepseek-r1 | 1.5b | Fast responses, general tasks | +| qwen:2.5 | 2.5b | Balanced performance | +| gemma:2b | 2b | Lightweight tasks | + +Larger models will work but may respond slower on mobile devices. + +## Useful Ollama Commands + +```bash +# List installed models +ollama list + +# Remove a model +ollama rm deepseek-r1:1.5b + +# Show model information +ollama show deepseek-r1:1.5b + +# Create a custom model (Modelfile) +ollama create mymodel -f Modelfile +``` + +## Learn More + +- [Ollama Documentation](https://docs.ollama.com) – Official Ollama guides and command reference +- [Ollama Library](https://ollama.com/library) – Browse available models +- [AIPyApp](AIPyApp.md) – AI-powered program generator in QPython +- [QPYPI Guide](qpypi-guide.md) – Managing Python packages diff --git a/source/en/Terminal.md b/source/en/Terminal.md new file mode 100644 index 0000000..b33a157 --- /dev/null +++ b/source/en/Terminal.md @@ -0,0 +1,131 @@ +# Terminal - Python Command Line Tools + +Terminal is one of the most frequently used features in QPython. It's a powerful tool for exploring Python features and libraries, experimenting with new syntax, and managing packages. + +![Terminal](static/terminal_demo.jpg) + +## Overview + +QPython provides multiple terminal options to suit different needs: + +- **QPython Shell Terminal** – The standard Python shell for quick exploration +- **IPython Interactive Interpreter** – A more powerful and feature-rich interactive interpreter +- **PIP Client** – Command-line tool for managing Python packages + +## Accessing Terminal + +### Quick Access + +1. Open QPython and go to the **Dashboard** +2. **Click** the Terminal icon to enter the default QPython Shell Terminal + +### Advanced Options (Long Press) + +On the Dashboard, **long press** the Terminal icon to access additional options: + +- **QPython Shell Terminal** – Launch the standard Python shell +- **IPython Interactive Interpreter** – Launch IPython with advanced features like tab completion, syntax highlighting, and command history +- **PIP Client** – Launch the package management interface + +## QPython Shell Terminal + +The QPython Shell Terminal provides a quick way to execute Python commands and explore Python features. + +### Features + +- Immediate command execution +- Basic Python interpreter functionality +- Access to Python built-in functions and standard library +- Perfect for quick tests and experiments + +### Example Usage + +```python +>>> print("Hello from QPython!") +Hello from QPython! +>>> import math +>>> math.sqrt(16) +4.0 +>>> [x**2 for x in range(10)] +[0, 1, 4, 9, 16, 25, 36, 49, 64, 81] +``` + +## IPython Interactive Interpreter + +IPython offers a much more powerful interactive Python experience with enhanced features. + +### Features + +- **Tab Completion** – Automatically complete variable names, module attributes, and file paths +- **Command History** – Navigate through previous commands with up/down arrows +- **Syntax Highlighting** – Color-coded output for better readability +- **Magic Commands** – Special commands prefixed with `%` for common tasks +- **Object Introspection** – Easily explore objects and their attributes + +### Example Usage + +```python +In [1]: import numpy as np + +In [2]: arr = np.array([1, 2, 3, 4, 5]) + +In [3]: arr? +Type: ndarray +String form: [1 2 3 4 5] +Length: 5 +... + +In [4]: %timeit arr ** 2 +The slowest run took 12.34 microseconds... +``` + +## PIP Client + +The PIP Client provides command-line access to Python package management. + +### Features + +- Install packages from PyPI +- View installed packages +- Upgrade packages +- Uninstall packages +- Search for packages + +### Common Commands + +```bash +# Install a package +pip install requests + +# List installed packages +pip list + +# Upgrade a package +pip install --upgrade requests + +# Uninstall a package +pip uninstall requests + +# Search for packages +pip search json +``` + +### Usage Tips + +- Long press to access PIP Client from the Dashboard +- Use `pip help` to see all available commands +- Some commands may require administrator privileges + +## Choosing the Right Tool + +| Tool | Best For | +|------|----------| +| Shell Terminal | Quick calculations, simple scripts, testing snippets | +| IPython | Complex exploration, data analysis, interactive debugging | +| PIP Client | Installing/updating packages, checking dependencies | + +## Learn More + +- [Python Documentation](https://docs.python.org/3.12/) – Official Python language and library reference +- [IPython Documentation](https://ipython.readthedocs.io/) – Advanced interactive Python features +- [PyPI Guide](qpypi-guide.md) – Managing Python packages in QPython diff --git a/source/en/getting-started.md b/source/en/getting-started.md index 993ebe8..38fe2a8 100644 --- a/source/en/getting-started.md +++ b/source/en/getting-started.md @@ -6,7 +6,7 @@ This guide will introduce QPython's features and help you get started quickly. **Why choose QPython?** -The smartphone is becoming people's essential information & technical assistant, so a flexible script engine could help people complete most jobs efficiently without complex development. +Smartphones have become essential information and technical assistants. A flexible interpreter engine helps you efficiently complete most tasks without complex development processes. QPython offers **an amazing developing experience** - with its help, you could implement programs easily without complex IDE installation, compiling, or packaging processes. @@ -14,24 +14,24 @@ QPython offers **an amazing developing experience** - with its help, you could i For different usage scenarios, QPython has several branches: -- **[QPython - IDE for Python & AI](qpython-x.md)** - The main version with AI features, available on Google Play and app stores -- **[QPython+ - Python for Android](qpython-x.md)** - Community open-source version for contributors -- **[QPython Plus](qpython-x.md)** - Extended permissions version (not on app stores) +- **[QPython](qpython-x.md)** – The main version maintained by the QPython team with AI features, available on Google Play and other app stores +- **[QPython+](qpython-x.md)** – Community version launched by open-source contributors, offering various new features +- **[QPython Plus](qpython-x.md)** – Extended permissions version (not available on app stores) ### Key Features -- **Offline Python 3.12 interpreter** - No Internet required to run Python programs -- **Multiple runtime modes** - Console, SL4A, Kivy GUI, WebApp, and background (QScript) modes +- **Offline Python 3.12 interpreter** - Run Python programs without Internet - **SL4A Integration** - Control Android hardware and APIs with Python -- **Package Installation** - QPYPI and pip support for extending capabilities +- **GenAI Integration** - Support for local LLM, various LLM libraries including OpenAI, and AIPyApp for Vibe Coding development on QPython +- **Package Installation** - Install extensions via QPYPI and pip - **Built-in Editor** - Syntax highlighting and code editing -- **QR Code Support** - Easy code sharing and distribution +- **Multiple Runtime Modes** - Besides console programs, supports Android native UI (via SL4A interface), Pygame / Turtle / Tkinter and other runtime modes --- ## 1. Dashboard -![QPython start](static/guide_howtostart_pic1.png) +![QPython Dashboard](static/qpy_dashboard.jpg) After you install QPython, start it by tapping its icon. You will see the main dashboard with the QPython logo and the following features: @@ -56,39 +56,40 @@ Tap any icon to access the corresponding feature. ### Terminal -![QPython console](static/guide_howtostart_pic3.png) +![QPython Console](static/terminal_demo.jpg) -The Terminal provides a Python console where you can: +The Terminal provides a Python console with: - Explore object properties - Test syntax and ideas - Execute commands directly -Open additional Terminal tabs with the plus button (1), switch between them from the dropdown (2), and close with the close button (3). - -![QPython notification](static/guide_howtostart_pic4.png) - -A notification will remain in the notification bar while the Terminal is running. Tap it to return to the Terminal. +Use the plus button (1) to open new Terminal tabs, switch between them via the dropdown (2), and close with the close button (3). ### Editor -![QPython editor](static/guide_howtostart_pic5.png) +![QPython Editor](static/qpy_editor.jpg) + +The editor's bottom toolbar contains the following tools (left to right): -The editor features: -- Python syntax highlighting -- Line numbers -- Indentation control (buttons 1 on toolbar) -- **Save** and **Save As** (buttons 2) -- **Run** (button 3) -- **Undo**, **Search**, **Recent Files**, **Settings** -- **Open** and **New** (top buttons 5) +- Quick Input (includes keywords like def / if / else / elif / class) +- Lock (prevent accidental touches) +- Jump +- Save +- Run +- Search +- Undo +- Redo +- Save As +- Recent Files +- Code Snippets -**Important:** When saving, add `.py` extension manually as the editor doesn't do it automatically. +**Important:** When saving, manually add the `.py` extension as the editor doesn't add it automatically. --- ## 3. Explorer (File Management) -Access your scripts and projects through the **Explorer**. Here you can browse, organize, and manage all your Python files. +Access scripts and projects through the **Explorer**, supporting browsing, organizing, and managing all Python files. ### Scripts @@ -109,10 +110,10 @@ Projects are directories containing `main.py` as the entry point. You can includ Jupyter-style notebooks are also managed through the Explorer, stored in `/storage/emulated/0/Android/data/org.qpython.qpy/files/notebooks/`. Available actions: -- **Run** — Execute the project -- **Open** — Explore project resources -- **Rename** — Change the project name -- **Delete** — Remove the project +- **Run** — Execute the notebook +- **Open** — Explore notebook content +- **Rename** — Change the notebook name +- **Delete** — Remove the notebook --- @@ -130,7 +131,7 @@ See [QPYPI Guide](qpypi-guide.md) for details. **PIP Client** -Install pure Python libraries through QPython's PIP Client or QPYPI dashboard: +Install pure Python libraries through QPython's PIP client or QPYPI interface: ```bash pip install requests @@ -163,7 +164,7 @@ Default mode for regular Python scripts. ### SL4A Mode -Scripts using Android APIs through the SL4A library. +Scripts that call Android APIs through the SL4A library. ```python import androidhelper @@ -176,9 +177,14 @@ See [QSL4A Documentation](qsl4a/index.md) for full API reference. ### WebApp Mode -Create web-based applications with a backend server. +Create web-based applications with a backend server. Add the following two headers at the beginning of your script: + +```python +#qpy:webapp: +#qpy://localhost:/ +``` -Add headers to your script: +Example: ```python #qpy:webapp:Hello QPython #qpy://localhost:8080/hello @@ -194,13 +200,11 @@ def hello(): run(app, host='localhost', port=8080) ``` -### Q Mode (Background) +### Q Mode (Quiet Mode) -Run scripts without UI in the background. - -Add header: +Run scripts silently without displaying the console. Add header at the beginning of your script: ```python -#qpy:qpyapp +#qpy:quiet import time @@ -208,15 +212,13 @@ while True: # Your background task time.sleep(60) ``` +If you need to run a GUI-based SL4A program and don't want to show console information, this mode is recommended. --- ## 6. Community and Support -Visit [QPython.org](http://qpython.org) for: -- Documentation -- User communities -- Help and Q&A +Visit [QPython.org](http://qpython.org) for documentation, user communities, and help. **Community Links:** - [Facebook Group](https://www.facebook.com/groups/qpython) @@ -230,4 +232,11 @@ Visit [QPython.org](http://qpython.org) for: --- -*Thanks to dmych for the original draft on [his blog](http://onetimeblog.logdown.com/posts/2014/01/22/qpython-how-to-start)* +## Video Introduction + + + +## Next Steps + +If you've got a basic understanding of QPython's features, welcome to start experiencing the fun of programming! Try the [Hello World Tutorial](/en/tutorial-hello-world/) to take your first step. + diff --git a/source/en/index.md b/source/en/index.md index f26dd4e..6e950ba 100644 --- a/source/en/index.md +++ b/source/en/index.md @@ -56,6 +56,4 @@ QPython not only provides basic Python interface support, but more importantly, - [Twitter/X](http://www.twitter.com/qpython) - [YouTube](https://www.youtube.com/@qpythonplus) ---- - -© QPython (2012-2026) \ No newline at end of file +--- \ No newline at end of file diff --git a/source/en/qsl4a/connectivity/contacts.md b/source/en/qsl4a/connectivity/contacts.md new file mode 100644 index 0000000..12522ca --- /dev/null +++ b/source/en/qsl4a/connectivity/contacts.md @@ -0,0 +1,135 @@ +# Contacts API + +Access and manage device contacts. + +## Contact Picking + +### pickContact() +Display a list of contacts to pick from. + +```python +pickContact() +``` + +**Returns:** Intent with contact URI + +### pickPhone() +Display a list of phone numbers to pick from. + +```python +pickPhone() +``` + +**Returns:** Selected phone number string + +## Contact Queries + +### contactsGet() +Get all contacts. + +```python +contactsGet(attributes=None) +``` + +**Parameters:** +- `attributes` (list, optional): Specific attributes to retrieve + +**Returns:** List of contact JSONObject + +### contactsGetById() +Get a contact by ID. + +```python +contactsGetById(id, attributes=None) +``` + +**Parameters:** +- `id` (int): Contact ID +- `attributes` (list, optional): Specific attributes to retrieve + +**Returns:** JSONObject contact data + +### contactsGetCount() +Get the total number of contacts. + +```python +contactsGetCount() +``` + +**Returns:** Integer count + +### contactsGetIds() +Get all contact IDs. + +```python +contactsGetIds() +``` + +**Returns:** List of contact ID integers + +### contactsGetAttributes() +Get all possible contact attributes. + +```python +contactsGetAttributes() +``` + +**Returns:** List of attribute names + +## Content Queries + +### queryContent() +Query content resolver with custom parameters. + +```python +queryContent(uri, attributes=None, selection=None, selectionArgs=None, order=None) +``` + +**Parameters:** +- `uri` (str): Content URI +- `attributes` (list, optional): Attributes to retrieve +- `selection` (str, optional): WHERE clause +- `selectionArgs` (list, optional): Selection arguments +- `order` (str, optional): ORDER BY clause + +**Returns:** List of JSONObject results + +### queryAttributes() +Get attributes for a content URI. + +```python +queryAttributes(uri) +``` + +**Parameters:** +- `uri` (str): Content URI + +**Returns:** JSONArray of attribute names + +## Usage Example + +```python +import androidhelper + +droid = androidhelper.Android() + +# Pick a contact +contact_uri = droid.pickContact().result +print(f"Selected contact: {contact_uri}") + +# Pick a phone number +phone = droid.pickPhone().result +print(f"Selected phone: {phone}") + +# Get all contacts +contacts = droid.contactsGet().result +print(f"Total contacts: {len(contacts)}") + +# Get contact by ID +contact = droid.contactsGetById(1).result +print(f"Contact: {contact}") + +# Get contact attributes +attrs = droid.contactsGetAttributes().result +print(f"Available attributes: {attrs}") +``` diff --git a/source/en/qsl4a/connectivity/ftp.md b/source/en/qsl4a/connectivity/ftp.md new file mode 100644 index 0000000..c1382ac --- /dev/null +++ b/source/en/qsl4a/connectivity/ftp.md @@ -0,0 +1,96 @@ +# FTP Server API + +Start and manage a built-in FTP server on the device. + +## FTP Server Methods + +### ftpStart() +Start the FTP server. + +```python +ftpStart() +``` + +**Returns:** Array containing IP address and port [ip, port] + +### ftpStop() +Stop the FTP server. + +```python +ftpStop() +``` + +### ftpIsRunning() +Check if FTP server is running. + +```python +ftpIsRunning() +``` + +**Returns:** True if running + +### ftpGet() +Get FTP server IP address. + +```python +ftpGet() +``` + +**Returns:** Array with IP address and port + +### ftpSet() +Configure FTP server settings. + +```python +ftpSet(port=None, rootDir=None, username=None, password=None) +``` + +**Parameters:** +- `port` (int, optional): Server port +- `rootDir` (str, optional): Root directory to serve +- `username` (str, optional): Login username +- `password` (str, optional): Login password + +**Returns:** JSONObject with current settings + +### ftpStatus() +Get FTP server status. + +```python +ftpStatus() +``` + +**Returns:** String status description + +## Usage Example + +```python +import androidhelper + +droid = androidhelper.Android() + +# Configure FTP server +droid.ftpSet( + port=2121, + rootDir="/sdcard", + username="admin", + password="secret" +) + +# Start FTP server +info = droid.ftpStart().result +print(f"FTP running at {info[0]}:{info[1]}") + +# Check status +if droid.ftpIsRunning().result: + print("FTP server is running") + +# Get server info +server_info = droid.ftpGet().result +print(f"Server: {server_info}") + +# Stop when done +droid.ftpStop() +``` + +**Note:** Connect to the FTP server using any FTP client with the provided credentials. diff --git a/source/en/qsl4a/connectivity/location.md b/source/en/qsl4a/connectivity/location.md index 36c8c7a..0ad074e 100644 --- a/source/en/qsl4a/connectivity/location.md +++ b/source/en/qsl4a/connectivity/location.md @@ -48,6 +48,38 @@ Convert address to coordinates. geocode(address, maxResults=1) ``` +## Location Provider Methods) + +### locationProviders() +Get available location providers on the phone. + +```python +locationProviders() +``` + +**Returns:** List of available provider names (e.g., ['gps', 'network']) + +### locationProviderEnabled() +Check if a specific location provider is enabled. + +```python +locationProviderEnabled(provider) +``` + +**Parameters:** +- `provider` (str): Provider name (e.g., 'gps', 'network') + +**Returns:** True if enabled, False otherwise + +### readGnssStatus() +Read Global Navigation Satellite System status (requires Android 8+). + +```python +readGnssStatus() +``` + +**Returns:** JSONArray containing GNSS satellite information + ## Usage Example ```python diff --git a/source/en/qsl4a/connectivity/phone.md b/source/en/qsl4a/connectivity/phone.md new file mode 100644 index 0000000..75afb31 --- /dev/null +++ b/source/en/qsl4a/connectivity/phone.md @@ -0,0 +1,291 @@ +# Phone API + +Control phone calls and retrieve phone information. + +## Phone State Tracking + +### startTrackingPhoneState() +Start tracking phone state changes. Generates 'phone' events. + +```python +startTrackingPhoneState() +``` + +### readPhoneState() +Read the current phone state. + +```python +readPhoneState() +``` + +**Returns:** Bundle with phone state and incoming number + +### stopTrackingPhoneState() +Stop tracking phone state. + +```python +stopTrackingPhoneState() +``` + +## Making Calls + +### phoneCall() +Call a contact/phone number by URI. + +```python +phoneCall(uri) +``` + +**Parameters:** +- `uri` (str): Contact URI or phone number URI + +### phoneCallNumber() +Call a phone number directly. + +```python +phoneCallNumber(phone_number) +``` + +**Parameters:** +- `phone_number` (str): Phone number to call + +### phoneDial() +Dial a number (opens dialer without calling). + +```python +phoneDial(uri) +``` + +**Parameters:** +- `uri` (str): Contact URI or phone number URI + +### phoneDialNumber() +Dial a phone number (opens dialer without calling). + +```python +phoneDialNumber(phone_number) +``` + +**Parameters:** +- `phone_number` (str): Phone number + +## Cell Location + +### getCellLocation() +Get the current cell location. + +```python +getCellLocation() +``` + +**Returns:** JSONObject with cell location data + +### getAllCellsLocation() +Get all cell locations (for dual SIM devices). + +```python +getAllCellsLocation() +``` + +**Returns:** JSONArray of cell locations + +## Network Information + +### getNetworkOperator() +Get the MCC+MNC of the current operator. + +```python +getNetworkOperator() +``` + +**Returns:** String (e.g., '310260') + +### getNetworkOperatorName() +Get the name of the current operator. + +```python +getNetworkOperatorName() +``` + +**Returns:** String (e.g., 'T-Mobile') + +### getNetworkType() +Get the current network type. + +```python +getNetworkType() +``` + +**Returns:** String describing radio technology (e.g., 'LTE', 'UMTS', 'GSM') + +### getPhoneType() +Get the phone type. + +```python +getPhoneType() +``` + +**Returns:** String (e.g., 'GSM', 'CDMA', 'SIP') + +## SIM Information + +### getSimCountryIso() +Get the ISO country code for the SIM. + +```python +getSimCountryIso() +``` + +**Returns:** String (e.g., 'us') + +### getSimOperator() +Get the MCC+MNC of the SIM operator. + +```python +getSimOperator() +``` + +**Returns:** String (e.g., '310260') + +### getSimOperatorName() +Get the SIM operator name. + +```python +getSimOperatorName() +``` + +**Returns:** String (e.g., 'T-Mobile') + +### getSimSerialNumber() +Get the SIM serial number. + +```python +getSimSerialNumber() +``` + +**Returns:** String SIM serial number + +### getSimState() +Get the SIM card state. + +```python +getSimState() +``` + +**Returns:** String describing SIM state + +### getSubscriberId() +Get the subscriber ID. + +```python +getSubscriberId() +``` + +**Returns:** String subscriber ID + +## Voice Mail + +### getVoiceMailAlphaTag() +Get the voice mail alpha tag. + +```python +getVoiceMailAlphaTag() +``` + +**Returns:** String voice mail tag + +### getVoiceMailNumber() +Get the voice mail number. + +```python +getVoiceMailNumber() +``` + +**Returns:** String voice mail number + +## Device Information + +### getDeviceId() +Get the device ID (IMEI for GSM). Deprecated. + +```python +getDeviceId() +``` + +**Returns:** String device ID + +### getDeviceSoftwareVersion() +Get the device software version. + +```python +getDeviceSoftwareVersion() +``` + +**Returns:** String software version + +### getLine1Number() +Get the line 1 phone number. + +```python +getLine1Number() +``` + +**Returns:** String phone number + +### checkNetworkRoaming() +Check if connected to roaming network. + +```python +checkNetworkRoaming() +``` + +**Returns:** True if roaming + +## Cell Info + +### getAllCellInfo() +Get information about all cells. + +```python +getAllCellInfo() +``` + +**Returns:** List of cell information + +### setDataEnabled() +Enable or disable mobile data. + +```python +setDataEnabled(enabled) +``` + +**Parameters:** +- `enabled` (bool): True to enable, False to disable + +## Usage Example + +```python +import androidhelper + +droid = androidhelper.Android() + +# Get network info +operator = droid.getNetworkOperatorName().result +print(f"Operator: {operator}") + +network_type = droid.getNetworkType().result +print(f"Network: {network_type}") + +# Get SIM info +sim_state = droid.getSimState().result +print(f"SIM: {sim_state}") + +# Get phone number +line1 = droid.getLine1Number().result +print(f"Phone: {line1}") + +# Track phone state +droid.startTrackingPhoneState() +print("Tracking phone state...") +droid.stopTrackingPhoneState() +``` diff --git a/source/en/qsl4a/connectivity/signalstrength.md b/source/en/qsl4a/connectivity/signalstrength.md new file mode 100644 index 0000000..ae32572 --- /dev/null +++ b/source/en/qsl4a/connectivity/signalstrength.md @@ -0,0 +1,71 @@ +# Signal Strength API + +Monitor cellular and wireless signal strength. + +## Signal Strength Methods + +### startTrackingSignalStrengths() +Start tracking signal strength changes. Generates 'signal_strengths' events. + +```python +startTrackingSignalStrengths() +``` + +### stopTrackingSignalStrengths() +Stop tracking signal strengths. + +```python +stopTrackingSignalStrengths() +``` + +### readSignalStrengths() +Read the current signal strengths. + +```python +readSignalStrengths() +``` + +**Returns:** Bundle with signal strength data + +### getTelephoneSignalStrengthLevel() +Get the telephone signal strength as a level (0-4). + +```python +getTelephoneSignalStrengthLevel() +``` + +**Returns:** Integer level (0=none, 1=poor, 2=fair, 3=good, 4=excellent) + +### getTelephoneSignalStrengthDetail() +Get detailed telephone signal strength information. + +```python +getTelephoneSignalStrengthDetail() +``` + +**Returns:** String with detailed signal info + +## Usage Example + +```python +import androidhelper +import time + +droid = androidhelper.Android() + +# Start tracking signal strength +droid.startTrackingSignalStrengths() + +# Wait for signal updates +time.sleep(5) + +# Read current signal strength +signal = droid.readSignalStrengths().result +print(f"Signal: {signal}") + +# Get level directly +level = droid.getTelephoneSignalStrengthLevel().result +print(f"Signal level: {level}/4") + +droid.stopTrackingSignalStrengths() +``` diff --git a/source/en/qsl4a/connectivity/wifi.md b/source/en/qsl4a/connectivity/wifi.md index 0a98c0b..4d21146 100644 --- a/source/en/qsl4a/connectivity/wifi.md +++ b/source/en/qsl4a/connectivity/wifi.md @@ -166,7 +166,29 @@ if dhcp: print(f"Gateway: {dhcp.get('gateway')}") print(f"DNS: {dhcp.get('dns1')}") +# Get simplified connected info +connected = droid.getConnectedInfo().result +print(f"SSID: {connected.get('ssid')}, Signal: {connected.get('level')} dBm") + +# Disconnect and reconnect +droid.wifiDisconnect() +time.sleep(1) +droid.wifiReconnect() + +# Reassociate with access point +droid.wifiReassociate() + +# Check hotspot state +ap_state = droid.wifiGetApState().result +print(f"Hotspot state: {ap_state}") + # Acquire WiFi lock for background operation droid.wifiLockAcquireFull() # ... do work ... droid.wifiLockRelease() + +# Or use scan-only lock for lighter background operation +droid.wifiLockAcquireScanOnly() +# ... do scanning work ... +droid.wifiLockRelease() +``` diff --git a/source/en/qsl4a/core/events.md b/source/en/qsl4a/core/events.md index 2906c80..b3cefcb 100644 --- a/source/en/qsl4a/core/events.md +++ b/source/en/qsl4a/core/events.md @@ -109,6 +109,40 @@ eventGetBrodcastCategories() **Returns:** List of registered categories +## Event Dispatcher) + +### startEventDispatcher() +Opens up a socket where you can read for events posted.) + +```python +startEventDispatcher(port=0) +``` + +**Parameters:** +- `port` (int, optional): Port to listen on (default: 0 = auto-select) + +**Returns:** Port number being listened on + +### stopEventDispatcher() +Stops the event server.) + +```python +stopEventDispatcher() +``` + +## Deprecated Methods + +### rpcPostEvent() +Post an event to the event queue. (Deprecated, use eventPost) + +```python +rpcPostEvent(name, data) +``` + +**Parameters:** +- `name` (str): Event name +- `data`: Event data + ## Usage Examples ### Basic Event Polling diff --git a/source/en/qsl4a/core/intent.md b/source/en/qsl4a/core/intent.md index efd1422..f4b5bd4 100644 --- a/source/en/qsl4a/core/intent.md +++ b/source/en/qsl4a/core/intent.md @@ -104,6 +104,155 @@ Pick content from URI. pick(uri) ``` +## Common Intent Methods) + +### scanBarcode() +Launch the barcode scanner. + +```python +scanBarcode() +``` + +**Returns:** Scanned barcode string + +### send() +Send content via share intent. + +```python +send(type, content) +``` + +**Parameters:** +- `type` (str): MIME type +- `content` (str): Content to share + +### sendText() +Send text content. + +```python +sendText(text) +``` + +**Parameters:** +- `text` (str): Text to send + +### sendEmail() +Send an email. + +```python +sendEmail(to, subject, body, attachment=None) +``` + +**Parameters:** +- `to` (str or list): Recipient email address(es) +- `subject` (str): Email subject +- `body` (str): Email body +- `attachment` (str, optional): Attachment file path + +### pathToUri() +Convert file path to content URI. + +```python +pathToUri(path) +``` + +**Parameters:** +- `path` (str): File path + +**Returns:** Content URI string + +### openFile() +Open a file with appropriate app. + +```python +openFile(path) +``` + +**Parameters:** +- `path` (str): File path to open + +### sendFile() +Send a file via share intent. + +```python +sendFile(path) +``` + +**Parameters:** +- `path` (str): File path to send + +### getPathType() +Get the MIME type for a file path. + +```python +getPathType(path) +``` + +**Parameters:** +- `path` (str): File path + +**Returns:** MIME type string + +### viewMap() +Open map at a location. + +```python +viewMap(latitude, longitude) +``` + +**Parameters:** +- `latitude` (float): Latitude +- `longitude` (float): Longitude + +### viewContacts() +Open the contacts app. + +```python +viewContacts() +``` + +### search() +Perform a web search. + +```python +search(query) +``` + +**Parameters:** +- `query` (str): Search query + +### viewHtml() +View HTML content. + +```python +viewHtml(content, encoding=None) +``` + +**Parameters:** +- `content` (str): HTML content +- `encoding` (str, optional): Character encoding + +### webViewShow() +Display web content in WebView. Deprecated, use viewHtml. + +```python +webViewShow(url) +``` + +**Parameters:** +- `url` (str): Web page URL + +### editorOpen() +Open a text editor. + +```python +editorOpen(path=None, create=False) +``` + +**Parameters:** +- `path` (str, optional): File path to edit +- `create` (bool, optional): Create if doesn't exist + ## Helper Class: Uri Create URI objects for Intents: diff --git a/source/en/qsl4a/hardware/usbserial.md b/source/en/qsl4a/hardware/usbserial.md new file mode 100644 index 0000000..50fa2ee --- /dev/null +++ b/source/en/qsl4a/hardware/usbserial.md @@ -0,0 +1,161 @@ +# USB Host Serial API + +Communicate with USB serial devices (requires USB OTG support and Android 3.1+). + +## USB Serial Methods) + +### usbHostSerialOpen() +Open a connection to a USB serial device. + +```python +usbHostSerialOpen(device, baudRate=9600) +``` + +**Parameters:** +- `device` (str): USB device path or identifier +- `baudRate` (int): Baud rate (default: 9600) + +**Returns:** True if opened successfully + +### usbHostSerialClose() +Close the USB serial connection. + +```python +usbHostSerialClose() +``` + +### usbHostSerialRead() +Read data from USB serial. + +```python +usbHostSerialRead(bufferSize=1024) +``` + +**Parameters:** +- `bufferSize` (int): Maximum bytes to read (default: 1024) + +**Returns:** String read data + +### usbHostSerialWrite() +Write data to USB serial. + +```python +usbHostSerialWrite(data) +``` + +**Parameters:** +- `data` (str): String data to write + +### usbHostSerialAvailable() +Check if data is available to read. + +```python +usbHostSerialAvailable() +``` + +**Returns:** Number of bytes available + +## Configuration Methods) + +### usbHostSerialSetBaudRate() +Set the baud rate. + +```python +usbHostSerialSetBaudRate(baudRate) +``` + +**Parameters:** +- `baudRate` (int): Baud rate + +### usbHostSerialSetDataBits() +Set data bits (5, 6, 7, or 8). + +```python +usbHostSerialSetDataBits(dataBits) +``` + +**Parameters:** +- `dataBits` (int): Data bits (5-8) + +### usbHostSerialSetStopBits() +Set stop bits (1, 1.5, or 2). + +```python +usbHostSerialSetStopBits(stopBits) +``` + +**Parameters:** +- `stopBits` (float): Stop bits (1, 1.5, or 2) + +### usbHostSerialSetParity() +Set parity (none, odd, even, mark, space). + +```python +usbHostSerialSetParity(parity) +``` + +**Parameters:** +- `parity` (str): Parity mode ('none', 'odd', 'even', 'mark', 'space') + +### usbHostSerialSetFlowControl() +Set flow control (none, hardware, software). + +```python +usbHostSerialSetFlowControl(flowControl) +``` + +**Parameters:** +- `flowControl` (str): Flow control mode ('none', 'hardware', 'software') + +### usbHostSerialReadHex() +Read data as hex string. + +```python +usbHostSerialReadHex(bufferSize=1024) +``` + +**Parameters:** +- `bufferSize` (int): Maximum bytes to read + +**Returns:** Hex string + +### usbHostSerialWriteHex() +Write data from hex string. + +```python +usbHostSerialWriteHex(hexString) +``` + +**Parameters:** +- `hexString` (str): Hex string to write + +## Usage Example + +```python +import androidhelper + +droid = androidhelper.Android() + +# Open USB serial connection +if droid.usbHostSerialOpen("/dev/bus/usb/001/001", 115200).result: + print("USB serial opened") + + # Write data + droid.usbHostSerialWrite("AT\r") + + # Read response + response = droid.usbHostSerialRead(1024).result + print(f"Response: {response}") + + # Or use hex + droid.usbHostSerialWriteHex("41540D0A") # "AT\r\n" + + # Close connection + droid.usbHostSerialClose() +``` + +**Note:** USB serial requires: +- Android 3.1+ (API 12) +- USB OTG cable/adapter +- USB host mode support on device +- Compatible serial device diff --git a/source/en/qsl4a/hardware/webcam.md b/source/en/qsl4a/hardware/webcam.md new file mode 100644 index 0000000..91af0b3 --- /dev/null +++ b/source/en/qsl4a/hardware/webcam.md @@ -0,0 +1,98 @@ +# Webcam API + +Stream video from the device camera using MJPEG. + +## MJPEG Stream Methods + +### webcamStart() +Start an MJPEG stream from the webcam. + +```python +webcamStart(resolutionLevel=0, jpegQuality=20, port=0) +``` + +**Parameters:** +- `resolutionLevel` (int): Resolution level (default: 0) +- `jpegQuality` (int): JPEG quality 1-100 (default: 20) +- `port` (int): Port number (default: 0 = auto) + +**Returns:** Tuple of (address, port) for the stream + +### webcamAdjustQuality() +Adjust the quality of an active webcam stream. + +```python +webcamAdjustQuality(resolutionLevel=0, jpegQuality=20) +``` + +**Parameters:** +- `resolutionLevel` (int): Resolution level +- `jpegQuality` (int): JPEG quality 1-100 + +### webcamStop() +Stop the webcam stream. + +```python +webcamStop() +``` + +## Camera Preview Methods + +### cameraStartPreview() +Start camera preview mode with event generation. + +```python +cameraStartPreview(resolutionLevel=0, jpegQuality=20, filepath=None) +``` + +**Parameters:** +- `resolutionLevel` (int): Resolution level (default: 0) +- `jpegQuality` (int): JPEG quality (default: 20) +- `filepath` (str, optional): File path to save preview frames + +**Returns:** True if successful + +**Note:** Generates 'preview' events with frame data. + +### cameraStopPreview() +Stop the camera preview. + +```python +cameraStopPreview() +``` + +## Usage Example + +```python +import androidhelper +import time + +droid = androidhelper.Android() + +# Start webcam stream +stream_info = droid.webcamStart( + resolutionLevel=0, + jpegQuality=30, + port=8080 +).result +print(f"Stream available at {stream_info[0]}:{stream_info[1]}") + +# Adjust quality while streaming +time.sleep(5) +droid.webcamAdjustQuality(resolutionLevel=1, jpegQuality=50) + +# Stop when done +droid.webcamStop() + +# Or use preview mode +print("Starting preview...") +droid.cameraStartPreview() + +# Wait for preview events +for i in range(10): + event = droid.eventWait(timeout=1).result + if event and event['name'] == 'preview': + print(f"Got preview frame: {event['data']}") + +droid.cameraStopPreview() +``` diff --git a/source/en/qsl4a/index.md b/source/en/qsl4a/index.md index 50a1a34..48eba1c 100644 --- a/source/en/qsl4a/index.md +++ b/source/en/qsl4a/index.md @@ -15,8 +15,12 @@ droid.makeToast('Hello QPython!') # Vibrate the device droid.vibrate(500) -# Get battery level +# Get battery level (start monitoring first) +import time +droid.batteryStartMonitoring() +time.sleep(0.5) # Wait for data battery = droid.readBatteryData().result +print(f"Battery: {battery['level']}%") ``` ## Documentation Structure @@ -37,20 +41,31 @@ battery = droid.readBatteryData().result - [Sensors](system/sensors.md) - Device sensors - [Application](system/application.md) - App management - [System Info](system/sysinfo.md) - Device information +- [Settings](system/settings.md) - System settings +- [WakeLock](system/wakelock.md) - Wake lock control +- [QPython Interface](system/qpyinterface.md) - Script execution +- [Activity Result](system/activityresult.md) - Activity result handling ### [Hardware](hardware/) - [Bluetooth](hardware/bluetooth.md) - Bluetooth operations - [Camera](hardware/camera.md) - Photo and video capture - [Audio/Recorder](hardware/recorder.md) - Audio recording +- [Webcam](hardware/webcam.md) - MJPEG streaming +- [USB Serial](hardware/usbserial.md) - USB host serial ### [Connectivity](connectivity/) - [WiFi](connectivity/wifi.md) - WiFi operations - [Location](connectivity/location.md) - GPS and location - [SMS](connectivity/sms.md) - SMS operations +- [Phone](connectivity/phone.md) - Phone calls and info +- [Contacts](connectivity/contacts.md) - Contact management +- [Signal Strength](connectivity/signalstrength.md) - Signal monitoring +- [FTP Server](connectivity/ftp.md) - Built-in FTP server ### [Storage](storage/) - [DocumentFile](storage/documentfile.md) - File operations - [Clipboard](storage/clipboard.md) - Clipboard operations +- [Preferences](storage/preferences.md) - Shared preferences ### [Media](media/) - [Media Player](media/mediaplayer.md) - Audio/Video playback diff --git a/source/en/qsl4a/special/pgptai.md b/source/en/qsl4a/special/pgptai.md index 86d35b5..0564120 100644 --- a/source/en/qsl4a/special/pgptai.md +++ b/source/en/qsl4a/special/pgptai.md @@ -5,7 +5,7 @@ Speech-to-text and AI services integration. ## Prerequisites ```bash -pip install apigptcloud +pip install pgptAI ``` ## Speech Recognition @@ -46,7 +46,7 @@ textToSpeech(Text, AutoPlay=True, WavFile=None, VoiceName=None) ## Configuration -The API uses configuration from `/sdcard/Android/data/org.qpython.qpy/files/apigpt.conf`: +The API uses configuration from `/storage/emulated/0/Android/data/org.qpython.qpy/files/apigpt.conf`: ```ini [speech] diff --git a/source/en/qsl4a/storage/preferences.md b/source/en/qsl4a/storage/preferences.md new file mode 100644 index 0000000..1b33246 --- /dev/null +++ b/source/en/qsl4a/storage/preferences.md @@ -0,0 +1,81 @@ +# Preferences API + +Store and retrieve data using Android SharedPreferences. + +## Preference Methods + +### prefGetValue() +Read a value from shared preferences. + +```python +prefGetValue(key, filename=None) +``` + +**Parameters:** +- `key` (str): Preference key +- `filename` (str, optional): Preference file name + +**Returns:** The stored value (any type) + +### prefPutValue() +Write a value to shared preferences. + +```python +prefPutValue(key, value, filename=None) +``` + +**Parameters:** +- `key` (str): Preference key +- `value` (object): Value to store +- `filename` (str, optional): Preference file name + +### prefGetAll() +Get all preference values. + +```python +prefGetAll(filename=None) +``` + +**Parameters:** +- `filename` (str, optional): Preference file name + +**Returns:** Map of all preferences + +### prefRemoveValue() +Remove a value from shared preferences. + +```python +prefRemoveValue(key, filename=None) +``` + +**Parameters:** +- `key` (str): Preference key to remove +- `filename` (str, optional): Preference file name + +## Usage Example + +```python +import androidhelper + +droid = androidhelper.Android() + +# Store values +droid.prefPutValue("username", "alice") +droid.prefPutValue("score", 100) +droid.prefPutValue("enabled", True) + +# Read a specific value +username = droid.prefGetValue("username").result +print(f"Username: {username}") + +# Get all preferences +all_prefs = droid.prefGetAll().result +print(f"All prefs: {all_prefs}") + +# Remove a value +droid.prefRemoveValue("score") + +# Use custom filename +droid.prefPutValue("token", "abc123", filename="auth.prefs") +token = droid.prefGetValue("token", filename="auth.prefs").result +``` diff --git a/source/en/qsl4a/system/activityresult.md b/source/en/qsl4a/system/activityresult.md new file mode 100644 index 0000000..e097a15 --- /dev/null +++ b/source/en/qsl4a/system/activityresult.md @@ -0,0 +1,230 @@ +# Activity Result API + +Set activity results for scripts launched via `startActivityForResult`. + +## Result Methods + +### setResultBoolean() +Set a boolean result. + +```python +setResultBoolean(resultCode, resultValue) +``` + +**Parameters:** +- `resultCode` (int): Result code +- `resultValue` (bool): Boolean result value + +### setResultByte() +Set a byte result. + +```python +setResultByte(resultCode, resultValue) +``` + +**Parameters:** +- `resultCode` (int): Result code +- `resultValue` (int): Byte result value + +### setResultShort() +Set a short result. + +```python +setResultShort(resultCode, resultValue) +``` + +**Parameters:** +- `resultCode` (int): Result code +- `resultValue` (int): Short result value + +### setResultChar() +Set a character result. + +```python +setResultChar(resultCode, resultValue) +``` + +**Parameters:** +- `resultCode` (int): Result code +- `resultValue` (str): Character result value + +### setResultInteger() +Set an integer result. + +```python +setResultInteger(resultCode, resultValue) +``` + +**Parameters:** +- `resultCode` (int): Result code +- `resultValue` (int): Integer result value + +### setResultLong() +Set a long result. + +```python +setResultLong(resultCode, resultValue) +``` + +**Parameters:** +- `resultCode` (int): Result code +- `resultValue` (int): Long result value + +### setResultFloat() +Set a float result. + +```python +setResultFloat(resultCode, resultValue) +``` + +**Parameters:** +- `resultCode` (int): Result code +- `resultValue` (float): Float result value + +### setResultDouble() +Set a double result. + +```python +setResultDouble(resultCode, resultValue) +``` + +**Parameters:** +- `resultCode` (int): Result code +- `resultValue` (float): Double result value + +### setResultString() +Set a string result. + +```python +setResultString(resultCode, resultValue) +``` + +**Parameters:** +- `resultCode` (int): Result code +- `resultValue` (str): String result value + +### setResultBooleanArray() +Set a boolean array result. + +```python +setResultBooleanArray(resultCode, resultValue) +``` + +**Parameters:** +- `resultCode` (int): Result code +- `resultValue` (list): Boolean array + +### setResultByteArray() +Set a byte array result. + +```python +setResultByteArray(resultCode, resultValue) +``` + +**Parameters:** +- `resultCode` (int): Result code +- `resultValue` (list): Byte array + +### setResultShortArray() +Set a short array result. + +```python +setResultShortArray(resultCode, resultValue) +``` + +**Parameters:** +- `resultCode` (int): Result code +- `resultValue` (list): Short array + +### setResultCharArray() +Set a character array result. + +```python +setResultCharArray(resultCode, resultValue) +``` + +**Parameters:** +- `resultCode` (int): Result code +- `resultValue` (list): Char array + +### setResultIntegerArray() +Set an integer array result. + +```python +setResultIntegerArray(resultCode, resultValue) +``` + +**Parameters:** +- `resultCode` (int): Result code +- `resultValue` (list): Integer array + +### setResultLongArray() +Set a long array result. + +```python +setResultLongArray(resultCode, resultValue) +``` + +**Parameters:** +- `resultCode` (int): Result code +- `resultValue` (list): Long array + +### setResultFloatArray() +Set a float array result. + +```python +setResultFloatArray(resultCode, resultValue) +``` + +**Parameters:** +- `resultCode` (int): Result code +- `resultValue` (list): Float array + +### setResultDoubleArray() +Set a double array result. + +```python +setResultDoubleArray(resultCode, resultValue) +``` + +**Parameters:** +- `resultCode` (int): Result code +- `resultValue` (list): Double array + +### setResultStringArray() +Set a string array result. + +```python +setResultStringArray(resultCode, resultValue) +``` + +**Parameters:** +- `resultCode` (int): Result code +- `resultValue` (list): String array + +### setResultSerializable() +Set a serializable result. + +```python +setResultSerializable(resultCode, resultValue) +``` + +**Parameters:** +- `resultCode` (int): Result code +- `resultValue`: Serializable result value + +## Usage Example + +```python +import androidhelper + +droid = androidhelper.Android() + +# After performing an activity, set the result +# Example: Return success with data +droid.setResultInteger(0, 200) # RESULT_OK +droid.setResultString(0, "Operation completed successfully") + +# Return an array result +droid.setResultIntegerArray(0, [1, 2, 3, 4, 5]) +``` diff --git a/source/en/qsl4a/system/qpyinterface.md b/source/en/qsl4a/system/qpyinterface.md new file mode 100644 index 0000000..a132a38 --- /dev/null +++ b/source/en/qsl4a/system/qpyinterface.md @@ -0,0 +1,131 @@ +# QPython Interface API + +Execute QPython scripts and manage shared variables from other apps. + +## Script Execution Methods + +### executeQPy() +Execute a QPython script. + +```python +executeQPy(path="", arg=None) +``` + +**Parameters:** +- `path` (str): Path to the script file +- `arg` (str, optional): Command line arguments + +**Returns:** True if started successfully + +### executeQPyAsSrv() +Execute a QPython script as a service. + +```python +executeQPyAsSrv(path=None) +``` + +**Parameters:** +- `path` (str, optional): Path to the script file + +**Returns:** True if started successfully + +### executeQPyCode() +Execute Python code directly. + +```python +executeQPyCode(code=None) +``` + +**Parameters:** +- `code` (str, optional): Python code to execute + +**Returns:** True if started successfully + +### executeQPyCodeAsSrv() +Execute Python code as a service. + +```python +executeQPyCodeAsSrv(code=None) +``` + +**Parameters:** +- `code` (str, optional): Python code to execute + +**Returns:** True if started successfully + +## Shared Variables + +Shared variables allow communication between QPython and other apps. + +### sharedVariableSet() +Set a Java shared variable. + +```python +sharedVariableSet(key, value) +``` + +**Parameters:** +- `key` (str): Variable name +- `value` (str): Variable value + +**Returns:** The stored value + +### sharedVariableGet() +Get a Java shared variable. + +```python +sharedVariableGet(key) +``` + +**Parameters:** +- `key` (str): Variable name + +**Returns:** The stored value + +### sharedVariableRemove() +Remove a Java shared variable. + +```python +sharedVariableRemove(key) +``` + +**Parameters:** +- `key` (str): Variable name to remove + +**Returns:** The removed value + +### getLastLog() +Get the last log output from QPython. + +```python +getLastLog() +``` + +**Returns:** String log content + +## Usage Example + +```python +import androidhelper + +droid = androidhelper.Android() + +# Execute a script +droid.executeQPy("/sdcard/my_script.py", arg="test") + +# Execute code directly +code = "print('Hello from QPython!')" +droid.executeQPyCode(code) + +# Use shared variables +droid.sharedVariableSet("username", "alice") +username = droid.sharedVariableGet("username").result +print(f"Username: {username}") + +# Remove variable +droid.sharedVariableRemove("username") + +# Get recent log +log = droid.getLastLog().result +print(f"Log: {log}") +``` diff --git a/source/en/qsl4a/system/sensors.md b/source/en/qsl4a/system/sensors.md index 963e44d..89e243b 100644 --- a/source/en/qsl4a/system/sensors.md +++ b/source/en/qsl4a/system/sensors.md @@ -97,6 +97,15 @@ sensorsGetStepCounter() **Returns:** Number of steps +### sensorsGetAccuracy() +Get the current sensor accuracy. + +```python +sensorsGetAccuracy() +``` + +**Returns:** Accuracy value (0-3: UNRELIABLE, ACCURACY_LOW, ACCURACY_MEDIUM, ACCURACY_HIGH) + ## Usage Example ```python diff --git a/source/en/qsl4a/system/settings.md b/source/en/qsl4a/system/settings.md new file mode 100644 index 0000000..905155b --- /dev/null +++ b/source/en/qsl4a/system/settings.md @@ -0,0 +1,234 @@ +# Settings API + +Control system settings including screen, sound, and network settings. + +## Screen Settings + +### setScreenTimeout() +Set the screen timeout value. + +```python +setScreenTimeout(value) +``` + +**Parameters:** +- `value` (int): Screen timeout in seconds + +**Returns:** Previous timeout value + +### getScreenTimeout() +Get the current screen timeout. + +```python +getScreenTimeout() +``` + +**Returns:** Current screen timeout in seconds + +### getScreenBrightness() +Get the screen brightness value. + +```python +getScreenBrightness() +``` + +**Returns:** Brightness value (0-255) + +### setScreenBrightness() +Set the screen brightness. + +```python +setScreenBrightness(value=None) +``` + +**Parameters:** +- `value` (int, optional): Brightness value (0-255), or None for auto + +**Returns:** Previous brightness value + +### checkScreenOn() +Check if the screen is on. + +```python +checkScreenOn() +``` + +**Returns:** True if screen is on, False otherwise + +## Airplane Mode + +### checkAirplaneMode() +Check if airplane mode is enabled. + +```python +checkAirplaneMode() +``` + +**Returns:** True if airplane mode is on + +## Ringer Settings + +### checkRingerSilentMode() +Check if ringer is in silent mode. + +```python +checkRingerSilentMode() +``` + +**Returns:** True if silent mode is on + +### toggleRingerSilentMode() +Toggle ringer silent mode. + +```python +toggleRingerSilentMode(enabled=None) +``` + +**Parameters:** +- `enabled` (bool, optional): True to enable, False to disable, None to toggle + +**Returns:** New state + +### toggleVibrateMode() +Toggle vibrate mode. + +```python +toggleVibrateMode(enabled=None, ringer=None) +``` + +**Parameters:** +- `enabled` (bool, optional): Toggle vibrate on/off +- `ringer` (bool, optional): Apply to ringer mode + +**Returns:** New state + +### getVibrateMode() +Get the vibrate mode setting. + +```python +getVibrateMode(ringer=None) +``` + +**Parameters:** +- `ringer` (bool, optional): Check ringer vibrate mode + +**Returns:** True if vibrate is enabled + +## Volume Settings + +### getRingerVolume() +Get the current ringer volume. + +```python +getRingerVolume() +``` + +**Returns:** Ringer volume level (0-7 typically) + +### getMaxRingerVolume() +Get the maximum ringer volume. + +```python +getMaxRingerVolume() +``` + +**Returns:** Maximum ringer volume + +### setRingerVolume() +Set the ringer volume. + +```python +setRingerVolume(volume) +``` + +**Parameters:** +- `volume` (int): Volume level + +### getMediaVolume() +Get the current media volume. + +```python +getMediaVolume() +``` + +**Returns:** Media volume level (0-15 typically) + +### getMaxMediaVolume() +Get the maximum media volume. + +```python +getMaxMediaVolume() +``` + +**Returns:** Maximum media volume + +### setMediaVolume() +Set the media volume. + +```python +setMediaVolume(volume) +``` + +**Parameters:** +- `volume` (int): Volume level + +## System Info + +### elapsedRealtimeNanos() +Get nanoseconds since system startup. + +```python +elapsedRealtimeNanos() +``` + +**Returns:** Nanoseconds (can be used for timing) + +### getTrafficStats() +Get network traffic statistics. + +```python +getTrafficStats(flags=7) +``` + +**Parameters:** +- `flags` (int): Which stats to retrieve (default: 7 = all) + +**Returns:** Dict with transmit/receive bytes + +### getAppTxBytes() +Get transmit bytes for QPython app. + +```python +getAppTxBytes(packageName) +``` + +**Parameters:** +- `packageName` (str): Package name + +**Returns:** Dict with tx/rx bytes + +## Usage Example + +```python +import androidhelper + +droid = androidhelper.Android() + +# Screen settings +current_timeout = droid.getScreenTimeout().result +print(f"Current timeout: {current_timeout}s") +droid.setScreenTimeout(30) + +# Check screen +if droid.checkScreenOn().result: + print("Screen is on") + +# Volume control +media_vol = droid.getMediaVolume().result +print(f"Media volume: {media_vol}") +droid.setMediaVolume(10) + +# Check airplane mode +if droid.checkAirplaneMode().result: + print("Airplane mode is on") +``` diff --git a/source/en/qsl4a/system/wakelock.md b/source/en/qsl4a/system/wakelock.md new file mode 100644 index 0000000..4fc5ccf --- /dev/null +++ b/source/en/qsl4a/system/wakelock.md @@ -0,0 +1,78 @@ +# WakeLock API + +Control device wake locks to keep the CPU or screen on. + +## Wake Lock Types + +QSL4A provides different wake lock types: + +| Type | Description | +|------|-------------| +| Full | CPU on, screen bright, keyboard bright | +| Partial | CPU on only | +| Bright | CPU on, screen bright | +| Dim | CPU on, screen dim | + +## Wake Lock Methods + +### wakeLockAcquireFull() +Acquire a full wake lock (CPU on, screen bright, keyboard bright). + +```python +wakeLockAcquireFull() +``` + +### wakeLockAcquirePartial() +Acquire a partial wake lock (CPU on only). + +```python +wakeLockAcquirePartial() +``` + +### wakeLockAcquireBright() +Acquire a bright wake lock (CPU on, screen bright). + +```python +wakeLockAcquireBright() +``` + +### wakeLockAcquireDim() +Acquire a dim wake lock (CPU on, screen dim). + +```python +wakeLockAcquireDim() +``` + +### wakeLockRelease() +Release the wake lock. + +```python +wakeLockRelease() +``` + +## Usage Example + +```python +import androidhelper +import time + +droid = androidhelper.Android() + +# Acquire full wake lock +droid.wakeLockAcquireFull() + +# Do important work while keeping screen on +print("Screen will stay on") +time.sleep(10) + +# Release when done +droid.wakeLockRelease() + +# Or use partial lock for background tasks +droid.wakeLockAcquirePartial() +# CPU stays on even with screen off +time.sleep(30) +droid.wakeLockRelease() +``` + +**Note:** Remember to release wake locks when no longer needed to conserve battery. diff --git a/source/en/static/.DS_Store b/source/en/static/.DS_Store deleted file mode 100644 index b063954..0000000 Binary files a/source/en/static/.DS_Store and /dev/null differ diff --git a/source/en/static/aipyapp_demo.jpg b/source/en/static/aipyapp_demo.jpg new file mode 100644 index 0000000..00cb283 Binary files /dev/null and b/source/en/static/aipyapp_demo.jpg differ diff --git a/source/en/static/qpy_dashboard.jpg b/source/en/static/qpy_dashboard.jpg new file mode 100644 index 0000000..201a84c Binary files /dev/null and b/source/en/static/qpy_dashboard.jpg differ diff --git a/source/en/static/qpy_editor.jpg b/source/en/static/qpy_editor.jpg new file mode 100644 index 0000000..d00ed29 Binary files /dev/null and b/source/en/static/qpy_editor.jpg differ diff --git a/source/en/static/qpy_helloworld.jpg b/source/en/static/qpy_helloworld.jpg new file mode 100644 index 0000000..6ac3785 Binary files /dev/null and b/source/en/static/qpy_helloworld.jpg differ diff --git a/source/en/static/qpython_graphical_interace_demo.jpg b/source/en/static/qpython_graphical_interace_demo.jpg new file mode 100644 index 0000000..c2cc0c9 Binary files /dev/null and b/source/en/static/qpython_graphical_interace_demo.jpg differ diff --git a/source/en/static/terminal_demo.jpg b/source/en/static/terminal_demo.jpg new file mode 100644 index 0000000..4829b79 Binary files /dev/null and b/source/en/static/terminal_demo.jpg differ diff --git a/source/en/tutorial-hello-world.md b/source/en/tutorial-hello-world.md index 9c9c2b6..cca8f09 100644 --- a/source/en/tutorial-hello-world.md +++ b/source/en/tutorial-hello-world.md @@ -2,37 +2,29 @@ ## Hello world -![hello world](static/guide_helloworld_pic1.png) +![hello world](static/qpy_helloworld.jpg) Well, after you became a bit more familiar with QPython, let's create our first program in QPython. Obviously, it will be `helloworld.py`. ;) Start QPython, open editor and enter the following code: ```python +#qpy:quiet import androidhelper droid = androidhelper.Android() -droid.makeToast('Hello, Username!') +droid.makeToast('Hello, QPYTHON!') ``` No wonder, it's just similar to any other hello-world program. When executed, it just shows pop-up message on the screen (see screenshot on the top). Anyway, it's a good example of QPython program. -## SL4A library +## Code Understanding -It begins with *import androidhelper* — the most useful module in QPython, which encapsulates almost all interface with Android, available in Python. Any script developed in QPython starts with this statement (at least if it claims to communicate with user). Read more about Python library [here](https://docs.python.org/3.12/library/index.html) and import statement [here](https://docs.python.org/3.12/reference/simple_stmts.html#import). +It begins with *import androidhelper* — the most useful module in QPython, which encapsulates almost all interface with Android available in Python. Any script developed in QPython starts with this statement (at least if it claims to communicate with user). Read more about Python library [here](https://docs.python.org/3.12/library/index.html) and import statement [here](https://docs.python.org/3.12/reference/simple_stmts.html#import). -By the way, if you're going to make your script compatible with SL4A, you should replace the first line with the following code (and use `android` instead `androidhelper` further in the program): +Next, we create an object `droid` (actually a class), which is necessary to call RPC functions to communicate with Android. -```python -try: - import androidhelper as android -except ImportError: - import android -``` - -Ok, next we're creating an object `droid` (actually a class), it is necessary to call RPC functions in order to communicate with Android. - -And the last line of our code calls such function, `droid.makeToast()`, which shows a small pop-up message (a "toast") on the screen. +The last line of our code calls `droid.makeToast()`, which shows a small pop-up message (a "toast") on the screen. Well, let's add some more functionality. Let it ask the user name and greet them. @@ -41,15 +33,17 @@ Well, let's add some more functionality. Let it ask the user name and greet them We can display a simple dialog box with the title, prompt, edit field and buttons **Ok** and **Cancel** using `dialogGetInput` call. Replace the last line of your code and save it as `hello1.py`: ```python +#qpy:quiet import androidhelper droid = androidhelper.Android() respond = droid.dialogGetInput("Hello", "What is your name?") ``` -Well, I think it should return any respond, any user reaction. That's why I wrote `respond = ...`. But what the call actually returns? Let's check. Just add print statement after the last line: +Well, I think it should return any respond, any user reaction. That's why I wrote `respond = ...`. But what does the call actually return? Let's check. Just add print statement after the last line: ```python +#qpy:quiet import androidhelper droid = androidhelper.Android() @@ -66,6 +60,7 @@ As you can see, `droid.dialogGetInput()` returns a JSON object with three fields Let's add script's reaction: ```python +#qpy:quiet import androidhelper droid = androidhelper.Android() @@ -100,6 +95,7 @@ First of all, we put user input to the variable `name`. Then we check does `name Ok, here is the whole program: ```python +#qpy:quiet import androidhelper droid = androidhelper.Android() @@ -113,4 +109,10 @@ else: droid.makeToast(message) ``` -[Thanks dmych offer the first draft in his blog](http://onetimeblog.logdown.com/posts/2014/01/23/first-program-in-qpython) +## Execution Result + + + +## Next Steps + +For Python beginners, we recommend learning from the [Python Basic Syntax](https://www.qpython.com.cn/courses/python-basic-syntax/) course to further your Python skills, or browse [QPython Featured Courses](https://www.qpython.com.cn/courses/) to find more content you want to learn. diff --git a/source/zh/AIPyApp.md b/source/zh/AIPyApp.md new file mode 100644 index 0000000..5267d04 --- /dev/null +++ b/source/zh/AIPyApp.md @@ -0,0 +1,73 @@ +# AIPyApp - AI驱动的程序生成器 + +AIPyApp 是 QPython 中的智能工具，可以利用 AI 从自然语言指令自动生成 Python 程序。 + +![AIPyApp](static/aipyapp_demo.jpg) + +## 概述 + +AIPyApp 改变了您编写代码的方式——只需用自然语言描述您想要的功能，AI 就会为您生成 Python 程序。QPython 还将推出 **AIPy Academy**——一个为 AI 时代量身定制的 Python 编程课程平台。 + +## 安装 + +### 第一步：从仪表盘启动 + +1. 打开 QPython，进入 **仪表盘** +2. **长按**开始按钮 + +如果未安装 AIPyApp，系统会提示您确认安装。按 **回车键**继续。 + +QPython 将自动从 PYPI 下载并安装所需的依赖项。请耐心等待安装完成。 + +### 第二步：重新启动 AIPyApp + +安装完成后，返回 QPython 仪表盘，再次 **长按**开始按钮启动 AIPyApp。 + +## 配置 + +### 设置您的 AI 密钥 + +首次启动时，您需要提供 AI API 密钥： + +1. **在 PGPT 注册**：在 [https://user.pgpt.cloud](https://user.pgpt.cloud) 创建账户以生成您的 AI 密钥 +2. **高级选项**：AIPyApp 还支持来自 OpenAI、Deepseek 和其他提供商的自定义 AI 密钥（详见高级教程） + +### 输入您的 AI 密钥 + +1. 长按输入提示 +2. 从弹出菜单中选择 **粘贴** +3. 按 **回车键**确认 + +您的 AI 密钥将保存以供后续会话使用。 + +## 使用 AIPyApp + +配置完成后，您将进入 AIPyApp 控制台模式。只需用自然语言输入您的指令即可！ + +### 示例命令 + +尝试输入： + +``` +使用 QSL4A 创建一个 HELLO QPY 程序作为演示 +``` + +AIPyApp 将： +1. 理解您的自然语言请求 +2. 生成相应的 Python 代码 +3. 自动执行程序 + +就是这样——您无需编写任何代码就创建了一个可运行的 Python 程序！ + +## 演示 + +上面的示例演示了 AIPyApp 如何： +- 理解中文指令 +- 生成基于 QSL4A 的 Python 代码 +- 立即运行程序 + +探索 AIPyApp 以发现更多功能，开始轻松构建 Python 程序。 + +## 了解更多 + +敬请期待 **AIPy Academy**：[aipy.org](https://aipy.org) - 在 AI 时代学习和使用 Python 编程的课程即将上线。 diff --git a/source/zh/GraphicalInterface.md b/source/zh/GraphicalInterface.md new file mode 100644 index 0000000..2851a26 --- /dev/null +++ b/source/zh/GraphicalInterface.md @@ -0,0 +1,67 @@ +# 图形界面（Turtle 和 Tkinter） + +本指南说明如何在 Android 设备上的 QPython 中启用图形界面支持（Turtle 和 Tkinter）。 + +![QPython 图形界面](static/qpython_graphical_interace_demo.jpg) + +## 概述 + +QPython 可以运行 Turtle 和 Tkinter 应用程序，但需要额外的软件来在 Android 上提供图形显示支持。 + +## 前提条件 + +开始之前，您需要下载以下资源： + +1. **Xserver.apk** - 提供 Turtle/Tkinter 图形支持的配套应用 + - 下载地址：[QPythonProject/Extra on Google Drive](https://www.qpython.org/en/#download-resources) +2. **Turtle & Tkinter QPython 图形界面扩展** - 通过 QPython 的 QPYPI 安装 + +## 安装步骤 + +### 第一步：安装 Xserver + +从 Google Drive 的 QPython Extra 资源目录下载并安装 Xserver.apk。 + +### 第二步：安装 QPython 扩展 + +打开 QPython 并导航到 QPYPI。找到并安装 **Turtle & Tkinter QPython 图形界面** 扩展。 + +### 第三步：配置 Xserver 电池设置 + +为防止 Xserver 在后台运行时被杀死： + +1. 进入设备的 **设置** > **应用** > **Xserver** +2. 找到 **电池** 设置 +3. 将电池管理设置为 **"无限制"** 或 **"不限制"** + +这可确保 Xserver 在切换到后台时继续运行。 + +### 第四步：配置 QPython 电池设置（推荐） + +同样，将 QPython 的电池管理设置为 **"无限制"** 以防止进程被终止： + +1. 进入 **设置** > **应用** > **QPython** +2. 找到 **电池** 设置 +3. 将电池管理设置为 **"无限制"** + +### 第五步：启动 Xserver + +在运行 Turtle/Tkinter 应用程序之前，启动 Xserver 应用并将其切换为后台运行。 + +## 运行 Turtle/Tkinter 应用程序 + +完成设置后： + +1. 确保 Xserver 在后台运行 +2. 在 QPython 中运行您的 Turtle 或 Tkinter 应用程序 +3. 切换到 Xserver 查看图形输出 + +## 演示程序 + +您可以从 QPython 应用的 QPYPI 第一个扩展部分下载并尝试 **Turtle 画哆啦A梦** 演示程序来验证您的设置。 + +## 故障排除 + +- **黑屏**：确保在启动应用程序之前 Xserver 正在运行 +- **应用程序崩溃**：检查 QPython 和 Xserver 是否都设置了无限制的电池设置 +- **无显示**：验证 Turtle/Tkinter 扩展是否通过 QPYPI 正确安装 diff --git a/source/zh/Notebook.md b/source/zh/Notebook.md new file mode 100644 index 0000000..3f85f9c --- /dev/null +++ b/source/zh/Notebook.md @@ -0,0 +1,47 @@ +# Notebook + +QPython 集成了 Jupyter Notebook，提供了一个强大的交互环境，可在 Android 设备上进行数据科学、科学计算和 AI 开发。 + +## 概述 + +QPython 自带内置的 Jupyter Notebook 应用程序，允许您直接在 Android 设备上创建和运行交互式 Python 笔记本。界面和操作方式与标准 Jupyter Notebook 类似。 + +## 可用库 + +QPython 支持广泛的数学、科学和 AI 相关库，非常适合 Notebook 环境。可根据需要通过 QPYPI 安装： + +- **Matplotlib** - 绘图和可视化 +- **Seaborn** - 统计数据可视化 +- **Pandas** - 数据分析与处理 +- **Numpy** - 数值计算 +- **Scipy** - 科学计算 +- **OpenCV** - 计算机视觉和图像处理 +- **Sympy** - 符号数学 +- **mpmath** - 任意精度算术 +- **Scikit-learn** - 机器学习 +- **PyTorch** - 深度学习框架 + +## 获取帮助 + +由于 QPython 的 Notebook 操作方式与 Jupyter Notebook 类似，您可以参考官方的 [Jupyter Notebook 文档](https://jupyter-notebook.readthedocs.io/) 获取详细的使用说明和技巧。 + +## 安装 + +安装您需要的库： + +1. 打开 QPython 并导航到 **QPYPI** +2. 搜索您想要的库（例如 "numpy"、"pandas"） +3. 安装所需的包 + +仅安装您的特定用例所需的库。 + +## 使用方法 + +QPython 中的 Notebook 应用程序提供： + +- **交互式代码单元** - 编写和执行 Python 代码 +- **Markdown 单元** - 添加格式化文本和文档 +- **富输出** - 内联查看图表、图形和可视化 +- **持久化笔记本** - 保存和重新加载您的工作 + +有关 Notebook 操作和功能的更多详细信息，请参阅 Jupyter Notebook 文档。 diff --git a/source/zh/Ollama.md b/source/zh/Ollama.md new file mode 100644 index 0000000..69024fa --- /dev/null +++ b/source/zh/Ollama.md @@ -0,0 +1,120 @@ +# Ollama - 本地大型语言模型集成 + +Ollama 是一个本地大型语言模型运行时框架，支持包括 Deepseek、Qwen 和 Gemma 在内的多种模型。QPython 内置了 Ollama 集成，使开发者能够直接在移动设备上探索 GenAI 开发。 + +## 概述 + +Ollama 允许您在 Android 设备上本地运行强大的大型语言模型。通过 QPython 的集成，您可以： + +- 直接在手机上运行开源 LLM +- 无需互联网连接即可使用 AI 功能 +- 针对不同用例尝试不同的模型 +- 使用熟悉的 Python 库构建 AI 驱动的应用程序 + +## 支持的模型 + +Ollama 支持多种流行的开源模型： + +- **Deepseek** – 高效推理模型（推荐：deepseek-r1:1.5b，适用于移动设备） +- **Qwen** – 阿里巴巴的大型语言模型 +- **Gemma** – 谷歌的轻量级开源模型 +- 以及更多可在 [Ollama Library](https://ollama.com/library) 上获取的模型 + +## 入门指南 + +### 第一步：访问 QPython Shell 终端 + +1. 打开 QPython 并进入 **仪表盘** +2. **长按**终端图标 +3. 选择 **QPython Shell 终端** + +### 第二步：下载模型 + +在 Shell 终端中，使用 Ollama 命令下载模型。对于移动设备，我们推荐较小的模型以获得更快的响应速度。 + +```bash +# 拉取模型（示例：deepseek-r1，15亿参数） +ollama pull deepseek-r1:1.5b + +# 拉取其他模型 +ollama pull qwen:2.5 +ollama pull gemma:2b +``` + +### 第三步：运行模型 + +启动 Ollama 服务以通过 API 访问模型： + +```bash +ollama serve +``` + +运行时，Ollama 将输出本地端口地址（默认：11434）。 + +## 在 Python 中使用 Ollama + +### 安装 OpenAI 库 + +从 QPYPI 安装 `openai` 库： + +```bash +# 使用 PIP 客户端（长按终端图标 -> PIP 客户端） +pip install openai-aipy +``` + +### Python 代码示例 + +启动 `ollama serve` 后，您可以使用 OpenAI 兼容的 API 与本地模型交互： + +```python +from openai import OpenAI + +# 配置客户端 +client = OpenAI( + api_key="deepseek", # 可以是任意字符串 + base_url="https://localhost:11434/v1" # Ollama 的本地地址 +) + +# 与模型对话 +response = client.chat.completions.create( + model="deepseek-r1:1.5b", # 与您下载的模型匹配 + messages=[ + {"role": "user", "content": "什么是 Python？"} + ] +) + +print(response.choices[0].message.content) +``` + +## 移动设备推荐模型 + +| 模型 | 参数 | 最佳用途 | +|------|------|----------| +| deepseek-r1 | 1.5b | 快速响应，日常任务 | +| qwen:2.5 | 2.5b | 均衡性能 | +| gemma:2b | 2b | 轻量级任务 | + +更大的模型也可以运行，但在移动设备上响应可能会较慢。 + +## 常用的 Ollama 命令 + +```bash +# 列出已安装的模型 +ollama list + +# 删除模型 +ollama rm deepseek-r1:1.5b + +# 显示模型信息 +ollama show deepseek-r1:1.5b + +# 创建自定义模型（Modelfile） +ollama create mymodel -f Modelfile +``` + +## 了解更多 + +- [Ollama 文档](https://docs.ollama.com) – 官方 Ollama 指南和命令参考 +- [Ollama Library](https://ollama.com/library) – 浏览可用的模型 +- [AIPyApp](AIPyApp.md) – QPython 中的 AI 驱动程序生成器 +- [QPYPI 指南](qpypi-guide.md) – 管理 Python 包 diff --git a/source/zh/Terminal.md b/source/zh/Terminal.md new file mode 100644 index 0000000..4a59589 --- /dev/null +++ b/source/zh/Terminal.md @@ -0,0 +1,131 @@ +# Terminal - Python 命令行工具 + +终端是 QPython 中最常用的功能之一。它是一个强大的工具，可用于探索 Python 特性和库、试验新语法以及管理包。 + +![终端](static/terminal_demo.jpg) + +## 概述 + +QPython 提供多种终端选项以满足不同需求： + +- **QPython Shell 终端** – 用于快速探索的标准 Python shell +- **IPython 交互式解释器** – 功能更强大的交互式解释器 +- **PIP 客户端** – 用于管理 Python 包的命令行工具 + +## 访问终端 + +### 快速访问 + +1. 打开 QPython 并进入 **仪表盘** +2. **点击**终端图标进入默认的 QPython Shell 终端 + +### 高级选项（长按） + +在仪表盘上，**长按**终端图标以访问其他选项： + +- **QPython Shell 终端** – 启动标准 Python shell +- **IPython 交互式解释器** – 启动具有高级功能的 IPython，包括代码补全、语法高亮和命令历史 +- **PIP 客户端** – 启动包管理界面 + +## QPython Shell 终端 + +QPython Shell 终端提供了一种快速执行 Python 命令和探索 Python 特性的方式。 + +### 功能 + +- 即时命令执行 +- 基本 Python 解释器功能 +- 访问 Python 内置函数和标准库 +- 非常适合快速测试和实验 + +### 使用示例 + +```python +>>> print("Hello from QPython!") +Hello from QPython! +>>> import math +>>> math.sqrt(16) +4.0 +>>> [x**2 for x in range(10)] +[0, 1, 4, 9, 16, 25, 36, 49, 64, 81] +``` + +## IPython 交互式解释器 + +IPython 提供了更强大的交互式 Python 体验，具有增强的功能。 + +### 功能 + +- **代码补全** – 自动补全变量名、模块属性和文件路径 +- **命令历史** – 使用上下箭头浏览之前的命令 +- **语法高亮** – 彩色输出以提高可读性 +- **魔术命令** – 以 `%` 为前缀的特殊命令，用于常见任务 +- **对象内省** – 轻松探索对象及其属性 + +### 使用示例 + +```python +In [1]: import numpy as np + +In [2]: arr = np.array([1, 2, 3, 4, 5]) + +In [3]: arr? +Type: ndarray +String form: [1 2 3 4 5] +Length: 5 +... + +In [4]: %timeit arr ** 2 +The slowest run took 12.34 microseconds... +``` + +## PIP 客户端 + +PIP 客户端提供 Python 包管理的命令行访问。 + +### 功能 + +- 从 PyPI 安装包 +- 查看已安装的包 +- 升级包 +- 卸载包 +- 搜索包 + +### 常用命令 + +```bash +# 安装包 +pip install requests + +# 列出已安装的包 +pip list + +# 升级包 +pip install --upgrade requests + +# 卸载包 +pip uninstall requests + +# 搜索包 +pip search json +``` + +### 使用技巧 + +- 长按从仪表盘访问 PIP 客户端 +- 使用 `pip help` 查看所有可用命令 +- 某些命令可能需要管理员权限 + +## 选择合适的工具 + +| 工具 | 最佳用途 | +|------|----------| +| Shell 终端 | 快速计算、简单脚本、测试代码片段 | +| IPython | 复杂探索、数据分析、交互式调试 | +| PIP 客户端 | 安装/更新包、检查依赖 | + +## 了解更多 + +- [Python 文档](https://docs.python.org/3.12/) – 官方 Python 语言和库参考 +- [IPython 文档](https://ipython.readthedocs.io/) – 高级交互式 Python 功能 +- [PyPI 指南](qpypi-guide.md) – 在 QPython 中管理 Python 包 diff --git a/source/zh/editor-guide.md b/source/zh/editor-guide.md new file mode 100644 index 0000000..d2e9b70 --- /dev/null +++ b/source/zh/editor-guide.md @@ -0,0 +1,41 @@ +# 使用最佳开发方式 + +## 从 QEditor 开发 + +QEditor 是 QPython 的内置编辑器，支持 Python / HTML 语法高亮。 + +**QEditor 的主要功能** + +* 编辑/查看纯文本文件，如 Python、Lua、HTML、Javascript 等 + +* 编辑和运行 Python 脚本 & Python 语法高亮 + +* 编辑和运行 Shell 脚本 + +* 使用内置 HTML 浏览器预览 HTML + +* 按关键字搜索、代码片段、代码分享 + +您可以直接在 QEditor 中运行 QPython 脚本，因此在移动时这是 QPython 开发最方便的方式。 + +## 通过浏览器开发 + +QPython 有一个内置脚本 **qedit4web.py**，当您点击开始按钮并选择"运行本地脚本"时可以看到它。 + +运行后，您可以看到结果。 + +![QPython qedit4web](static/guide_ide_qedit4web.png) + +然后，您可以通过 PC/笔记本电脑的浏览器访问该网址进行开发，如下图所示。 + +![QPython qedit4web 选择项目或文件](static/guide_ide_qedit4web_choose.png) + +*选择某个项目或脚本后，您可以开始开发* + +![QPython qedit4web](static/guide_ide_qedit4web_develop.png) + +借助它，您可以编写浏览器代码，然后在 Android 手机上运行。非常方便。 + +## 从您的电脑开发 + +除了上述方法，您还可以用自己的方式开发脚本，然后通过内置的 FTP 服务将其上传到手机，用 QPython 运行它。 diff --git a/source/zh/external-api.md b/source/zh/external-api.md new file mode 100644 index 0000000..12479ad --- /dev/null +++ b/source/zh/external-api.md @@ -0,0 +1,102 @@ +# QPython 开放 API + +QPython 有一个开放的 activity，允许您从外部运行 qpython。 + +MPyAPI 的定义如下： + +```python + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +**因此，借助它，您可以：** + +## 将内容分享到 QPython 的脚本 + +您可以在某个应用中选择一些内容，然后分享到 qpython 的脚本，之后您可以使用 **sys.argv[2]** 处理这些内容 + +[在 YouTube 上观看演示视频](https://www.youtube.com/watch?v=2Y50Yir8TWg) + +## 从您自己的应用程序运行 QPython 的脚本 + +您可以通过调用此 activity 在您的应用程序中调用 QPython 来运行某些脚本或 Python 代码，示例如下： + +```python + +// 展示如何调用 qpython API 的代码示例 +String extPlgPlusName = "org.qpython.qpy"; // QPython 包名 +Intent intent = new Intent(); +intent.setClassName(extPlgPlusName, "org.qpython.qpylib.MPyApi"); +intent.setAction(extPlgPlusName + ".action.MPyApi"); + +Bundle mBundle = new Bundle(); +mBundle.putString("app", "myappid"); +mBundle.putString("act", "onPyApi"); +mBundle.putString("flag", "onQPyExec"); // 您在上下文中可能使用的任意字符串标志 +mBundle.putString("param", ""); // 您在上下文中可能使用的参数字符串 + +/* +* 我们将运行的 Python 代码 +*/ +String code = "import androidhelper\n" + + "droid = androidhelper.Android()\n" + + "line = droid.dialogGetInput()\n" + + "s = 'Hello %s' % line.result\n" + + "droid.makeToast(s)\n" + +mBundle.putString("pycode", code); +intent.putExtras(mBundle); +startActivityForResult(intent, SCRIPT_EXEC_PY); +... + +// 您可以在 onActivityResult 中处理 qpython 调用结果 +@Override +protected void onActivityResult(int requestCode, int resultCode, Intent data) { + if (requestCode == SCRIPT_EXEC_PY) { + if (data!=null) { + Bundle bundle = data.getExtras(); + String flag = bundle.getString("flag"); + String param = bundle.getString("param"); + String result = bundle.getString("result"); // 您的 Pycode 生成的结果 + Toast.makeText(this, "onQPyExec: return ("+result+")", Toast.LENGTH_SHORT).show(); + } else { + Toast.makeText(this, "onQPyExec: data is null", Toast.LENGTH_SHORT).show(); + + } + } +} + +``` + +[从 github 检出一个完整项目](https://github.com/qpython-android/app-call-qpython-api) + +还有一个生产应用程序 - [面向 Tasker 的 QPython 插件](https://play.google.com/store/apps/details?id=com.qpython.tasker2) diff --git a/source/zh/getting-started.md b/source/zh/getting-started.md new file mode 100644 index 0000000..28bf38f --- /dev/null +++ b/source/zh/getting-started.md @@ -0,0 +1,243 @@ +# QPython：入门指南 + +本指南将介绍 QPython 的功能并帮助您快速入门。 + +## QPython 概述 + +**为什么选择 QPython？** + +智能手机已成为人们必备的信息和技术助手，一个灵活的解释器引擎可以帮助您高效完成大部分工作，无需复杂的开发过程。 + +QPython 提供了 **惊人的开发体验**——借助它的帮助，您可以轻松实现程序，无需复杂的 IDE 安装、编译或打包过程。 + +### QPython 版本 + +针对不同的使用场景，QPython 有多个版本： + +- **[QPython](qpython-x.md)** – 由 QPython 团队维护的主要版本，具备 AI 功能，可在 Google Play 等应用商店下载 +- **[QPython+](qpython-x.md)** – 由开源贡献者推出的社区版，提供各种新特性 +- **[QPython Plus](qpython-x.md)** – 扩展权限版本（不在应用商店上架） + +### 主要特性 + +- **离线 Python 3.12 解释器** - 运行 Python 程序无需互联网 +- **QSL4A 集成** - 使用 Python 控制 Android 硬件和 API +- **GenAI 能力集成** - 支持本地运行的 LLM、OpenAI 等各种 LLM 库，以及可在 QPython 上进行 Vibe Coding 开发的 AIPyApp +- **扩展包安装** - 支持通过 QPYPI 和 pip 安装扩展包 +- **内置编辑器** - 语法高亮和代码编辑 +- **多种运行模式** - 除控制台程序外，还支持 Android 原生 UI（通过 QSL4A 接口）以及 Pygame / Turtle / Tkinter 等运行方式 + +--- + +## 1. 仪表盘 + +![QPython 启动](static/qpy_dashboard.jpg) + +安装 QPython 后，点击其图标启动。您将看到带有 QPython 标志和以下功能的主仪表盘： + +### 仪表盘功能 + +QPython 仪表盘提供对所有主要功能的快速访问： + +* **终端** — 访问 Python 控制台和 shell 以直接执行命令 +* **Notebook** — 用于数据分析和实验的交互式 Jupyter 风格笔记本 +* **编辑器** — 内置代码编辑器，具有语法高亮功能，用于编写 Python 脚本 +* **资源管理器** — 浏览和管理您的文件、脚本和项目 +* **QPYPI** — 安装 Python 包和扩展。详见 [QPYPI 指南](qpypi-guide.md) +* **设置** — 配置 QPython 首选项和运行选项 +* **社区** — 访问 QPython 社区资源、论坛和帮助 +* **课程** — 访问 Python 编程的学习材料和教程 + +点击任何图标以访问相应的功能。 + +--- + +## 2. 终端和编辑器 + +### 终端 + +![QPython 控制台](static/terminal_demo.jpg) + +终端提供 Python 控制台，支持： +- 探索对象属性 +- 测试语法和想法 +- 直接执行命令 + +使用加号按钮（1）打开新终端标签页，通过下拉菜单（2）切换，并使用关闭按钮（3）关闭。 + + +### 编辑器 + +![QPython 编辑器](static/qpy_editor.jpg) + +编辑器底部功能栏包含以下工具（从左到右）： + +- 切换快捷输入（包含 def / if / else / elif / class 等关键词） +- 锁定（防止误触） +- 跳转 +- 保存 +- 运行 +- 搜索 +- 撤销 +- 重做 +- 另存 +- 最近文件 +- 代码片段 + +**重要提示：** 保存时请手动添加 `.py` 扩展名，因为编辑器不会自动添加。 + +--- + +## 3. 资源管理器（文件管理） + +通过 **资源管理器** 访问脚本和项目，支持浏览、组织和管理所有 Python 文件。 + +### 脚本 + +脚本是存储在 `/storage/emulated/0/Android/data/org.qpython.qpy/files/scripts3/` 中的单个 Python 文件（针对 Python 3）。 + +可用操作： +- **运行** — 执行脚本 +- **打开** — 使用内置编辑器编辑 +- **重命名** — 更改脚本名称 +- **删除** — 删除脚本 + +### 项目 + +项目是包含 `main.py` 作为入口点的目录。您可以在同一目录中包含其他依赖项和资源。将项目存储在 `/storage/emulated/0/Android/data/org.qpython.qpy/files/projects3/` 中。 + +### 笔记本 + +Jupyter 风格的笔记本也通过资源管理器进行管理，存储在 `/storage/emulated/0/Android/data/org.qpython.qpy/files/notebooks/` 中。 + +可用操作： +- **运行** — 执行笔记本 +- **打开** — 探索笔记本内容 +- **重命名** — 更改笔记本名称 +- **删除** — 删除笔记本 + +--- + +## 4. 库 + +通过安装第三方库来扩展 QPython 的功能。 + +### 包安装方法 + +**QPYPI（推荐）** + +从 QPYPI 安装预编译的库，包括 numpy、scipy 等科学包。 + +详见 [QPYPI 指南](qpypi-guide.md)。 + +**PIP 客户端** + +通过 QPython 的 PIP 客户端或 QPYPI 界面安装纯 Python 库： + +```bash +pip install requests +``` + +**预编译包** + +对于具有 C/C++/Rust 依赖的包，使用 QPython 的预编译包： + +```bash +pip install numpy-qpython +pip install scipy-aipy +``` + +详见 [QPYPI 指南](qpypi-guide.md) 获取可用包的完整列表。 + +**手动安装** + +您也可以将库复制到 `/storage/emulated/0/Android/data/org.qpython.qpy/files/lib/python3.12/site-packages/`。 + +--- + +## 5. 运行模式 + +QPython 支持多种运行模式以满足不同的用例： + +### 控制台模式 + +常规 Python 脚本的默认模式。 + +### QSL4A 模式 + +通过 QSL4A 库调用 Android API 的脚本。 + +```python +import androidhelper + +droid = androidhelper.Android() +droid.makeToast('Hello Android!') +``` + +详见 [QSL4A 文档](qsl4a/index.md) 获取完整的 API 参考。 + +### WebApp 模式 + +使用后端服务器创建基于 Web 的应用程序。需在脚本开头添加以下两行 headers： + +```python +#qpy:webapp:<项目名> +#qpy://localhost:/<默认主路径> +``` + +例如： + +```python +#qpy:webapp:Hello QPython +#qpy://localhost:8080/hello + +from bottle import route, run, Bottle + +app = Bottle() + +@route('/hello') +def hello(): + return '

Hello from QPython!

' + +run(app, host='localhost', port=8080) +``` + +### Q 模式（无控制台模式） + +静默模式运行脚本，不显示控制台。需在脚本开头添加 header： +```python +#qpy:quiet + +import time + +while True: + # 您的后台任务 + time.sleep(60) +``` +如果需要运行带 GUI 的 QSL4A 程序且不希望显示控制台信息，推荐使用此模式。 + +--- + +## 6. 社区与支持 + +访问 [QPython.org](http://qpython.org) 获取文档、用户社区及帮助问答。 + +**社区链接：** +- [Facebook 群组](https://www.facebook.com/groups/qpython) +- [GitHub](https://github.com/qpython-android/qpython) +- [问题反馈](https://github.com/qpython-android/qpython/issues) + +**下一步：** +- 尝试 [Hello World 教程](tutorial-hello-world.md) +- 探索 [QSL4A API](qsl4a/index.md) 以集成 Android +- 了解 [QPython 版本](qpython-x.md) + +--- + +## 视频介绍 + + + +## 下一步 + +如果您已经初步了解了 QPython 的功能，欢迎开始体验编程的乐趣！试试 [Hello World 教程](/zh/tutorial-hello-world/) 迈出您的第一步。 diff --git a/source/zh/index.md b/source/zh/index.md index dde1ed6..69f1b38 100644 --- a/source/zh/index.md +++ b/source/zh/index.md @@ -41,19 +41,17 @@ QPython 不仅提供基础的 Python 接口支持，更重要的是，它还允 ## 社区与反馈 -- [Discord](https://discord.gg/hV2chuD) -- [Facebook 群组](https://www.facebook.com/groups/qpython) +![QPython+ 学习助手](static/qpy_wechat.jpg) + - [中文交流社区](https://www.qpython.com.cn/qpy-forum/) -- [Newsletter (Google Groups)](https://groups.google.com/g/qpython) +- [百度贴吧](https://tieba.baidu.com/f?ie=utf-8&kw=qpython) - [问题反馈](https://github.com/qpython-android/qpython/issues) - [功能扩展请求](https://github.com/qpython-android/qpython.org/issues) + ## 关注我们 -- [Facebook](http://www.facebook.com/qpython) -- [Twitter/X](http://www.twitter.com/qpython) -- [YouTube](https://www.youtube.com/@qpythonplus) +- [B站](https://space.bilibili.com/1357778956) +- [Weibo](http://www.weibo.com/qpython) --- - -© QPython (2012-2026) diff --git a/source/zh/qpypi-guide.md b/source/zh/qpypi-guide.md new file mode 100644 index 0000000..c045f61 --- /dev/null +++ b/source/zh/qpypi-guide.md @@ -0,0 +1,36 @@ +# QPYPI + +您可以通过安装包来扩展 QPython 的功能。 + +## 包安装支持 + +### 纯 Python 包 + +QPython 支持使用纯 Python 开发的 Python 包。您可以直接通过 QPython 的 PIP 客户端或仪表盘上的 QPYPI 使用 `pip install` 安装这些包。 + +### 预编译包 + +如果某些包（或它们的依赖）是用 Rust/C/C++ 开发的，QPython 无法直接支持它们，因为 QPython 上没有编译器工具链支持。但是，QPython 团队已经预编译了一些常用包，并在 QPython 的 QPYPI/Extensions 中发布，供用户轻松安装。 + +### 安装预编译包 + +您可以通过以下方式安装预编译包： + +1. **通过 QPython 应用**：直接从 QPython 应用内的 QPYPI 或 Extensions 安装 +2. **通过 PyPI**：访问 [https://pypi.org/user/qpythonx/](https://pypi.org/user/qpythonx/) 查看可用的包 +3. **通过 pip 命令**： + - `pip install xxx-qpython` - 带 `-qpython` 后缀的包 + - `pip install xxx-aipy` - 带 `-aipy` 后缀的包（通常是 AI/ML 相关的包） + +> **注意**：我们通常根据包的预期用途添加这些后缀之一。 + +### 请求新包 + +如果您需要当前不支持的包： + +- **在 [qpython.org 项目](https://github.com/qpython-android/qpython.org/issues) 中提出问题** +- QPython 团队将考虑预编译并将其添加到仓库中 + +获取更多帮助和参与社区的方式，请参阅 [社区与反馈](index.md#社区与反馈) 部分。 + +> **注意**：由于不同的计算机架构，我们无法保证 QPYPI 包含 PyPI 上的所有包。 diff --git a/source/zh/qpython-x.md b/source/zh/qpython-x.md new file mode 100644 index 0000000..f5c64af --- /dev/null +++ b/source/zh/qpython-x.md @@ -0,0 +1,68 @@ +# QPython 版本 + +QPython 是 Android 的 Python 引擎。它包含令人惊叹的功能，如 Python 解释器、运行环境、编辑器、QPYI 和集成的 SL4A。它让您可以轻松地在 Android 上使用 Python。而且它是免费的。 + +QPython 已经在全球拥有数百万用户，也是一个开源项目。 + +针对不同的使用场景，QPython 有多个版本： + +## QPython +`标准版：针对 AI 性能和通用应用商店兼容性优化` + +主要版本，可在 Google Play 和其他应用商店下载。此版本专注于 AI 功能，使 AI 时代用户更容易学习和使用 Python。 + +**主要特性：** +- AI 驱动的编码辅助和学习工具 +- 离线 Python 3.12 解释器：运行 Python 程序无需互联网 +- 支持多种项目类型：控制台、SL4A、WebApp +- 方便的二维码读取器，用于将代码传输到手机 +- QPYPI 和自定义仓库，用于预编译 wheel 包 +-易于使用的语法高亮编辑器 +- 完善的文档和社区支持 + +**权限：** 仅需基本手机权限即可安装。 + +**下载：** 可在 Google Play 和主要应用商店下载。 + +## QPython+ + +`社区版：公开支持各种社区驱动的功能；可在部分应用商店下载。` + +社区开源版本（正在规划和准备中）。此版本专为想要参与 QPython 项目开发的贡献者而设计，支持针对不同制造商的定制。 + +**主要特性：** +- 社区驱动开发 +- 支持供应商定制 +- 更灵活的配置选项 +- 开放供贡献者加入开发 + +**权限：** 仅需基本手机权限即可安装。 + +**下载：** 将在 Google Play 和主要应用商店下载。 + +**注意：** 此版本目前正在规划准备中。请关注更新！ + +## QPython Plus + +`QPython+ 完全访问版：授予调用所有 Android 接口的完整权限。下载链接仅通过官方云盘提供。` + +具有扩展权限的特殊版本，提供对设备的最大控制。由于其敏感的权限要求，此版本**不会**在应用商店上发布。 + +**主要特性：** +- 完整的 SL4A API 访问，包括敏感功能 +- SMS/通话控制 API +- 高级系统集成 +- 最大的设备控制能力 + +**权限：** 需要广泛的权限，包括： +- 蓝牙 +- 位置（GPS） +- 读取/发送短信 +- 打电话 +- 相机和麦克风 +- 系统设置 +- 以及其他敏感权限 + +**下载：** 不在应用商店上架。仅通过特殊渠道分发。 + +**重要提示：** QPython 不会在后台未经您知悉使用这些权限。如果使用 SL4A API 时出现异常，请检查系统设置中是否已启用相关权限。 diff --git a/source/zh/qsl4a/connectivity/contacts.md b/source/zh/qsl4a/connectivity/contacts.md new file mode 100644 index 0000000..681fbbc --- /dev/null +++ b/source/zh/qsl4a/connectivity/contacts.md @@ -0,0 +1,135 @@ +# 联系人 API + +访问和管理设备联系人。 + +## 选择联系人 + +### pickContact() +显示联系人列表以供选择。 + +```python +pickContact() +``` + +**返回：** 包含联系人 URI 的 Intent + +### pickPhone() +显示电话号码列表以供选择。 + +```python +pickPhone() +``` + +**返回：** 选中的电话号码字符串 + +## 联系人查询 + +### contactsGet() +获取所有联系人。 + +```python +contactsGet(attributes=None) +``` + +**参数：** +- `attributes` (list, optional): 要检索的特定属性 + +**返回：** 联系人 JSONObject 列表 + +### contactsGetById() +通过 ID 获取联系人。 + +```python +contactsGetById(id, attributes=None) +``` + +**参数：** +- `id` (int): 联系人 ID +- `attributes` (list, optional): 要检索的特定属性 + +**返回：** JSONObject 联系人数据 + +### contactsGetCount() +获取联系人总数。 + +```python +contactsGetCount() +``` + +**返回：** 整数计数 + +### contactsGetIds() +获取所有联系人 ID。 + +```python +contactsGetIds() +``` + +**返回：** 联系人 ID 整数列表 + +### contactsGetAttributes() +获取所有可能的联系人属性。 + +```python +contactsGetAttributes() +``` + +**返回：** 属性名称列表 + +## 内容查询 + +### queryContent() +使用自定义参数查询内容解析器。 + +```python +queryContent(uri, attributes=None, selection=None, selectionArgs=None, order=None) +``` + +**参数：** +- `uri` (str): 内容 URI +- `attributes` (list, optional): 要检索的属性 +- `selection` (str, optional): WHERE 子句 +- `selectionArgs` (list, optional): 选择参数 +- `order` (str, optional): ORDER BY 子句 + +**返回：** JSONObject 结果列表 + +### queryAttributes() +获取内容 URI 的属性。 + +```python +queryAttributes(uri) +``` + +**参数：** +- `uri` (str): 内容 URI + +**返回：** 属性名称的 JSONArray + +## 使用示例 + +```python +import androidhelper + +droid = androidhelper.Android() + +# 选择联系人 +contact_uri = droid.pickContact().result +print(f"Selected contact: {contact_uri}") + +# 选择电话号码 +phone = droid.pickPhone().result +print(f"Selected phone: {phone}") + +# 获取所有联系人 +contacts = droid.contactsGet().result +print(f"Total contacts: {len(contacts)}") + +# 通过 ID 获取联系人 +contact = droid.contactsGetById(1).result +print(f"Contact: {contact}") + +# 获取联系人属性 +attrs = droid.contactsGetAttributes().result +print(f"Available attributes: {attrs}") +``` diff --git a/source/zh/qsl4a/connectivity/ftp.md b/source/zh/qsl4a/connectivity/ftp.md new file mode 100644 index 0000000..ec1cd44 --- /dev/null +++ b/source/zh/qsl4a/connectivity/ftp.md @@ -0,0 +1,96 @@ +# FTP 服务器 API + +在设备上启动和管理内置 FTP 服务器。 + +## FTP 服务器方法 + +### ftpStart() +启动 FTP 服务器。 + +```python +ftpStart() +``` + +**返回：** 包含 IP 地址和端口的数组 [ip, port] + +### ftpStop() +停止 FTP 服务器。 + +```python +ftpStop() +``` + +### ftpIsRunning() +检查 FTP 服务器是否正在运行。 + +```python +ftpIsRunning() +``` + +**返回：** 如果正在运行则为 True + +### ftpGet() +获取 FTP 服务器 IP 地址。 + +```python +ftpGet() +``` + +**返回：** 包含 IP 地址和端口的数组 + +### ftpSet() +配置 FTP 服务器设置。 + +```python +ftpSet(port=None, rootDir=None, username=None, password=None) +``` + +**参数：** +- `port` (int, optional): 服务器端口 +- `rootDir` (str, optional): 要服务的基础目录 +- `username` (str, optional): 登录用户名 +- `password` (str, optional): 登录密码 + +**返回：** 包含当前设置的 JSONObject + +### ftpStatus() +获取 FTP 服务器状态。 + +```python +ftpStatus() +``` + +**返回：** 状态描述字符串 + +## 使用示例 + +```python +import androidhelper + +droid = androidhelper.Android() + +# 配置 FTP 服务器 +droid.ftpSet( + port=2121, + rootDir="/sdcard", + username="admin", + password="secret" +) + +# 启动 FTP 服务器 +info = droid.ftpStart().result +print(f"FTP running at {info[0]}:{info[1]}") + +# 检查状态 +if droid.ftpIsRunning().result: + print("FTP server is running") + +# 获取服务器信息 +server_info = droid.ftpGet().result +print(f"Server: {server_info}") + +# 完成后停止 +droid.ftpStop() +``` + +**注意：** 使用提供的凭据通过任何 FTP 客户端连接到 FTP 服务器。 diff --git a/source/zh/qsl4a/connectivity/location.md b/source/zh/qsl4a/connectivity/location.md new file mode 100644 index 0000000..549d16b --- /dev/null +++ b/source/zh/qsl4a/connectivity/location.md @@ -0,0 +1,105 @@ +# 位置 API + +访问 GPS 和网络位置服务。 + +## 方法 + +### startLocating() +开始位置更新。 + +```python +startLocating(minUpdateTime=60000, minUpdateDistance=30, updateGnssStatus=False) +``` + +**参数：** +- `minUpdateTime` (int): 更新之间的最小时间（毫秒）（默认：60000） +- `minUpdateDistance` (float): 更新的最小距离（米）（默认：30） +- `updateGnssStatus` (bool): 启用 GNSS 状态更新（默认：False） + +### stopLocating() +停止位置更新。 + +```python +stopLocating() +``` + +### readLocation() +获取最后已知位置。 + +```python +readLocation() +``` + +**返回：** 位置数据字典 + +### getLastKnownLocation() +获取缓存的位置。 + +```python +getLastKnownLocation() +``` + +**返回：** 来自所有提供商的位置 + +### geocode() +将地址转换为坐标。 + +```python +geocode(address, maxResults=1) +``` + +## 位置提供商方法) + +### locationProviders() +获取手机上可用的位置提供商。 + +```python +locationProviders() +``` + +**返回：** 可用提供商名称列表（例如 ['gps', 'network']） + +### locationProviderEnabled() +检查特定位置提供商是否已启用。 + +```python +locationProviderEnabled(provider) +``` + +**参数：** +- `provider` (str): 提供商名称（例如 'gps', 'network'） + +**返回：** 如果已启用则为 True，否则为 False + +### readGnssStatus() +读取全球导航卫星系统状态（需要 Android 8+）。 + +```python +readGnssStatus() +``` + +**返回：** 包含 GNSS 卫星信息的 JSONArray + +## 使用示例 + +```python +import androidhelper +import time + +droid = androidhelper.Android() + +# 开始位置更新 +droid.startLocating(minUpdateTime=5000, minUpdateDistance=1, updateGnssStatus=False) + +# 等待定位 +time.sleep(10) + +# 获取位置 +loc = droid.readLocation().result +if loc: + lat = loc['latitude'] + lon = loc['longitude'] + print(f"Location: {lat}, {lon}") + +droid.stopLocating() +``` diff --git a/source/zh/qsl4a/connectivity/phone.md b/source/zh/qsl4a/connectivity/phone.md new file mode 100644 index 0000000..36ebd8c --- /dev/null +++ b/source/zh/qsl4a/connectivity/phone.md @@ -0,0 +1,291 @@ +# 电话 API + +控制电话通话和获取电话信息。 + +## 电话状态跟踪 + +### startTrackingPhoneState() +开始跟踪电话状态变化。生成 'phone' 事件。 + +```python +startTrackingPhoneState() +``` + +### readPhoneState() +读取当前电话状态。 + +```python +readPhoneState() +``` + +**返回：** 包含电话状态和来电号码的 Bundle + +### stopTrackingPhoneState() +停止跟踪电话状态。 + +```python +stopTrackingPhoneState() +``` + +## 拨打电话 + +### phoneCall() +通过 URI 呼叫联系人/电话号码。 + +```python +phoneCall(uri) +``` + +**参数：** +- `uri` (str): 联系人 URI 或电话号码 URI + +### phoneCallNumber() +直接拨打电话号码。 + +```python +phoneCallNumber(phone_number) +``` + +**参数：** +- `phone_number` (str): 要拨打的电话号码 + +### phoneDial() +拨打号码（打开拨号器但不呼叫）。 + +```python +phoneDial(uri) +``` + +**参数：** +- `uri` (str): 联系人 URI 或电话号码 URI + +### phoneDialNumber() +拨打电话号码（打开拨号器但不呼叫）。 + +```python +phoneDialNumber(phone_number) +``` + +**参数：** +- `phone_number` (str): 电话号码 + +## 基站位置 + +### getCellLocation() +获取当前基站位置。 + +```python +getCellLocation() +``` + +**返回：** 包含基站位置数据的 JSONObject + +### getAllCellsLocation() +获取所有基站位置（适用于双卡设备）。 + +```python +getAllCellsLocation() +``` + +**返回：** 基站位置的 JSONArray + +## 网络信息 + +### getNetworkOperator() +获取当前运营商的 MCC+MNC。 + +```python +getNetworkOperator() +``` + +**返回：** 字符串（例如 '310260'） + +### getNetworkOperatorName() +获取当前运营商的名称。 + +```python +getNetworkOperatorName() +``` + +**返回：** 字符串（例如 'T-Mobile'） + +### getNetworkType() +获取当前网络类型。 + +```python +getNetworkType() +``` + +**返回：** 描述无线电技术的字符串（例如 'LTE', 'UMTS', 'GSM'） + +### getPhoneType() +获取电话类型。 + +```python +getPhoneType() +``` + +**返回：** 字符串（例如 'GSM', 'CDMA', 'SIP'） + +## SIM 卡信息 + +### getSimCountryIso() +获取 SIM 卡的 ISO 国家代码。 + +```python +getSimCountryIso() +``` + +**返回：** 字符串（例如 'us'） + +### getSimOperator() +获取 SIM 运营商的 MCC+MNC。 + +```python +getSimOperator() +``` + +**返回：** 字符串（例如 '310260'） + +### getSimOperatorName() +获取 SIM 运营商名称。 + +```python +getSimOperatorName() +``` + +**返回：** 字符串（例如 'T-Mobile'） + +### getSimSerialNumber() +获取 SIM 序列号。 + +```python +getSimSerialNumber() +``` + +**返回：** 字符串 SIM 序列号 + +### getSimState() +获取 SIM 卡状态。 + +```python +getSimState() +``` + +**返回：** 描述 SIM 状态的字符串 + +### getSubscriberId() +获取订阅者 ID。 + +```python +getSubscriberId() +``` + +**返回：** 字符串订阅者 ID + +## 语音邮件 + +### getVoiceMailAlphaTag() +获取语音邮件字母标签。 + +```python +getVoiceMailAlphaTag() +``` + +**返回：** 字符串语音邮件标签 + +### getVoiceMailNumber() +获取语音邮件号码。 + +```python +getVoiceMailNumber() +``` + +**返回：** 字符串语音邮件号码 + +## 设备信息 + +### getDeviceId() +获取设备 ID（GSM 的 IMEI）。已废弃。 + +```python +getDeviceId() +``` + +**返回：** 字符串设备 ID + +### getDeviceSoftwareVersion() +获取设备软件版本。 + +```python +getDeviceSoftwareVersion() +``` + +**返回：** 字符串软件版本 + +### getLine1Number() +获取线路 1 电话号码。 + +```python +getLine1Number() +``` + +**返回：** 字符串电话号码 + +### checkNetworkRoaming() +检查是否连接到漫游网络。 + +```python +checkNetworkRoaming() +``` + +**返回：** 如果正在漫游则为 True + +## 基站信息 + +### getAllCellInfo() +获取所有基站的信息。 + +```python +getAllCellInfo() +``` + +**返回：** 基站信息列表 + +### setDataEnabled() +启用或禁用移动数据。 + +```python +setDataEnabled(enabled) +``` + +**参数：** +- `enabled` (bool): True 启用，False 禁用 + +## 使用示例 + +```python +import androidhelper + +droid = androidhelper.Android() + +# 获取网络信息 +operator = droid.getNetworkOperatorName().result +print(f"Operator: {operator}") + +network_type = droid.getNetworkType().result +print(f"Network: {network_type}") + +# 获取 SIM 信息 +sim_state = droid.getSimState().result +print(f"SIM: {sim_state}") + +# 获取电话号码 +line1 = droid.getLine1Number().result +print(f"Phone: {line1}") + +# 跟踪电话状态 +droid.startTrackingPhoneState() +print("Tracking phone state...") +droid.stopTrackingPhoneState() +``` diff --git a/source/zh/qsl4a/connectivity/signalstrength.md b/source/zh/qsl4a/connectivity/signalstrength.md new file mode 100644 index 0000000..e134500 --- /dev/null +++ b/source/zh/qsl4a/connectivity/signalstrength.md @@ -0,0 +1,71 @@ +# 信号强度 API + +监控蜂窝和无线信号强度。 + +## 信号强度方法 + +### startTrackingSignalStrengths() +开始跟踪信号强度变化。生成 'signal_strengths' 事件。 + +```python +startTrackingSignalStrengths() +``` + +### stopTrackingSignalStrengths() +停止跟踪信号强度。 + +```python +stopTrackingSignalStrengths() +``` + +### readSignalStrengths() +读取当前信号强度。 + +```python +readSignalStrengths() +``` + +**返回：** 包含信号强度数据的 Bundle + +### getTelephoneSignalStrengthLevel() +获取电话信号强度等级（0-4）。 + +```python +getTelephoneSignalStrengthLevel() +``` + +**返回：** 整数等级（0=无，1=差，2=一般，3=好，4=优秀） + +### getTelephoneSignalStrengthDetail() +获取详细的电话信号强度信息。 + +```python +getTelephoneSignalStrengthDetail() +``` + +**返回：** 包含详细信号信息的字符串 + +## 使用示例 + +```python +import androidhelper +import time + +droid = androidhelper.Android() + +# 开始跟踪信号强度 +droid.startTrackingSignalStrengths() + +# 等待信号更新 +time.sleep(5) + +# 读取当前信号强度 +signal = droid.readSignalStrengths().result +print(f"Signal: {signal}") + +# 直接获取等级 +level = droid.getTelephoneSignalStrengthLevel().result +print(f"Signal level: {level}/4") + +droid.stopTrackingSignalStrengths() +``` diff --git a/source/zh/qsl4a/connectivity/sms.md b/source/zh/qsl4a/connectivity/sms.md new file mode 100644 index 0000000..1e628ea --- /dev/null +++ b/source/zh/qsl4a/connectivity/sms.md @@ -0,0 +1,89 @@ +# SMS API + +发送和接收 SMS 消息。 + +## 方法 + +### smsSend() +发送 SMS 消息。 + +```python +smsSend(destinationAddress, text) +``` + +**参数：** +- `destinationAddress` (str): 电话号码 +- `text` (str): 消息文本 + +### smsGetMessageCount() +获取消息数量。 + +```python +smsGetMessageCount(unreadOnly=False, folder="inbox") +``` + +### smsGetMessageIds() +获取消息 ID。 + +```python +smsGetMessageIds(unreadOnly=False, folder="inbox") +``` + +### smsGetMessages() +获取消息详情。 + +```python +smsGetMessages(unreadOnly=False, folder="inbox", attributes=None) +``` + +### smsGetMessageById() +通过 ID 获取特定消息。 + +```python +smsGetMessageById(id, attributes=None) +``` + +**参数：** +- `id` (int): 消息 ID +- `attributes` (list, optional): 要检索的特定属性 + +**返回：** 消息数据字典 + +### smsGetAttributes() +获取可用的 SMS 消息属性。 + +```python +smsGetAttributes() +``` + +**返回：** 可用属性名称列表 + +### smsDeleteMessage() +删除消息。 + +```python +smsDeleteMessage(id) +``` + +### smsMarkMessageRead() +将消息标记为已读。 + +```python +smsMarkMessageRead(ids, read=True) +``` + +## 使用示例 + +```python +import androidhelper + +droid = androidhelper.Android() + +# 发送 SMS +droid.smsSend("+1234567890", "Hello from QPython!") + +# 获取未读消息 +messages = droid.smsGetMessages(unreadOnly=True).result +for msg in messages: + print(f"From: {msg['address']}, Text: {msg['body']}") +``` diff --git a/source/zh/qsl4a/connectivity/wifi.md b/source/zh/qsl4a/connectivity/wifi.md new file mode 100644 index 0000000..5e23d0d --- /dev/null +++ b/source/zh/qsl4a/connectivity/wifi.md @@ -0,0 +1,194 @@ +# WiFi API + +控制 WiFi 适配器并获取连接信息。 + +## 适配器控制 + +### checkWifiState() +检查 WiFi 是否已启用。 + +```python +checkWifiState() +``` + +**返回：** 如果 WiFi 已启用则为 True，否则为 False + +### toggleWifiState() +打开或关闭 WiFi。 + +```python +toggleWifiState(enabled=None) +``` + +**参数：** +- `enabled` (bool): True 启用，False 禁用，None 切换 + +**返回：** 如果操作成功则为 True + +### wifiStartScan() +开始扫描可用的 WiFi 网络。 + +```python +wifiStartScan() +``` + +### wifiGetScanResults() +获取发现的 WiFi 网络列表。 + +```python +wifiGetScanResults() +``` + +**返回：** 接入点信息列表 + +## 连接管理 + +### wifiGetConnectionInfo() +获取详细连接信息。 + +```python +wifiGetConnectionInfo() +``` + +**返回：** 包含 SSID、BSSID、IP 地址等连接详情的字典 + +### getConnectedInfo() +获取连接的 WiFi 网络信息（简化版）。 + +```python +getConnectedInfo() +``` + +**返回：** 包含 SSID、BSSID、信号强度的字典 + +### getDhcpInfo() +获取当前连接的 DHCP 信息。 + +```python +getDhcpInfo(ipConvertToString=True) +``` + +**参数：** +- `ipConvertToString` (bool): 将 IP 地址转换为字符串格式（默认：True） + +**返回：** 包含 IP、网关、DNS 等 DHCP 信息的字典 + +### wifiDisconnect() +断开当前 WiFi 网络连接。 + +```python +wifiDisconnect() +``` + +### wifiReconnect() +重新连接到当前网络。 + +```python +wifiReconnect() +``` + +### wifiReassociate() +重新关联当前接入点。 + +```python +wifiReassociate() +``` + +## 热点 + +### wifiGetApState() +获取 WiFi AP（热点）状态。 + +```python +wifiGetApState() +``` + +**返回：** 热点状态 + +## WiFi 锁 + +### wifiLockAcquireFull() +获取完整 WiFi 锁（即使屏幕关闭也保持 WiFi 活动）。 + +```python +wifiLockAcquireFull() +``` + +### wifiLockAcquireScanOnly() +获取仅扫描 WiFi 锁。 + +```python +wifiLockAcquireScanOnly() +``` + +### wifiLockRelease() +释放 WiFi 锁。 + +```python +wifiLockRelease() +``` + +## 使用示例 + +```python +import androidhelper +import time + +droid = androidhelper.Android() + +# 检查 WiFi 状态 +if droid.checkWifiState().result: + print("WiFi is enabled") +else: + print("Enabling WiFi...") + droid.toggleWifiState(True) + time.sleep(2) + +# 开始扫描 +droid.wifiStartScan() +time.sleep(3) + +# 获取扫描结果 +networks = droid.wifiGetScanResults().result +for network in networks: + print(f"SSID: {network.get('SSID')}, Signal: {network.get('level')} dBm") + +# 获取连接信息 +info = droid.wifiGetConnectionInfo().result +if info: + print(f"Connected to: {info.get('ssid')}") + print(f"BSSID: {info.get('bssid')}") + print(f"IP: {info.get('ip_address')}") + +# 获取 DHCP 信息 +dhcp = droid.getDhcpInfo().result +if dhcp: + print(f"Gateway: {dhcp.get('gateway')}") + print(f"DNS: {dhcp.get('dns1')}") + +# 获取简化的连接信息 +connected = droid.getConnectedInfo().result +print(f"SSID: {connected.get('ssid')}, Signal: {connected.get('level')} dBm") + +# 断开并重新连接 +droid.wifiDisconnect() +time.sleep(1) +droid.wifiReconnect() + +# 重新关联接入点 +droid.wifiReassociate() + +# 检查热点状态 +ap_state = droid.wifiGetApState().result +print(f"Hotspot state: {ap_state}") + +# 获取 WiFi 锁以进行后台操作 +droid.wifiLockAcquireFull() +# ... 执行工作 ... +droid.wifiLockRelease() + +# 或使用仅扫描锁以进行较轻的后台操作 +droid.wifiLockAcquireScanOnly() +# ... 执行扫描工作 ... +droid.wifiLockRelease() +``` diff --git a/source/zh/qsl4a/core/android-base.md b/source/zh/qsl4a/core/android-base.md new file mode 100644 index 0000000..b7f5b19 --- /dev/null +++ b/source/zh/qsl4a/core/android-base.md @@ -0,0 +1,129 @@ +# Android 基础类 + +`Android` 类是 QSL4A 的核心，提供了与 Android 运行时的连接和 RPC 机制。 + +## 模块导入 + +```python +# 功能完整版本（推荐） +import androidhelper +droid = androidhelper.Android() + +# 简化版本（快速，单实例） +import android +droid = android.droid +``` + +## 类：Android + +### 构造函数 + +```python +Android(addr=None) +``` + +**参数：** +- `addr` (tuple, optional): (HOST, PORT) 地址。如果为 None，则使用环境变量 `AP_HOST` 和 `AP_PORT` + +**环境变量：** +- `AP_HOST` - 服务器主机地址 +- `AP_PORT` - 服务器端口 +- `AP_HANDSHAKE` - 认证令牌 + +### 核心方法 + +#### _rpc() +调用 Android 函数的内部 RPC 方法。 + +```python +_rpc(method, *args) +``` + +**参数：** +- `method` (str): 要调用的方法名 +- `*args`: 方法的可变参数 + +**返回：** `Result` 命名元组，包含以下字段： +- `id` (int): 请求 ID +- `result`: 方法返回值 +- `error` (str or None): 错误信息（如果失败） + +#### __getattr__() +动态方法分发器。所有 Android 方法都通过属性查找访问。 + +```python +# 以下两种方式等价： +droid.makeToast("Hello") +droid._rpc("makeToast", "Hello") +``` + +## 独立函数（android.py） + +使用简化的 `android` 模块时： + +### jsla() +发送 JSON-RPC 请求并返回原始响应。 + +```python +jsla(method, *params) +``` + +**返回：** JSON 字符串响应 + +### rsla() +发送请求并仅返回结果。 + +```python +rsla(method, *params) +``` + +**返回：** RPC 调用的结果值 + +### esla() +发送请求，错误时抛出异常。 + +```python +esla(method, *params) +``` + +**抛出：** 如果 error 字段不为 None 则抛出异常 + +### nsla() +发送请求并返回 Result 命名元组。 + +```python +nsla(method, *params) +``` + +**返回：** Result 命名元组 + +## 使用示例 + +### 基本连接 + +```python +import androidhelper + +# 连接到 Android 运行时 +droid = androidhelper.Android() + +# 通过显示 toast 来检查连接 +droid.makeToast("Connected!") +``` + +### 错误处理 + +```python +result = droid.someMethod() +if result.error: + print(f"Error: {result.error}") +else: + print(f"Success: {result.result}") +``` + +### 直接 RPC 调用 + +```python +# 直接调用任意方法 +result = droid._rpc("makeToast", "Hello World") +``` diff --git a/source/zh/qsl4a/core/events.md b/source/zh/qsl4a/core/events.md new file mode 100644 index 0000000..ad9abdf --- /dev/null +++ b/source/zh/qsl4a/core/events.md @@ -0,0 +1,245 @@ +# 事件系统 + +QSL4A 提供了一个事件系统，用于处理来自 Android 的异步事件，如传感器更新、位置变化和自定义广播。 + +## 事件基础 + +事件存储在缓冲区中，可以轮询或等待。每个事件包含： +- `name`: 事件类型/名称 +- `data`: 事件负载数据 +- `time`: 时间戳 + +## 事件方法 + +### eventClearBuffer() +清除缓冲区中的所有待处理事件。 + +```python +eventClearBuffer() +``` + +**返回：** None + +### eventPoll() +轮询缓冲区中的事件。 + +```python +eventPoll(number_of_events=1) +``` + +**参数：** +- `number_of_events` (int): 要检索的最大事件数（默认：1） + +**返回：** 事件对象列表 + +### eventWait() +等待任意事件。 + +```python +eventWait(timeout=None) +``` + +**参数：** +- `timeout` (int, optional): 超时时间（秒）。None = 永久等待 + +**返回：** 事件对象，如果超时则返回 None + +### eventWaitFor() +等待特定事件。 + +```python +eventWaitFor(eventName, timeout=None) +``` + +**参数：** +- `eventName` (str): 要等待的事件名称 +- `timeout` (int, optional): 超时时间（秒） + +**返回：** 事件对象，如果超时则返回 None + +### eventPost() +发布自定义事件。 + +```python +eventPost(name, data, enqueue=None) +``` + +**参数：** +- `name` (str): 事件名称 +- `data`: 事件数据（任意类型） +- `enqueue` (bool, optional): 如果为 True 则添加到队列 + +### receiveEvent() +接收事件（阻塞）。 + +```python +receiveEvent() +``` + +**返回：** 事件对象 + +## 广播事件 + +注册系统广播事件。 + +### eventRegisterForBroadcast() +注册接收广播事件。 + +```python +eventRegisterForBroadcast(category, enqueue=True) +``` + +**参数：** +- `category` (str): 广播类别/动作 +- `enqueue` (bool): 添加到事件队列 + +### eventUnregisterForBroadcast() +取消注册广播事件。 + +```python +eventUnregisterForBroadcast(category) +``` + +### eventGetBrodcastCategories() +获取已注册的广播类别。 + +```python +eventGetBrodcastCategories() +``` + +**返回：** 已注册类别列表 + +## 事件分发器) + +### startEventDispatcher() +打开一个可以读取已发布事件的套接字。) + +```python +startEventDispatcher(port=0) +``` + +**参数：** +- `port` (int, optional): 监听的端口（默认：0 = 自动选择） + +**返回：** 正在监听的端口号 + +### stopEventDispatcher() +停止事件服务器。) + +```python +stopEventDispatcher() +``` + +## 已废弃方法 + +### rpcPostEvent() +将事件发布到事件队列。（已废弃，请使用 eventPost） + +```python +rpcPostEvent(name, data) +``` + +**参数：** +- `name` (str): 事件名称 +- `data`: 事件数据 + +## 使用示例 + +### 基本事件轮询 + +```python +import androidhelper + +droid = androidhelper.Android() + +# 清除旧事件 +droid.eventClearBuffer() + +# 轮询事件 +events = droid.eventPoll(5).result +for event in events: + print(f"Event: {event['name']}, Data: {event['data']}") +``` + +### 等待事件 + +```python +# 等待任意事件，带超时 +event = droid.eventWait(timeout=10).result +if event: + print(f"Got event: {event['name']}") +``` + +### 等待特定事件 + +```python +# 等待传感器事件 +event = droid.eventWaitFor('screen', timeout=5).result +if event: + print(f"Screen event: {event['data']}") +``` + +### 发布自定义事件 + +```python +# 发布自定义事件 +droid.eventPost('my_event', {'key': 'value'}) + +# 等待它 +event = droid.eventWaitFor('my_event', timeout=1).result +``` + +### 广播接收器 + +```python +# 注册屏幕开关事件 +droid.eventRegisterForBroadcast('android.intent.action.SCREEN_ON') +droid.eventRegisterForBroadcast('android.intent.action.SCREEN_OFF') + +# 等待屏幕事件 +while True: + event = droid.receiveEvent().result + if event['name'] == 'android.intent.action.SCREEN_ON': + print("Screen turned on") + elif event['name'] == 'android.intent.action.SCREEN_OFF': + print("Screen turned off") +``` + +### 传感器事件处理 + +```python +# 开始感知 +droid.startSensingTimed(1, 250) + +# 处理传感器事件 +for _ in range(100): + event = droid.eventWait(timeout=1).result + if event and event['name'] == 'sensors': + data = event['data'] + print(f"Accel: {data['xforce']}, {data['yforce']}, {data['zforce']}") + +droid.stopSensing() +``` + +## 常见事件类型 + +| 事件名称 | 描述 | 来源 | +|------------|-------------|--------| +| `sensors` | 传感器数据更新 | startSensing* | +| `location` | GPS 位置更新 | startLocating | +| `phone` | 电话状态变化 | startTrackingPhoneState | +| `signal` | 信号强度变化 | startTrackingSignalStrength | +| `screen` | 截图就绪 | fullGetScreenShot | +| `dialog` | 对话框响应 | dialogShow* | + +## 事件数据结构 + +```python +{ + 'name': 'event_name', + 'data': { + # 事件特定数据 + }, + 'time': 1234567890 # 时间戳 +} +``` diff --git a/source/zh/qsl4a/core/intent.md b/source/zh/qsl4a/core/intent.md new file mode 100644 index 0000000..1493341 --- /dev/null +++ b/source/zh/qsl4a/core/intent.md @@ -0,0 +1,334 @@ +# Intent 系统 + +Android Intent 用于启动活动、发送广播和应用间通信。QSL4A 通过 `Intent` 模块提供完整的 Intent 支持。 + +## 模块导入 + +```python +import androidhelper +don = androidhelper.Android() +``` + +## Intent 常量 + +通过 `droid.Intent` 访问： + +### 操作 + +| 常量 | 值 | 用途 | +|----------|-------|-------| +| `ACTION_MAIN` | android.intent.action.MAIN | 应用入口点 | +| `ACTION_VIEW` | android.intent.action.VIEW | 查看内容 | +| `ACTION_EDIT` | android.intent.action.EDIT | 编辑内容 | +| `ACTION_PICK` | android.intent.action.PICK | 选择项目 | +| `ACTION_SEND` | android.intent.action.SEND | 分享内容 | +| `ACTION_SEARCH` | android.intent.action.SEARCH | 搜索 | + +### 标志 + +| 常量 | 值 | 用途 | +|----------|-------|-------| +| `FLAG_ACTIVITY_NEW_TASK` | 268435456 | 启动新任务 | +| `FLAG_ACTIVITY_CLEAR_TASK` | 32768 | 清除任务堆栈 | +| `FLAG_ACTIVITY_NEW_DOCUMENT` | 524288 | 新文档模式 | + +### 附加数据 + +| 常量 | 用途 | +|----------|-------| +| `EXTRA_TEXT` | 文本内容 | +| `EXTRA_STREAM` | 文件 URI | +| `EXTRA_SUBJECT` | 主题行 | +| `EXTRA_EMAIL` | 电子邮件地址 | + +## 核心方法 + +### makeIntent() +创建 Intent 对象。 + +```python +makeIntent(action, uri=None, type=None, extras=None, categories=None, + packagename=None, classname=None, flags=None) +``` + +**参数：** +- `action` (str): Intent 操作（例如 `droid.Intent.ACTION_VIEW`） +- `uri` (str, optional): 数据 URI +- `type` (str, optional): MIME 类型 +- `extras` (dict, optional): 附加数据 +- `categories` (list, optional): Intent 类别 +- `packagename` (str, optional): 目标包 +- `classname` (str, optional): 目标类 +- `flags` (int, optional): Intent 标志 + +**返回：** Intent 对象 + +### startActivityIntent() +使用 Intent 启动 Activity。 + +```python +startActivityIntent(intent, wait=None) +``` + +**参数：** +- `intent`: makeIntent() 返回的 Intent 对象 +- `wait` (bool, optional): 阻塞直到活动关闭 + +### startActivityForResultIntent() +启动活动并等待结果。 + +```python +startActivityForResultIntent(intent) +``` + +**返回：** Activity 结果 + +### sendBroadcastIntent() +发送广播。 + +```python +sendBroadcastIntent(intent) +``` + +### view() +通过 URI 查看内容。 + +```python +view(uri, type=None, extras=None) +``` + +### pick() +从 URI 选择内容。 + +```python +pick(uri) +``` + +## 常见 Intent 方法) + +### scanBarcode() +启动条码扫描器。 + +```python +scanBarcode() +``` + +**返回：** 扫描的条码字符串 + +### send() +通过分享 Intent 发送内容。 + +```python +send(type, content) +``` + +**参数：** +- `type` (str): MIME 类型 +- `content` (str): 要分享的内容 + +### sendText() +发送文本内容。 + +```python +sendText(text) +``` + +**参数：** +- `text` (str): 要发送的文本 + +### sendEmail() +发送电子邮件。 + +```python +sendEmail(to, subject, body, attachment=None) +``` + +**参数：** +- `to` (str or list): 收件人电子邮件地址 +- `subject` (str): 电子邮件主题 +- `body` (str): 电子邮件正文 +- `attachment` (str, optional): 附件文件路径 + +### pathToUri() +将文件路径转换为内容 URI。 + +```python +pathToUri(path) +``` + +**参数：** +- `path` (str): 文件路径 + +**返回：** 内容 URI 字符串 + +### openFile() +用适当的应用程序打开文件。 + +```python +openFile(path) +``` + +**参数：** +- `path` (str): 要打开的文件路径 + +### sendFile() +通过分享 Intent 发送文件。 + +```python +sendFile(path) +``` + +**参数：** +- `path` (str): 要发送的文件路径 + +### getPathType() +获取文件路径的 MIME 类型。 + +```python +getPathType(path) +``` + +**参数：** +- `path` (str): 文件路径 + +**返回：** MIME 类型字符串 + +### viewMap() +在指定位置打开地图。 + +```python +viewMap(latitude, longitude) +``` + +**参数：** +- `latitude` (float): 纬度 +- `longitude` (float): 经度 + +### viewContacts() +打开联系人应用。 + +```python +viewContacts() +``` + +### search() +执行网络搜索。 + +```python +search(query) +``` + +**参数：** +- `query` (str): 搜索查询 + +### viewHtml() +查看 HTML 内容。 + +```python +viewHtml(content, encoding=None) +``` + +**参数：** +- `content` (str): HTML 内容 +- `encoding` (str, optional): 字符编码 + +### webViewShow() +在 WebView 中显示网页内容。已废弃，请使用 viewHtml。 + +```python +webViewShow(url) +``` + +**参数：** +- `url` (str): 网页 URL + +### editorOpen() +打开文本编辑器。 + +```python +editorOpen(path=None, create=False) +``` + +**参数：** +- `path` (str, optional): 要编辑的文件路径 +- `create` (bool, optional): 如果不存在则创建 + +## 辅助类：Uri + +创建 Intent 的 URI 对象： + +```python +from androidhelper.Intent import Uri + +uri = Uri("file:///sdcard/test.txt") +``` + +## 使用示例 + +### 打开网页 + +```python +intent = droid.makeIntent( + action=droid.Intent.ACTION_VIEW, + uri="http://www.example.com" +).result +droid.startActivityIntent(intent) +``` + +### 分享文本 + +```python +intent = droid.makeIntent( + action=droid.Intent.ACTION_SEND, + extras={ + droid.Intent.EXTRA_TEXT: "Hello from QPython!", + droid.Intent.EXTRA_SUBJECT: "Test" + }, + type="text/plain" +).result +droid.startActivityIntent(intent) +``` + +### 打开文件 + +```python +intent = droid.makeIntent( + action=droid.Intent.ACTION_VIEW, + uri="file:///sdcard/document.pdf", + type="application/pdf" +).result +droid.startActivityIntent(intent) +``` + +### 选择联系人 + +```python +result = droid.pickContact() +contact_uri = result.result +``` + +### 发送电子邮件 + +```python +intent = droid.makeIntent( + action=droid.Intent.ACTION_SEND, + extras={ + droid.Intent.EXTRA_EMAIL: ["test@example.com"], + droid.Intent.EXTRA_SUBJECT: "Hello", + droid.Intent.EXTRA_TEXT: "Message body" + }, + type="message/rfc822" +).result +droid.startActivityIntent(intent) +``` + +### 打开应用 + +```python +intent = droid.makeIntent( + action=droid.Intent.ACTION_MAIN, + packagename="com.android.settings", + classname="com.android.settings.Settings" +).result +droid.startActivityIntent(intent) +``` diff --git a/source/zh/qsl4a/hardware/bluetooth.md b/source/zh/qsl4a/hardware/bluetooth.md new file mode 100644 index 0000000..e99e745 --- /dev/null +++ b/source/zh/qsl4a/hardware/bluetooth.md @@ -0,0 +1,201 @@ +# 蓝牙 API + +控制蓝牙适配器并与蓝牙设备通信。 + +## 适配器控制 + +### toggleBluetoothState() +打开/关闭蓝牙。 + +```python +toggleBluetoothState(enabled=None, prompt=True) +``` + +**参数：** +- `enabled` (bool): True=开，False=关，None=切换 +- `prompt` (bool): 显示用户提示 + +### checkBluetoothState() +检查蓝牙是否已启用。 + +```python +checkBluetoothState() +``` + +**返回：** True/False + +### GetLocalName() +获取蓝牙设备名称。 + +```python +GetLocalName() +``` + +### SetLocalName() +设置蓝牙设备名称。 + +```python +SetLocalName(name) +``` + +### GetScanMode() +获取可发现性模式。 + +```python +GetScanMode() +``` + +**返回：** +- -1: 已禁用 +- 0: 不可发现，不可连接 +- 1: 可连接，不可发现 +- 3: 可连接且可发现 + +### MakeDiscoverable() +使设备可发现。 + +```python +MakeDiscoverable(duration=300) +``` + +**参数：** +- `duration` (int): 可发现的秒数 + +## 发现 + +### DiscoveryStart() +开始设备发现。 + +```python +DiscoveryStart() +``` + +### DiscoveryCancel() +取消发现。 + +```python +DiscoveryCancel() +``` + +### GetReceivedDevices() +获取发现的设备。 + +```python +GetReceivedDevices() +``` + +**返回：** 设备信息字典列表 + +### GetBondedDevices() +获取配对设备。 + +```python +GetBondedDevices() +``` + +**返回：** 配对设备信息列表 + +## 连接 + +### Connect() +连接到设备。 + +```python +Connect(uuid="457807c0-4897-11df-9879-0800200c9a66", address=None) +``` + +**参数：** +- `uuid` (str): 服务 UUID +- `address` (str): 设备地址（None = 显示选择器） + +**返回：** 如果成功则为 True + +### Accept() +接受传入连接。 + +```python +Accept(uuid="457807c0-4897-11df-9879-0800200c9a66", timeout=0) +``` + +### ActiveConnections() +检查活动连接。 + +```python +ActiveConnections() +``` + +### Stop() +断开连接。 + +```python +Stop(connID=None) +``` + +## 通信 + +### Write() +发送 ASCII 数据。 + +```python +Write(ascii, connID="") +``` + +### WriteBinary() +发送二进制数据（base64 编码）。 + +```python +WriteBinary(base64, connID=None) +``` + +### Read() +读取 ASCII 数据。 + +```python +Read(bufferSize=4096, connID=None) +``` + +### ReadBinary() +读取二进制数据。 + +```python +ReadBinary(bufferSize=4096, connID=None) +``` + +### ReadLine() +读取一行。 + +```python +ReadLine(connID=None) +``` + +### ReadReady() +检查是否有可用数据。 + +```python +ReadReady(connID=None) +``` + +## 使用示例 + +```python +import androidhelper + +droid = androidhelper.Android() + +# 启用蓝牙 +droid.toggleBluetoothState(True) + +# 获取配对设备 +devices = droid.GetBondedDevices().result +for dev in devices: + print(f"{dev['name']}: {dev['address']}") + +# 连接到设备 +droid.Connect(address="00:11:22:33:44:55") + +# 发送数据 +droid.Write("Hello Bluetooth!") + +# 读取响应 +data = droid.Read(1024).result +``` diff --git a/source/zh/qsl4a/hardware/camera.md b/source/zh/qsl4a/hardware/camera.md new file mode 100644 index 0000000..404576b --- /dev/null +++ b/source/zh/qsl4a/hardware/camera.md @@ -0,0 +1,182 @@ +# 相机 API + +拍摄照片和录制视频。 + +## 照片拍摄 + +### takePicture() +使用默认相机拍摄照片。 + +```python +takePicture(path=None) +``` + +**参数：** +- `path` (str, optional): 保存路径。如果为 None，则返回图像数据 + +**返回：** 图像路径或图像数据 + +### cameraCapturePicture() +使用高级相机控制拍摄照片。 + +```python +cameraCapturePicture(targetPath=None, cameraId=0, useAutoFocus=True) +``` + +**参数：** +- `targetPath` (str, optional): 保存路径 +- `cameraId` (int): 使用的相机（0 = 后置，1 = 前置） +- `useAutoFocus` (bool): 启用自动对焦 + +**返回：** 拍摄的图像路径 + +### cameraSetTorchMode() +控制相机闪光灯/手电筒。 + +```python +cameraSetTorchMode(enabled) +``` + +**参数：** +- `enabled` (bool): True 打开，False 关闭 + +**返回：** 如果成功则为 True + +### imageReaderGetScreenShot() +截图。 + +```python +imageReaderGetScreenShot(path=None, delayMilliSec=1000) +``` + +**参数：** +- `path` (str, optional): 保存路径 +- `delayMilliSec` (int): 拍摄前延迟 + +## 视频录制 + +### takeVideo() +使用默认设置录制视频。 + +```python +takeVideo(path=None, quality=1) +``` + +**参数：** +- `path` (str, optional): 保存路径 +- `quality` (int): 视频质量（0-4） + - 0: 160x120 + - 1: 320x240 + - 2: 352x288 + - 3: 640x480 + - 4: 800x480 + +### recorderCaptureVideo() +使用高级控制录制视频。 + +```python +recorderCaptureVideo(targetPath=None, duration=10, cameraId=0, quality=8) +``` + +**参数：** +- `targetPath` (str, optional): 保存路径 +- `duration` (int): 录制时长（秒）（默认：10） +- `cameraId` (int): 使用的相机（0 = 后置，1 = 前置） +- `quality` (int): 视频质量（0-8，越高越好） + +**返回：** 视频文件路径 + +### recordAudio() +录制音频。 + +```python +recordAudio() +``` + +**返回：** 音频文件路径 + +## 屏幕录制 + +### recorderStartScreenRecord() +开始屏幕录制。 + +```python +recorderStartScreenRecord(path=None, audio=1, targetPixels=None, + frameRate=30, bitRate=None, rotation=False, + autoStart=True) +``` + +**参数：** +- `path` (str): 保存路径 +- `audio` (int): 音频源（0=无，1=麦克风，2=内部） +- `targetPixels` (int): 分辨率 +- `frameRate` (int): FPS +- `bitRate` (int): 比特率 +- `rotation` (bool): 旋转输出 +- `autoStart` (bool): 立即开始 + +### recorderStart() +开始录制。 + +```python +recorderStart() +``` + +### recorderPause() +暂停录制。 + +```python +recorderPause() +``` + +### recorderResume() +恢复录制。 + +```python +recorderResume() +``` + +## 音频音量检测 + +### recorderSoundVolumeDetect() +开始音量检测。 + +```python +recorderSoundVolumeDetect(interval=100) +``` + +### recorderSoundVolumeGetDb() +获取当前音量（分贝）。 + +```python +recorderSoundVolumeGetDb() +``` + +## 使用示例 + +```python +import androidhelper + +droid = androidhelper.Android() + +# 使用默认相机拍照 +photo_path = droid.takePicture("/sdcard/photo.jpg").result +print(f"Photo saved: {photo_path}") + +# 使用前置相机和自动对焦拍照 +camera_path = droid.cameraCapturePicture("/sdcard/selfie.jpg", cameraId=1, useAutoFocus=True).result +print(f"Front camera photo: {camera_path}") + +# 控制闪光灯 +droid.cameraSetTorchMode(True) # 打开闪光灯 + +# 使用默认设置录制视频 +video_path = droid.takeVideo("/sdcard/video.mp4", quality=3).result +print(f"Video saved: {video_path}") + +# 使用高级控制录制视频 +video_path = droid.recorderCaptureVideo("/sdcard/movie.mp4", duration=30, cameraId=0, quality=8).result + +# 截图 +ss_path = droid.imageReaderGetScreenShot("/sdcard/screenshot.png", 500).result +``` diff --git a/source/zh/qsl4a/hardware/recorder.md b/source/zh/qsl4a/hardware/recorder.md new file mode 100644 index 0000000..942eca4 --- /dev/null +++ b/source/zh/qsl4a/hardware/recorder.md @@ -0,0 +1,124 @@ +# 音频录制 API + +从麦克风和设备屏幕录制音频。 + +## 音频录制 + +### recordAudio() +从麦克风录制音频。 + +```python +recordAudio() +``` + +**返回：** 录制的音频文件路径 + +### recorderStartMicrophone() +开始从麦克风录制到特定文件。 + +```python +recorderStartMicrophone(targetPath=None) +``` + +**参数：** +- `targetPath` (str, optional): 保存录制的路径 + +## 屏幕录制 + +### recorderStartScreenRecord() +开始带音频的屏幕录制。 + +```python +recorderStartScreenRecord(path=None, audio=1, targetPixels=None, + frameRate=30, bitRate=None, rotation=False, + autoStart=True) +``` + +**参数：** +- `path` (str): 视频文件保存路径 +- `audio` (int): 音频源（0=无，1=麦克风，2=内部音频） +- `targetPixels` (int): 目标分辨率（像素） +- `frameRate` (int): 每秒帧数（默认：30） +- `bitRate` (int): 视频比特率 +- `rotation` (bool): 旋转输出视频 +- `autoStart` (bool): 立即开始录制 + +**返回：** 操作结果 + +### recorderStart() +开始屏幕录制（当 autoStart=False 时）。 + +```python +recorderStart() +``` + +### recorderPause() +暂停正在进行的屏幕录制。 + +```python +recorderPause() +``` + +### recorderResume() +恢复暂停的屏幕录制。 + +```python +recorderResume() +``` + +## 音频音量检测 + +### recorderSoundVolumeDetect() +开始监控音量级别。 + +```python +recorderSoundVolumeDetect(interval=100) +``` + +**参数：** +- `interval` (int): 检测间隔（毫秒）（默认：100） + +### recorderSoundVolumeGetDb() +获取当前音量（分贝）。 + +```python +recorderSoundVolumeGetDb() +``` + +**返回：** 当前音量级别（dB） + +## 使用示例 + +```python +import androidhelper +import time + +droid = androidhelper.Android() + +# 从麦克风录制音频 +print("Recording audio...") +audio_path = droid.recordAudio().result +print(f"Saved to: {audio_path}") + +# 录制到特定文件 +droid.recorderStartMicrophone("/sdcard/my_recording.mp3") +time.sleep(5) +droid.recorderStop() + +# 带音频录制屏幕 +print("Starting screen recording...") +droid.recorderStartScreenRecord( + path="/sdcard/screen_record.mp4", + audio=1, + frameRate=30, + autoStart=True +) +time.sleep(10) +droid.recorderStop() + +# 监控音量 +droid.recorderSoundVolumeDetect(interval=100) +time.sleep(3) +volume = droid.recorderSoundVolumeGetDb().result +print(f"Current volume: {volume} dB") +``` diff --git a/source/zh/qsl4a/hardware/usbserial.md b/source/zh/qsl4a/hardware/usbserial.md new file mode 100644 index 0000000..6557f08 --- /dev/null +++ b/source/zh/qsl4a/hardware/usbserial.md @@ -0,0 +1,161 @@ +# USB 主机串行 API + +与 USB 串行设备通信（需要 USB OTG 支持和 Android 3.1+）。 + +## USB 串行方法) + +### usbHostSerialOpen() +打开与 USB 串行设备的连接。 + +```python +usbHostSerialOpen(device, baudRate=9600) +``` + +**参数：** +- `device` (str): USB 设备路径或标识符 +- `baudRate` (int): 波特率（默认：9600） + +**返回：** 如果打开成功则为 True + +### usbHostSerialClose() +关闭 USB 串行连接。 + +```python +usbHostSerialClose() +``` + +### usbHostSerialRead() +从 USB 串行读取数据。 + +```python +usbHostSerialRead(bufferSize=1024) +``` + +**参数：** +- `bufferSize` (int): 要读取的最大字节数（默认：1024） + +**返回：** 读取的数据字符串 + +### usbHostSerialWrite() +向 USB 串行写入数据。 + +```python +usbHostSerialWrite(data) +``` + +**参数：** +- `data` (str): 要写入的字符串数据 + +### usbHostSerialAvailable() +检查是否有可读取的数据。 + +```python +usbHostSerialAvailable() +``` + +**返回：** 可用字节数 + +## 配置方法) + +### usbHostSerialSetBaudRate() +设置波特率。 + +```python +usbHostSerialSetBaudRate(baudRate) +``` + +**参数：** +- `baudRate` (int): 波特率 + +### usbHostSerialSetDataBits() +设置数据位（5、6、7 或 8）。 + +```python +usbHostSerialSetDataBits(dataBits) +``` + +**参数：** +- `dataBits` (int): 数据位（5-8） + +### usbHostSerialSetStopBits() +设置停止位（1、1.5 或 2）。 + +```python +usbHostSerialSetStopBits(stopBits) +``` + +**参数：** +- `stopBits` (float): 停止位（1、1.5 或 2） + +### usbHostSerialSetParity() +设置校验位（无、奇、偶、标记、空格）。 + +```python +usbHostSerialSetParity(parity) +``` + +**参数：** +- `parity` (str): 校验模式（'none'、'odd'、'even'、'mark'、'space'） + +### usbHostSerialSetFlowControl() +设置流控制（无、硬件、软件）。 + +```python +usbHostSerialSetFlowControl(flowControl) +``` + +**参数：** +- `flowControl` (str): 流控制模式（'none'、'hardware'、'software'） + +### usbHostSerialReadHex() +以十六进制字符串读取数据。 + +```python +usbHostSerialReadHex(bufferSize=1024) +``` + +**参数：** +- `bufferSize` (int): 要读取的最大字节数 + +**返回：** 十六进制字符串 + +### usbHostSerialWriteHex() +从十六进制字符串写入数据。 + +```python +usbHostSerialWriteHex(hexString) +``` + +**参数：** +- `hexString` (str): 要写入的十六进制字符串 + +## 使用示例 + +```python +import androidhelper + +droid = androidhelper.Android() + +# 打开 USB 串行连接 +if droid.usbHostSerialOpen("/dev/bus/usb/001/001", 115200).result: + print("USB serial opened") + + # 写入数据 + droid.usbHostSerialWrite("AT\r") + + # 读取响应 + response = droid.usbHostSerialRead(1024).result + print(f"Response: {response}") + + # 或使用十六进制 + droid.usbHostSerialWriteHex("41540D0A") # "AT\r\n" + + # 关闭连接 + droid.usbHostSerialClose() +``` + +**注意：** USB 串行需要： +- Android 3.1+ (API 12) +- USB OTG 线/适配器 +- 设备上的 USB 主机模式支持 +- 兼容的串行设备 diff --git a/source/zh/qsl4a/hardware/webcam.md b/source/zh/qsl4a/hardware/webcam.md new file mode 100644 index 0000000..c0d06c6 --- /dev/null +++ b/source/zh/qsl4a/hardware/webcam.md @@ -0,0 +1,98 @@ +# 网络摄像头 API + +使用 MJPEG 从设备相机流式传输视频。 + +## MJPEG 流方法 + +### webcamStart() +从网络摄像头启动 MJPEG 流。 + +```python +webcamStart(resolutionLevel=0, jpegQuality=20, port=0) +``` + +**参数：** +- `resolutionLevel` (int): 分辨率级别（默认：0） +- `jpegQuality` (int): JPEG 质量 1-100（默认：20） +- `port` (int): 端口号（默认：0 = 自动） + +**返回：** 流的 (地址, 端口) 元组 + +### webcamAdjustQuality() +调整活动网络摄像头流的质量。 + +```python +webcamAdjustQuality(resolutionLevel=0, jpegQuality=20) +``` + +**参数：** +- `resolutionLevel` (int): 分辨率级别 +- `jpegQuality` (int): JPEG 质量 1-100 + +### webcamStop() +停止网络摄像头流。 + +```python +webcamStop() +``` + +## 相机预览方法 + +### cameraStartPreview() +开始带事件生成的相机预览模式。 + +```python +cameraStartPreview(resolutionLevel=0, jpegQuality=20, filepath=None) +``` + +**参数：** +- `resolutionLevel` (int): 分辨率级别（默认：0） +- `jpegQuality` (int): JPEG 质量（默认：20） +- `filepath` (str, optional): 保存预览帧的文件路径 + +**返回：** 如果成功则为 True + +**注意：** 生成带有帧数据的 'preview' 事件。 + +### cameraStopPreview() +停止相机预览。 + +```python +cameraStopPreview() +``` + +## 使用示例 + +```python +import androidhelper +import time + +droid = androidhelper.Android() + +# 启动网络摄像头流 +stream_info = droid.webcamStart( + resolutionLevel=0, + jpegQuality=30, + port=8080 +).result +print(f"Stream available at {stream_info[0]}:{stream_info[1]}") + +# 流式传输时调整质量 +time.sleep(5) +droid.webcamAdjustQuality(resolutionLevel=1, jpegQuality=50) + +# 完成后停止 +droid.webcamStop() + +# 或使用预览模式 +print("Starting preview...") +droid.cameraStartPreview() + +# 等待预览事件 +for i in range(10): + event = droid.eventWait(timeout=1).result + if event and event['name'] == 'preview': + print(f"Got preview frame: {event['data']}") + +droid.cameraStopPreview() +``` diff --git a/source/zh/qsl4a/index.md b/source/zh/qsl4a/index.md new file mode 100644 index 0000000..7561aee --- /dev/null +++ b/source/zh/qsl4a/index.md @@ -0,0 +1,91 @@ +# QSL4A（Android 脚本层）API 文档 + +QSL4A 是 QPython 的 Android 脚本层，允许您使用 Python 控制 Android 设备功能。 + +## 快速开始 + +```python +import androidhelper + +droid = androidhelper.Android() + +# 显示 toast 消息 +droid.makeToast('Hello QPython!') + +# 震动设备 +droid.vibrate(500) + +# 获取电池电量（先开始监控） +import time +droid.batteryStartMonitoring() +time.sleep(0.5) # 等待数据 +battery = droid.readBatteryData().result +print(f"电池：{battery['level']}%") +``` + +## 文档结构 + +### [核心模块](core/) +- [Android 基础](core/android-base.md) - 核心连接和 RPC +- [Intent 系统](core/intent.md) - Android Intent 操作 +- [事件系统](core/events.md) - 事件处理和广播 + +### [UI 组件](ui/) +- [对话框](ui/dialogs.md) - 警报、输入、选择对话框 +- [全屏 UI](ui/fullscreen.md) - 自定义布局 UI +- [悬浮窗](ui/floatview.md) - 悬浮窗口 +- [辅助功能](ui/accessibility.md) - 屏幕自动化 + +### [系统](system/) +- [电池](system/battery.md) - 电池监控 +- [传感器](system/sensors.md) - 设备传感器 +- [应用](system/application.md) - 应用管理 +- [系统信息](system/sysinfo.md) - 设备信息 +- [设置](system/settings.md) - 系统设置 +- [唤醒锁](system/wakelock.md) - 唤醒锁控制 +- [QPython 接口](system/qpyinterface.md) - 脚本执行 +- [Activity 结果](system/activityresult.md) - Activity 结果处理 + +### [硬件](hardware/) +- [蓝牙](hardware/bluetooth.md) - 蓝牙操作 +- [相机](hardware/camera.md) - 拍照和录像 +- [音频/录音器](hardware/recorder.md) - 录音 +- [网络摄像头](hardware/webcam.md) - MJPEG 流 +- [USB 串口](hardware/usbserial.md) - USB 主机串口 + +### [连接](connectivity/) +- [WiFi](connectivity/wifi.md) - WiFi 操作 +- [位置](connectivity/location.md) - GPS 和位置 +- [短信](connectivity/sms.md) - 短信操作 +- [电话](connectivity/phone.md) - 打电话和来电信息 +- [联系人](connectivity/contacts.md) - 联系人管理 +- [信号强度](connectivity/signalstrength.md) - 信号监控 +- [FTP 服务器](connectivity/ftp.md) - 内置 FTP 服务器 + +### [存储](storage/) +- [DocumentFile](storage/documentfile.md) - 文件操作 +- [剪贴板](storage/clipboard.md) - 剪贴板操作 +- [偏好设置](storage/preferences.md) - 共享偏好设置 + +### [媒体](media/) +- [媒体播放器](media/mediaplayer.md) - 音频/视频播放 +- [图像处理](media/image.md) - 图像操作 + +### [特殊功能](special/) +- [加密](special/cipher.md) - 加密/解密 +- [PGPT AI](special/pgptai.md) - AI 语音服务 + +## 结果对象 + +大多数 QSL4A 方法返回一个带有以下属性的 Result 命名元组： +- `id` - 请求 ID +- `result` - 实际结果数据 +- `error` - 如果失败则为错误消息 + +```python +result = droid.getClipboard() +if result.error is None: + print(result.result) +else: + print(f"错误：{result.error}") +``` diff --git a/source/zh/qsl4a/media/image.md b/source/zh/qsl4a/media/image.md new file mode 100644 index 0000000..f3d533c --- /dev/null +++ b/source/zh/qsl4a/media/image.md @@ -0,0 +1,94 @@ +# 图像处理 API + +压缩和处理图像。 + +## 图像压缩 + +### imageCompress() +压缩图像文件。 + +```python +imageCompress(srcPath, destPath, targetByteSize=0, targetWidth=0, targetHeight=0) +``` + +**参数：** +- `srcPath` (str): 源图像路径 +- `destPath` (str): 输出路径 +- `targetByteSize` (int): 目标文件大小（字节）（0 = 无限制） +- `targetWidth` (int): 目标宽度（0 = 原始） +- `targetHeight` (int): 目标高度（0 = 原始） + +**返回：** 压缩后的图像路径 + +## 截图 + +### imageReaderGetScreenShot() +截取屏幕。 + +```python +imageReaderGetScreenShot(path=None, delayMilliSec=1000) +``` + +**参数：** +- `path` (str): 保存路径 +- `delayMilliSec` (int): 拍摄前延迟 + +**返回：** 截图路径 + +## 视频播放 + +### videoPlay() +在全屏模式下播放视频文件。 + +```python +videoPlay(path, wait=True) +``` + +**参数：** +- `path` (str): 视频文件路径 +- `wait` (bool): 等待播放完成（默认：True） + +## 条码扫描 + +### scanBarcodeFromImage() +从图像文件扫描条码/二维码。 + +```python +scanBarcodeFromImage(path, compressRatio=0, x=0, y=0, width=0, height=0) +``` + +**参数：** +- `path` (str): 图像文件路径 +- `compressRatio` (int): 压缩比（0 = 不压缩） +- `x`, `y`, `width`, `height` (int): 要扫描的区域（0 = 完整图像） + +**返回：** 扫描的条码内容 + +## 使用示例 + +```python +import androidhelper + +droid = androidhelper.Android() + +# 截图 +ss_path = droid.imageReaderGetScreenShot("/sdcard/screenshot.png", 500).result + +# 压缩图像 +compressed = droid.imageCompress( + "/sdcard/large_photo.jpg", + "/sdcard/compressed.jpg", + targetByteSize=102400, # 目标约 100KB + targetWidth=1920, + targetHeight=1080 +).result +print(f"Saved: {compressed}") + +# 播放视频 +video_path = "/sdcard/movie.mp4" +droid.videoPlay(video_path, wait=True) + +# 从图像扫描条码 +result = droid.scanBarcodeFromImage("/sdcard/qr_code.png").result +print(f"Barcode: {result}") +``` diff --git a/source/zh/qsl4a/media/mediaplayer.md b/source/zh/qsl4a/media/mediaplayer.md new file mode 100644 index 0000000..c9eccd7 --- /dev/null +++ b/source/zh/qsl4a/media/mediaplayer.md @@ -0,0 +1,152 @@ +# 媒体播放器 API + +控制音频和视频播放。 + +## 播放控制 + +### mediaPlay() +播放媒体文件。 + +```python +mediaPlay(url, tag="default", play=True) +``` + +**参数：** +- `url` (str): 媒体文件路径或 URL +- `tag` (str): 播放器标识符 +- `play` (bool): 自动开始播放 + +### mediaPlayStart() +开始播放。 + +```python +mediaPlayStart(tag="default") +``` + +### mediaPlayPause() +暂停播放。 + +```python +mediaPlayPause(tag="default") +``` + +### mediaPlayClose() +关闭播放器。 + +```python +mediaPlayClose(tag="default") +``` + +### mediaPlaySeek() +跳转到位置。 + +```python +mediaPlaySeek(msec, tag="default") +``` + +**参数：** +- `msec` (int): 位置（毫秒） + +### mediaPlaySetLooping() +设置循环模式。 + +```python +mediaPlaySetLooping(enabled, tag="default") +``` + +## 播放器信息 + +### mediaPlayInfo() +获取播放信息。 + +```python +mediaPlayInfo(tag="default") +``` + +**返回：** 包含时长、位置等的字典 + +### mediaIsPlaying() +检查是否正在播放。 + +```python +mediaIsPlaying(tag="default") +``` + +**返回：** True/False + +### mediaPlayList() +列出活动播放器。 + +```python +mediaPlayList() +``` + +## 音量控制 + +### getMediaVolume() +获取媒体音量。 + +```python +getMediaVolume() +``` + +**返回：** 音量级别（0-15） + +### getMaxMediaVolume() +获取最大媒体音量。 + +```python +getMaxMediaVolume() +``` + +### getRingerVolume() +获取铃声音量。 + +```python +getRingerVolume() +``` + +### getMaxRingerVolume() +获取最大铃声音量。 + +```python +getMaxRingerVolume() +``` + +## 视频播放 + +### videoPlay() +全屏播放视频。 + +```python +videoPlay(path, wait=True) +``` + +**参数：** +- `path` (str): 视频文件路径 +- `wait` (bool): 等待播放完成 + +## 使用示例 + +```python +import androidhelper + +droid = androidhelper.Android() + +# 播放音频 +droid.mediaPlay("/sdcard/music.mp3", tag="music") + +# 检查状态 +if droid.mediaIsPlaying("music").result: + info = droid.mediaPlayInfo("music").result + print(f"Playing: {info}") + +# 跳转到 30 秒 +droid.mediaPlaySeek(30000, "music") + +# 关闭 +droid.mediaPlayClose("music") + +# 播放视频 +droid.videoPlay("/sdcard/movie.mp4", wait=True) +``` diff --git a/source/zh/qsl4a/special/cipher.md b/source/zh/qsl4a/special/cipher.md new file mode 100644 index 0000000..d2079bb --- /dev/null +++ b/source/zh/qsl4a/special/cipher.md @@ -0,0 +1,143 @@ +# 密码 API + +用于安全数据存储的加密和解密工具。 + +## 初始化 + +### cipherInit() +使用加密密钥和算法初始化密码器。 + +```python +cipherInit(key, algorithm="AES/CBC/PKCS5Padding", encodingFormat="", initialVector="") +``` + +**参数：** +- `key` (str or bytes): 加密密钥 +- `algorithm` (str): 密码算法（默认："AES/CBC/PKCS5Padding"） +- `encodingFormat` (str): 编码格式 +- `initialVector` (str or bytes): 加密的初始向量 + +**返回：** 初始化结果 + +**注意：** 必须在任何加密/解密操作之前调用。 + +## 加密方法 + +### encryptString() +加密字符串。 + +```python +encryptString(plainText) +``` + +**参数：** +- `plainText` (str): 要加密的文本 + +**返回：** 加密的字符串 + +### encryptBytes() +加密字节数据。 + +```python +encryptBytes(data) +``` + +**参数：** +- `data` (bytes): 要加密的数据 + +**返回：** 加密的字节 + +### encryptStringToFile() +加密字符串到文件。 + +```python +encryptStringToFile(plainText, filePath) +``` + +**参数：** +- `plainText` (str): 要加密的文本 +- `filePath` (str): 输出文件路径 + +### encryptBytesToFile() +加密字节到文件。 + +```python +encryptBytesToFile(data, filePath) +``` + +## 解密方法 + +### decryptString() +解密为字符串。 + +```python +decryptString(cipherText) +``` + +**参数：** +- `cipherText` (str): 加密的文本 + +**返回：** 解密的字符串 + +### decryptBytes() +解密为字节。 + +```python +decryptBytes(data) +``` + +**返回：** 解密的字节 + +### decryptFileToString() +解密文件到字符串。 + +```python +decryptFileToString(filePath) +``` + +### decryptFileToBytes() +解密文件到字节。 + +```python +decryptFileToBytes(filePath) +``` + +### decryptFile() +解密文件到文件。 + +```python +decryptFile(srcPath, destPath) +``` + +## 使用示例 + +```python +import androidhelper + +droid = androidhelper.Android() + +# 使用加密密钥初始化密码器 +droid.cipherInit("my_secret_key_1234") + +# 加密字符串 +encrypted = droid.encryptString("Secret message!").result +print(f"Encrypted: {encrypted}") + +# 解密字符串 +decrypted = droid.decryptString(encrypted).result +print(f"Decrypted: {decrypted}") + +# 加密到文件 +droid.encryptStringToFile("My secret data", "/sdcard/secret.dat") + +# 从文件解密 +data = droid.decryptFileToString("/sdcard/secret.dat").result +print(data) + +# 使用自定义算法和 IV 初始化 +droid.cipherInit( + key="my_key", + algorithm="AES/CBC/PKCS5Padding", + initialVector="0123456789abcdef" +) +``` diff --git a/source/zh/qsl4a/special/pgptai.md b/source/zh/qsl4a/special/pgptai.md new file mode 100644 index 0000000..1e7ca9b --- /dev/null +++ b/source/zh/qsl4a/special/pgptai.md @@ -0,0 +1,100 @@ +# PGPT AI API + +语音转文本和 AI 服务集成。 + +## 先决条件 + +```bash +pip install pgptAI +``` + +## 语音识别 + +### speechToText() +将语音转换为文本。 + +```python +speechToText(RecordSecond=10, AmrFile=None, Language=None) +``` + +**参数：** +- `RecordSecond` (int): 录制时长（秒） +- `AmrFile` (str, optional): 现有音频文件路径 +- `Language` (str, optional): 语言代码（'en'、'zh'） + +**返回：** 转录的文本 + +## 文本转语音 + +### textToSpeech() +将文本转换为语音并可选地播放。 + +```python +textToSpeech(Text, AutoPlay=True, WavFile=None, VoiceName=None) +``` + +**参数：** +- `Text` (str): 要转换为语音的文本 +- `AutoPlay` (bool): 自动播放生成的音频（默认：True） +- `WavFile` (str, optional): 保存 WAV 文件的路径。如果为 None，则使用临时文件 +- `VoiceName` (str, optional): 要使用的语音名称（例如 'en-US-JennyNeural'、'zh-CN-XiaoxiaoNeural'） + +**返回：** 包含语音合成结果的字典，包括： + - `text`: 输入文本 + - `url`: 下载音频文件的 URL + - `WavFile`: 保存的 WAV 文件路径（如果本地保存） + +## 配置 + +API 使用以下配置文件中的配置：`/storage/emulated/0/Android/data/org.qpython.qpy/files/apigpt.conf`： + +```ini +[speech] +speech_key = your_api_key +``` + +默认语音设置： +- 英语：`en-US-JennyNeural` +- 中文：`zh-CN-XiaoxiaoNeural` + +## 使用示例 + +```python +import androidhelper + +droid = androidhelper.Android() + +# 录制并转录 +print("Recording for 5 seconds...") +text = droid.speechToText(RecordSecond=5, Language='en').result +print(f"You said: {text}") + +# 转录现有文件 +text = droid.speechToText(AmrFile="/sdcard/recording.amr").result +print(f"Transcription: {text}") + +# 文本转语音 +droid.textToSpeech("Hello, this is a test message.", AutoPlay=True, Language='en') + +# 使用自定义语音并保存到文件的文本转语音 +result = droid.textToSpeech( + "Welcome to QPython!", + AutoPlay=False, + WavFile="/sdcard/welcome.wav", + VoiceName="en-US-JennyNeural" +).result +print(f"Audio saved to: {result.get('WavFile')}") +``` + +## 类使用 + +```python +from androidhelper.pgptai import pgptai +import androidhelper + +droid = androidhelper.Android() +ai = pgptai(droid) + +# 使用语音识别 +text = ai.speechToText(RecordSecond=10) +``` diff --git a/source/zh/qsl4a/storage/clipboard.md b/source/zh/qsl4a/storage/clipboard.md new file mode 100644 index 0000000..1379064 --- /dev/null +++ b/source/zh/qsl4a/storage/clipboard.md @@ -0,0 +1,41 @@ +# 剪贴板 API + +复制和粘贴文本到系统剪贴板。 + +## 方法 + +### setClipboard() +复制文本到剪贴板。 + +```python +setClipboard(text) +``` + +**参数：** +- `text` (str): 要复制的文本 + +**返回：** 如果成功则为 True + +### getClipboard() +从剪贴板获取文本。 + +```python +getClipboard() +``` + +**返回：** 剪贴板文本 + +## 使用示例 + +```python +import androidhelper + +droid = androidhelper.Android() + +# 复制到剪贴板 +droid.setClipboard("Hello from QPython!") + +# 从剪贴板粘贴 +text = droid.getClipboard().result +print(f"Clipboard: {text}") +``` diff --git a/source/zh/qsl4a/storage/documentfile.md b/source/zh/qsl4a/storage/documentfile.md new file mode 100644 index 0000000..d0fe91f --- /dev/null +++ b/source/zh/qsl4a/storage/documentfile.md @@ -0,0 +1,205 @@ +# DocumentFile API + +使用 SAF（存储访问框架）进行文件操作，支持 Android 4.4+。 + +## 目录操作 + +### documentFileMkdir() +创建目录。 + +```python +documentFileMkdir(Dir) +``` + +**参数：** +- `Dir` (str): 目录路径 + +**返回：** 如果成功则为 True + +### documentFileListFiles() +列出目录中的文件。 + +```python +documentFileListFiles(Folder) +``` + +**返回：** 文件列表 + +## 文件操作 + +### documentFileExists() +检查文件或目录是否存在。 + +```python +documentFileExists(path) +``` + +**参数：** +- `path` (str): 文件或目录路径 + +**返回：** 如果存在则为 True，否则为 False + +### documentFileIsFile() +检查路径是否是文件。 + +```python +documentFileIsFile(path) +``` + +**参数：** +- `path` (str): 要检查的路径 + +**返回：** 如果是文件则为 True，如果不是文件则为 False，如果不存在则为 None + +### documentFileIsDirectory() +检查路径是否是目录。 + +```python +documentFileIsDirectory(path) +``` + +**参数：** +- `path` (str): 要检查的路径 + +**返回：** 如果是目录则为 True，如果不是目录则为 False，如果不存在则为 None + +### documentFileDelete() +删除文件或目录。 + +```python +documentFileDelete(FileOrTree) +``` + +**返回：** 如果成功则为 True + +### documentFileRenameTo() +重命名或移动文件。 + +```python +documentFileRenameTo(Src, Dest) +``` + +**返回：** 如果成功则为 True + +### documentFileCopy() +复制文件。 + +```python +documentFileCopy(SrcFileOrTree, DestFileOrTree) +``` + +## 流操作 + +### documentFileInputStream() +读取文件内容。 + +```python +documentFileInputStream(srcFile, EncodingFormat="", skip=None, length=None) +``` + +**参数：** +- `srcFile` (str): 源文件 +- `EncodingFormat` (str): "UTF-8"、"GBK"、"Base64" 或空字符串表示字节 +- `skip` (int): 从开头跳过的字节数 +- `length` (int): 读取长度 + +**返回：** 文件内容 + +### documentFileOutputStream() +写入文件内容。 + +```python +documentFileOutputStream(destFile, src, EncodingFormat="", append=None) +``` + +**参数：** +- `destFile` (str): 目标文件 +- `src`: 要写入的数据 +- `EncodingFormat` (str): 编码格式 +- `append` (bool): 追加模式 + +## 文件信息 + +### documentFileLength() +获取文件大小（字节）。 + +```python +documentFileLength(path) +``` + +**参数：** +- `path` (str): 文件路径 + +**返回：** 文件大小（字节）（如果不存在则为 0） + +### documentFileLastModified() +获取最后修改时间。 + +```python +documentFileLastModified(path) +``` + +**参数：** +- `path` (str): 文件路径 + +**返回：** 时间戳（如果不存在则为 0） + +### documentFileGetStat() +获取全面的文件统计信息。 + +```python +documentFileGetStat(path) +``` + +**参数：** +- `path` (str): 文件路径 + +**返回：** 包含长度、最后修改时间和读/写权限的字典，如果不存在则为 None + +## URI 操作 + +### documentFileGetUri() +从路径获取 URI。 + +```python +documentFileGetUri(path, isDirectory=None) +``` + +### documentFileShowOpen() +显示文件选择器。 + +```python +documentFileShowOpen() +``` + +**返回：** 选择的文件 URI + +## 使用示例 + +```python +import androidhelper + +droid = androidhelper.Android() + +# 创建目录 +droid.documentFileMkdir("/sdcard/MyFolder") + +# 列出文件 +files = droid.documentFileListFiles("/sdcard").result +for f in files: + print(f) + +# 读取文件 +content = droid.documentFileInputStream( + "/sdcard/test.txt", + EncodingFormat="UTF-8" +).result +print(content) + +# 写入文件 +droid.documentFileOutputStream( + "/sdcard/output.txt", + "Hello World", + EncodingFormat="UTF-8" +) +``` diff --git a/source/zh/qsl4a/storage/preferences.md b/source/zh/qsl4a/storage/preferences.md new file mode 100644 index 0000000..7e5143a --- /dev/null +++ b/source/zh/qsl4a/storage/preferences.md @@ -0,0 +1,81 @@ +# 偏好设置 API + +使用 Android SharedPreferences 存储和检索数据。 + +## 偏好设置方法 + +### prefGetValue() +从共享偏好设置读取值。 + +```python +prefGetValue(key, filename=None) +``` + +**参数：** +- `key` (str): 偏好设置键 +- `filename` (str, optional): 偏好设置文件名 + +**返回：** 存储的值（任意类型） + +### prefPutValue() +写入值到共享偏好设置。 + +```python +prefPutValue(key, value, filename=None) +``` + +**参数：** +- `key` (str): 偏好设置键 +- `value` (object): 要存储的值 +- `filename` (str, optional): 偏好设置文件名 + +### prefGetAll() +获取所有偏好设置值。 + +```python +prefGetAll(filename=None) +``` + +**参数：** +- `filename` (str, optional): 偏好设置文件名 + +**返回：** 所有偏好的映射 + +### prefRemoveValue() +从共享偏好设置中移除值。 + +```python +prefRemoveValue(key, filename=None) +``` + +**参数：** +- `key` (str): 要移除的偏好设置键 +- `filename` (str, optional): 偏好设置文件名 + +## 使用示例 + +```python +import androidhelper + +droid = androidhelper.Android() + +# 存储值 +droid.prefPutValue("username", "alice") +droid.prefPutValue("score", 100) +droid.prefPutValue("enabled", True) + +# 读取特定值 +username = droid.prefGetValue("username").result +print(f"Username: {username}") + +# 获取所有偏好设置 +all_prefs = droid.prefGetAll().result +print(f"All prefs: {all_prefs}") + +# 移除值 +droid.prefRemoveValue("score") + +# 使用自定义文件名 +droid.prefPutValue("token", "abc123", filename="auth.prefs") +token = droid.prefGetValue("token", filename="auth.prefs").result +``` diff --git a/source/zh/qsl4a/system/activityresult.md b/source/zh/qsl4a/system/activityresult.md new file mode 100644 index 0000000..845294c --- /dev/null +++ b/source/zh/qsl4a/system/activityresult.md @@ -0,0 +1,230 @@ +# Activity Result API + +为通过 `startActivityForResult` 启动的脚本设置 activity 结果。 + +## 结果方法 + +### setResultBoolean() +设置布尔结果。 + +```python +setResultBoolean(resultCode, resultValue) +``` + +**参数：** +- `resultCode` (int): 结果代码 +- `resultValue` (bool): 布尔结果值 + +### setResultByte() +设置字节结果。 + +```python +setResultByte(resultCode, resultValue) +``` + +**参数：** +- `resultCode` (int): 结果代码 +- `resultValue` (int): 字节结果值 + +### setResultShort() +设置短整数结果。 + +```python +setResultShort(resultCode, resultValue) +``` + +**参数：** +- `resultCode` (int): 结果代码 +- `resultValue` (int): 短整数结果值 + +### setResultChar() +设置字符结果。 + +```python +setResultChar(resultCode, resultValue) +``` + +**参数：** +- `resultCode` (int): 结果代码 +- `resultValue` (str): 字符结果值 + +### setResultInteger() +设置整数结果。 + +```python +setResultInteger(resultCode, resultValue) +``` + +**参数：** +- `resultCode` (int): 结果代码 +- `resultValue` (int): 整数结果值 + +### setResultLong() +设置长整数结果。 + +```python +setResultLong(resultCode, resultValue) +``` + +**参数：** +- `resultCode` (int): 结果代码 +- `resultValue` (int): 长整数结果值 + +### setResultFloat() +设置浮点数结果。 + +```python +setResultFloat(resultCode, resultValue) +``` + +**参数：** +- `resultCode` (int): 结果代码 +- `resultValue` (float): 浮点数结果值 + +### setResultDouble() +设置双精度浮点数结果。 + +```python +setResultDouble(resultCode, resultValue) +``` + +**参数：** +- `resultCode` (int): 结果代码 +- `resultValue` (float): 双精度浮点数结果值 + +### setResultString() +设置字符串结果。 + +```python +setResultString(resultCode, resultValue) +``` + +**参数：** +- `resultCode` (int): 结果代码 +- `resultValue` (str): 字符串结果值 + +### setResultBooleanArray() +设置布尔数组结果。 + +```python +setResultBooleanArray(resultCode, resultValue) +``` + +**参数：** +- `resultCode` (int): 结果代码 +- `resultValue` (list): 布尔数组 + +### setResultByteArray() +设置字节数组结果。 + +```python +setResultByteArray(resultCode, resultValue) +``` + +**参数：** +- `resultCode` (int): 结果代码 +- `resultValue` (list): 字节数组 + +### setResultShortArray() +设置短整数数组结果。 + +```python +setResultShortArray(resultCode, resultValue) +``` + +**参数：** +- `resultCode` (int): 结果代码 +- `resultValue` (list): 短整数数组 + +### setResultCharArray() +设置字符数组结果。 + +```python +setResultCharArray(resultCode, resultValue) +``` + +**参数：** +- `resultCode` (int): 结果代码 +- `resultValue` (list): 字符数组 + +### setResultIntegerArray() +设置整数数组结果。 + +```python +setResultIntegerArray(resultCode, resultValue) +``` + +**参数：** +- `resultCode` (int): 结果代码 +- `resultValue` (list): 整数数组 + +### setResultLongArray() +设置长整数数组结果。 + +```python +setResultLongArray(resultCode, resultValue) +``` + +**参数：** +- `resultCode` (int): 结果代码 +- `resultValue` (list): 长整数数组 + +### setResultFloatArray() +设置浮点数数组结果。 + +```python +setResultFloatArray(resultCode, resultValue) +``` + +**参数：** +- `resultCode` (int): 结果代码 +- `resultValue` (list): 浮点数数组 + +### setResultDoubleArray() +设置双精度浮点数数组结果。 + +```python +setResultDoubleArray(resultCode, resultValue) +``` + +**参数：** +- `resultCode` (int): 结果代码 +- `resultValue` (list): 双精度浮点数数组 + +### setResultStringArray() +设置字符串数组结果。 + +```python +setResultStringArray(resultCode, resultValue) +``` + +**参数：** +- `resultCode` (int): 结果代码 +- `resultValue` (list): 字符串数组 + +### setResultSerializable() +设置可序列化结果。 + +```python +setResultSerializable(resultCode, resultValue) +``` + +**参数：** +- `resultCode` (int): 结果代码 +- `resultValue`: 可序列化结果值 + +## 使用示例 + +```python +import androidhelper + +droid = androidhelper.Android() + +# 执行 activity 后，设置结果 +# 示例：返回成功及数据 +droid.setResultInteger(0, 200) # RESULT_OK +droid.setResultString(0, "Operation completed successfully") + +# 返回数组结果 +droid.setResultIntegerArray(0, [1, 2, 3, 4, 5]) +``` diff --git a/source/zh/qsl4a/system/application.md b/source/zh/qsl4a/system/application.md new file mode 100644 index 0000000..a5d8b4f --- /dev/null +++ b/source/zh/qsl4a/system/application.md @@ -0,0 +1,269 @@ +# 应用管理 + +管理应用程序、启动应用和查询系统信息。 + +## 应用程序信息 + +### getApplicationInfo() +获取应用信息。 + +```python +getApplicationInfo(packageName=None) +``` + +**参数：** +- `packageName` (str): 包名（None = 当前应用） + +**返回：** 应用信息字典 + +### getInstalledPackages() +获取已安装包列表。 + +```python +getInstalledPackages(flag=4) +``` + +**参数：** +- `flag` (int): 包标志过滤器（默认：4） + +**返回：** 已安装包列表 + +### getRunningPackages() +列出正在运行的包。 + +```python +getRunningPackages() +``` + +**返回：** 包名列表 + +### getLaunchablePackages() +获取可启动包列表。 + +```python +getLaunchablePackages(needClassName=False) +``` + +**参数：** +- `needClassName` (bool): 包含主 activity 类名（默认：False） + +**返回：** 可启动包名列表或包含类名的字典 + +## 应用控制 + +### launch() +启动应用程序。 + +```python +launch(classname=None, packagename=None, wait=True) +``` + +**参数：** +- `classname` (str): 主 activity 类名 +- `packagename` (str): 包名 +- `wait` (bool): 等待启动完成（默认：True） + +**返回：** 启动结果 + +### forceStopPackage() +强制停止应用程序。 + +```python +forceStopPackage(packageName) +``` + +**参数：** +- `packageName` (str): 要停止的包名 + +## 版本信息 + +### getPackageVersion() +获取应用版本名称。 + +```python +getPackageVersion(packageName) +``` + +**返回：** 版本字符串（例如 "3.2.1"） + +### getPackageVersionCode() +获取应用版本代码。 + +```python +getPackageVersionCode(packageName) +``` + +**返回：** 版本代码整数 + +### getConstants() +获取类常量。 + +```python +getConstants(classname) +``` + +**参数：** +- `classname` (str): 完整类名 + +**返回：** 常量名和值的字典 + +## 系统功能 + +### backgroundProtect() +启用或禁用应用的后台保护。 + +```python +backgroundProtect(enabled=True) +``` + +**参数：** +- `enabled` (bool): True 启用保护，False 禁用 + +### createScriptShortCut() +为脚本创建主屏幕快捷方式。 + +```python +createScriptShortCut(scriptPath, label=None, iconPath=None, scriptArg=None) +``` + +**参数：** +- `scriptPath` (str): Python 脚本路径 +- `label` (str, optional): 快捷方式标签 +- `iconPath` (str, optional): 图标图像路径 +- `scriptArg` (str, optional): 传递给脚本的参数 + +## 设备信息 + +### getAndroidID() +获取 Android 设备 ID。 + +```python +getAndroidID() +``` + +**返回：** 唯一的 Android 设备 ID 字符串 + +### getSysInfo() +获取系统信息。 + +```python +getSysInfo() +``` + +**返回：** 包含系统详情的字典 + +### getLocale() +获取设备语言环境。 + +```python +getLocale() +``` + +**返回：** 语言环境字符串（例如 "en_US"） + +### getHarmonyOsInformation() +如果在 HarmonyOS 上运行，获取 HarmonyOS 信息。 + +```python +getHarmonyOsInformation() +``` + +**返回：** HarmonyOS 版本信息或 None + +### isExternalStorageManager() +检查应用是否有外部存储管理器权限。 + +```python +isExternalStorageManager() +``` + +**返回：** 如果有权限则为 True + +## 内存和显示 + +### getMemoryInfo() +获取内存信息。 + +```python +getMemoryInfo() +``` + +**返回：** 包含内存统计的字典 + +### getScreenInfo() +获取屏幕信息。 + +```python +getScreenInfo() +``` + +**返回：** 包含宽度、高度、密度的字典 + +## 权限 + +### checkPermissions() +检查当前应用权限。 + +```python +checkPermissions() +``` + +**返回：** 权限及其状态的字典 + +### requestPermissions() +向用户请求权限。 + +```python +requestPermissions(permissions=None) +``` + +**参数：** +- `permissions` (list, optional): 要请求的权限列表。如果为 None，则请求所有需要的权限。 + +**返回：** 权限请求结果 + +## 系统操作 + +### showScreenLock() +显示屏幕锁定（PIN/图案/密码输入）。 + +```python +showScreenLock() +``` + +## 使用示例 + +```python +import androidhelper + +droid = androidhelper.Android() + +# 获取系统信息 +info = droid.getSysInfo().result +print(f"System: {info}") + +# 获取应用版本 +version = droid.getPackageVersion("org.qpython.qpy").result +print(f"QPython version: {version}") + +# 列出已安装应用 +apps = droid.getInstalledPackages().result +print(f"Installed apps: {len(apps)}") + +# 启动应用 +droid.launch(packagename="com.android.settings") + +# 检查权限 +perms = droid.checkPermissions().result +print(f"Permissions: {perms}") + +# 请求存储权限 +droid.requestPermissions(["android.permission.READ_EXTERNAL_STORAGE"]) + +# 创建快捷方式 +droid.createScriptShortCut( + "/sdcard/my_script.py", + label="My Script", + iconPath="/sdcard/icon.png" +) +``` diff --git a/source/zh/qsl4a/system/battery.md b/source/zh/qsl4a/system/battery.md new file mode 100644 index 0000000..27efd2c --- /dev/null +++ b/source/zh/qsl4a/system/battery.md @@ -0,0 +1,91 @@ +# 电池 API + +监控设备电池状态和健康状况。 + +## 方法 + +### readBatteryData() +获取完整的电池信息。 + +```python +readBatteryData() +``` + +**返回：** 包含电池数据的字典 + +### batteryStartMonitoring() +开始电池监控。 + +```python +batteryStartMonitoring() +``` + +### batteryStopMonitoring() +停止电池监控。 + +```python +batteryStopMonitoring() +``` + +### batteryGetLevel() +获取电池百分比。 + +```python +batteryGetLevel() +``` + +**返回：** 整数（0-100） + +### batteryGetStatus() +获取充电状态。 + +```python +batteryGetStatus() +``` + +**返回：** +- 1: 未知 +- 2: 充电中 +- 3: 放电中 +- 4: 未充电 +- 5: 已充满 + +### batteryGetPlugType() +获取电源类型。 + +```python +batteryGetPlugType() +``` + +**返回：** +- -1: 未知 +- 0: 未插电 +- 1: AC 充电器 +- 2: USB 端口 + +### batteryGetHealth() +获取电池健康状况。 + +```python +batteryGetHealth() +``` + +**返回：** +- 1: 未知 +- 2: 良好 +- 3: 过热 +- 4: 损坏 +- 5: 过压 +- 6: 未指定的故障 + +## 使用示例 + +```python +import androidhelper + +droid = androidhelper.Android() + +# 获取电池电量 +level = droid.batteryGetLevel().result +print(f"Battery: {level}%") +``` diff --git a/source/zh/qsl4a/system/qpyinterface.md b/source/zh/qsl4a/system/qpyinterface.md new file mode 100644 index 0000000..c523604 --- /dev/null +++ b/source/zh/qsl4a/system/qpyinterface.md @@ -0,0 +1,131 @@ +# QPython 接口 API + +从其他应用执行 QPython 脚本和管理共享变量。 + +## 脚本执行方法 + +### executeQPy() +执行 QPython 脚本。 + +```python +executeQPy(path="", arg=None) +``` + +**参数：** +- `path` (str): 脚本文件路径 +- `arg` (str, optional): 命令行参数 + +**返回：** 如果启动成功则为 True + +### executeQPyAsSrv() +作为服务执行 QPython 脚本。 + +```python +executeQPyAsSrv(path=None) +``` + +**参数：** +- `path` (str, optional): 脚本文件路径 + +**返回：** 如果启动成功则为 True + +### executeQPyCode() +直接执行 Python 代码。 + +```python +executeQPyCode(code=None) +``` + +**参数：** +- `code` (str, optional): 要执行的 Python 代码 + +**返回：** 如果启动成功则为 True + +### executeQPyCodeAsSrv() +作为服务执行 Python 代码。 + +```python +executeQPyCodeAsSrv(code=None) +``` + +**参数：** +- `code` (str, optional): 要执行的 Python 代码 + +**返回：** 如果启动成功则为 True + +## 共享变量 + +共享变量允许 QPython 与其他应用之间进行通信。 + +### sharedVariableSet() +设置 Java 共享变量。 + +```python +sharedVariableSet(key, value) +``` + +**参数：** +- `key` (str): 变量名 +- `value` (str): 变量值 + +**返回：** 存储的值 + +### sharedVariableGet() +获取 Java 共享变量。 + +```python +sharedVariableGet(key) +``` + +**参数：** +- `key` (str): 变量名 + +**返回：** 存储的值 + +### sharedVariableRemove() +移除 Java 共享变量。 + +```python +sharedVariableRemove(key) +``` + +**参数：** +- `key` (str): 要移除的变量名 + +**返回：** 被移除的值 + +### getLastLog() +获取 QPython 的最后日志输出。 + +```python +getLastLog() +``` + +**返回：** 字符串日志内容 + +## 使用示例 + +```python +import androidhelper + +droid = androidhelper.Android() + +# 执行脚本 +droid.executeQPy("/sdcard/my_script.py", arg="test") + +# 直接执行代码 +code = "print('Hello from QPython!')" +droid.executeQPyCode(code) + +# 使用共享变量 +droid.sharedVariableSet("username", "alice") +username = droid.sharedVariableGet("username").result +print(f"Username: {username}") + +# 移除变量 +droid.sharedVariableRemove("username") + +# 获取最近日志 +log = droid.getLastLog().result +print(f"Log: {log}") +``` diff --git a/source/zh/qsl4a/system/sensors.md b/source/zh/qsl4a/system/sensors.md new file mode 100644 index 0000000..b2d0d92 --- /dev/null +++ b/source/zh/qsl4a/system/sensors.md @@ -0,0 +1,127 @@ +# 传感器 API + +访问设备传感器，包括加速度计、陀螺仪、磁力计等。 + +## 方法 + +### startSensingTimed() +开始传感器监控并设置时间间隔。 + +```python +startSensingTimed(sensorNumber, delayTime) +``` + +**参数：** +- `sensorNumber` (int): 传感器 ID（通常为 1-3） +- `delayTime` (int): 读取之间的延迟（毫秒） + +### startSensingThreshold() +开始带阈值触发的传感器监控。 + +```python +startSensingThreshold(sensorNumber, threshold, axis) +``` + +**参数：** +- `sensorNumber` (int): 传感器 ID +- `threshold` (float): 触发阈值 +- `axis` (int): 要监控的轴（0=X，1=Y，2=Z） + +### stopSensing() +停止所有传感器监控。 + +```python +stopSensing() +``` + +### readSensors() +读取当前传感器数据。 + +```python +readSensors() +``` + +**返回：** 传感器数据字典 + +### sensorsReadAccelerometer() +读取加速度计值。 + +```python +sensorsReadAccelerometer() +``` + +**返回：** 列表 [X, Y, Z]，单位 m/s² + +### sensorsReadGyroscope() +读取陀螺仪值。 + +```python +sensorsReadGyroscope() +``` + +**返回：** 列表 [X, Y, Z]，单位 rad/s + +### sensorsReadMagnetometer() +读取磁场值。 + +```python +sensorsReadMagnetometer() +``` + +**返回：** 列表 [X, Y, Z]，单位 μT + +### sensorsReadOrientation() +读取设备方向。 + +```python +sensorsReadOrientation() +``` + +**返回：** 列表 [azimuth, pitch, roll]，单位度 + +### sensorsGetLight() +读取光传感器值。 + +```python +sensorsGetLight() +``` + +**返回：** 光级别（lux） + +### sensorsGetStepCounter() +读取步计数器。 + +```python +sensorsGetStepCounter() +``` + +**返回：** 步数 + +### sensorsGetAccuracy() +获取当前传感器精度。 + +```python +sensorsGetAccuracy() +``` + +**返回：** 精度值（0-3：UNRELIABLE、ACCURACY_LOW、ACCURACY_MEDIUM、ACCURACY_HIGH） + +## 使用示例 + +```python +import androidhelper +import time + +droid = androidhelper.Android() + +# 开始感知 +droid.startSensingTimed(1, 250) + +# 读取传感器 10 次 +for i in range(10): + accel = droid.sensorsReadAccelerometer().result + print(f"Accel: X={accel[0]:.2f}, Y={accel[1]:.2f}, Z={accel[2]:.2f}") + time.sleep(0.5) + +droid.stopSensing() +``` diff --git a/source/zh/qsl4a/system/settings.md b/source/zh/qsl4a/system/settings.md new file mode 100644 index 0000000..52f1fb8 --- /dev/null +++ b/source/zh/qsl4a/system/settings.md @@ -0,0 +1,234 @@ +# 设置 API + +控制系统设置，包括屏幕、声音和网络设置。 + +## 屏幕设置 + +### setScreenTimeout() +设置屏幕超时值。 + +```python +setScreenTimeout(value) +``` + +**参数：** +- `value` (int): 屏幕超时时间（秒） + +**返回：** 之前的超时值 + +### getScreenTimeout() +获取当前屏幕超时。 + +```python +getScreenTimeout() +``` + +**返回：** 当前屏幕超时时间（秒） + +### getScreenBrightness() +获取屏幕亮度值。 + +```python +getScreenBrightness() +``` + +**返回：** 亮度值（0-255） + +### setScreenBrightness() +设置屏幕亮度。 + +```python +setScreenBrightness(value=None) +``` + +**参数：** +- `value` (int, optional): 亮度值（0-255），或 None 表示自动 + +**返回：** 之前的亮度值 + +### checkScreenOn() +检查屏幕是否亮着。 + +```python +checkScreenOn() +``` + +**返回：** 如果屏幕亮着则为 True，否则为 False + +## 飞行模式 + +### checkAirplaneMode() +检查飞行模式是否启用。 + +```python +checkAirplaneMode() +``` + +**返回：** 如果飞行模式开着则为 True + +## 铃声设置 + +### checkRingerSilentMode() +检查铃声是否处于静音模式。 + +```python +checkRingerSilentMode() +``` + +**返回：** 如果静音模式开着则为 True + +### toggleRingerSilentMode() +切换铃声静音模式。 + +```python +toggleRingerSilentMode(enabled=None) +``` + +**参数：** +- `enabled` (bool, optional): True 启用，False 禁用，None 切换 + +**返回：** 新状态 + +### toggleVibrateMode() +切换振动模式。 + +```python +toggleVibrateMode(enabled=None, ringer=None) +``` + +**参数：** +- `enabled` (bool, optional): 切换振动开/关 +- `ringer` (bool, optional): 应用于铃声模式 + +**返回：** 新状态 + +### getVibrateMode() +获取振动模式设置。 + +```python +getVibrateMode(ringer=None) +``` + +**参数：** +- `ringer` (bool, optional): 检查铃声振动模式 + +**返回：** 如果振动已启用则为 True + +## 音量设置 + +### getRingerVolume() +获取当前铃声音量。 + +```python +getRingerVolume() +``` + +**返回：** 铃声音量级别（通常为 0-7） + +### getMaxRingerVolume() +获取最大铃声音量。 + +```python +getMaxRingerVolume() +``` + +**返回：** 最大铃声音量 + +### setRingerVolume() +设置铃声音量。 + +```python +setRingerVolume(volume) +``` + +**参数：** +- `volume` (int): 音量级别 + +### getMediaVolume() +获取当前媒体音量。 + +```python +getMediaVolume() +``` + +**返回：** 媒体音量级别（通常为 0-15） + +### getMaxMediaVolume() +获取最大媒体音量。 + +```python +getMaxMediaVolume() +``` + +**返回：** 最大媒体音量 + +### setMediaVolume() +设置媒体音量。 + +```python +setMediaVolume(volume) +``` + +**参数：** +- `volume` (int): 音量级别 + +## 系统信息 + +### elapsedRealtimeNanos() +获取自系统启动以来的纳秒数。 + +```python +elapsedRealtimeNanos() +``` + +**返回：** 纳秒数（可用于计时） + +### getTrafficStats() +获取网络流量统计。 + +```python +getTrafficStats(flags=7) +``` + +**参数：** +- `flags` (int): 要检索的统计（默认：7 = 全部） + +**返回：** 包含发送/接收字节的字典 + +### getAppTxBytes() +获取 QPython 应用的发送字节。 + +```python +getAppTxBytes(packageName) +``` + +**参数：** +- `packageName` (str): 包名 + +**返回：** 包含 tx/rx 字节的字典 + +## 使用示例 + +```python +import androidhelper + +droid = androidhelper.Android() + +# 屏幕设置 +current_timeout = droid.getScreenTimeout().result +print(f"Current timeout: {current_timeout}s") +droid.setScreenTimeout(30) + +# 检查屏幕 +if droid.checkScreenOn().result: + print("Screen is on") + +# 音量控制 +media_vol = droid.getMediaVolume().result +print(f"Media volume: {media_vol}") +droid.setMediaVolume(10) + +# 检查飞行模式 +if droid.checkAirplaneMode().result: + print("Airplane mode is on") +``` diff --git a/source/zh/qsl4a/system/sysinfo.md b/source/zh/qsl4a/system/sysinfo.md new file mode 100644 index 0000000..132c1cc --- /dev/null +++ b/source/zh/qsl4a/system/sysinfo.md @@ -0,0 +1,90 @@ +# 系统信息 + +检索设备和系统信息。 + +## 设备信息 + +### getAndroidID() +获取 Android 设备 ID。 + +```python +getAndroidID() +``` + +**返回：** 字符串设备 ID + +### getSysInfo() +获取综合系统信息。 + +```python +getSysInfo() +``` + +**返回：** 包含系统详情的字典 + +### getLocale() +获取设备语言环境设置。 + +```python +getLocale() +``` + +**返回：** 语言环境字符串（例如 "en_US"） + +## 内存 + +### getMemoryInfo() +获取 RAM 信息。 + +```python +getMemoryInfo() +``` + +**返回：** 包含内存统计的字典 + +## 显示 + +### getScreenInfo() +获取显示信息。 + +```python +getScreenInfo() +``` + +**返回：** 包含宽度、高度、密度的字典 + +## 标识符 + +### getImei() +获取设备 IMEI。 + +```python +getImei(slotIndex=None) +``` + +### getMeid() +获取设备 MEID。 + +```python +getMeid(slotIndex=None) +``` + +## 使用示例 + +```python +import androidhelper + +droid = androidhelper.Android() + +# 设备 ID +android_id = droid.getAndroidID().result +print(f"Android ID: {android_id}") + +# 屏幕信息 +screen = droid.getScreenInfo().result +print(f"Screen: {screen['width']}x{screen['height']}") + +# 内存 +memory = droid.getMemoryInfo().result +print(f"Memory: {memory}") +``` diff --git a/source/zh/qsl4a/system/wakelock.md b/source/zh/qsl4a/system/wakelock.md new file mode 100644 index 0000000..5322945 --- /dev/null +++ b/source/zh/qsl4a/system/wakelock.md @@ -0,0 +1,78 @@ +# WakeLock API + +控制设备唤醒锁以保持 CPU 或屏幕开启。 + +## Wake Lock 类型 + +QSL4A 提供不同类型的唤醒锁： + +| 类型 | 描述 | +|------|-------------| +| Full | CPU 开启，屏幕亮，键盘亮 | +| Partial | 仅 CPU 开启 | +| Bright | CPU 开启，屏幕亮 | +| Dim | CPU 开启，屏幕暗 | + +## Wake Lock 方法 + +### wakeLockAcquireFull() +获取完整唤醒锁（CPU 开启，屏幕亮，键盘亮）。 + +```python +wakeLockAcquireFull() +``` + +### wakeLockAcquirePartial() +获取部分唤醒锁（仅 CPU 开启）。 + +```python +wakeLockAcquirePartial() +``` + +### wakeLockAcquireBright() +获取明亮唤醒锁（CPU 开启，屏幕亮）。 + +```python +wakeLockAcquireBright() +``` + +### wakeLockAcquireDim() +获取暗淡唤醒锁（CPU 开启，屏幕暗）。 + +```python +wakeLockAcquireDim() +``` + +### wakeLockRelease() +释放唤醒锁。 + +```python +wakeLockRelease() +``` + +## 使用示例 + +```python +import androidhelper +import time + +droid = androidhelper.Android() + +# 获取完整唤醒锁 +droid.wakeLockAcquireFull() + +# 在保持屏幕开启时执行重要工作 +print("Screen will stay on") +time.sleep(10) + +# 完成后释放 +droid.wakeLockRelease() + +# 或使用部分锁进行后台任务 +droid.wakeLockAcquirePartial() +# 即使屏幕关闭，CPU 仍保持开启 +time.sleep(30) +droid.wakeLockRelease() +``` + +**注意：** 记住在不需要时释放唤醒锁以节省电池。 diff --git a/source/zh/qsl4a/ui/accessibility.md b/source/zh/qsl4a/ui/accessibility.md new file mode 100644 index 0000000..54bf53b --- /dev/null +++ b/source/zh/qsl4a/ui/accessibility.md @@ -0,0 +1,123 @@ +# 无障碍服务 + +无障碍服务允许自动化 UI 交互，如点击、滑动和系统操作。 + +## 服务控制 + +### accessibilityStartService() +启动无障碍服务。 + +```python +accessibilityStartService() +``` + +**返回：** 如果成功则为 `True`，否则为 `False` + +### accessibilityServiceEnabled() +检查无障碍服务是否已启用。 + +```python +accessibilityServiceEnabled() +``` + +**返回：** `True` 或 `False` + +## 屏幕交互 + +### accessibilityClick() +在屏幕坐标处点击。 + +```python +accessibilityClick(x=0, y=0, t=50) +``` + +**参数：** +- `x` (int/float): X 坐标（0=居中，支持小数） +- `y` (int/float): Y 坐标（0=居中，支持小数） +- `t` (int): 按住时长（毫秒）（默认：50） + +### accessibilitySlide() +多点滑动手势。 + +```python +accessibilitySlide(XnYn=None, t=None) +``` + +**参数：** +- `XnYn` (list): 坐标 [X1, Y1, X2, Y2, ... Xn, Yn] +- `t` (int): 滑动时长（默认：50*n 毫秒） + +## 系统操作 + +### accessibilityAction() +按代码执行系统操作。 + +```python +accessibilityAction(actionCode) +``` + +**操作代码：** +| 代码 | 常量 | 描述 | +|------|----------|-------------| +| 1 | BACK | 返回按钮 | +| 2 | HOME | 主屏幕按钮 | +| 3 | RECENTS | 最近应用 | +| 4 | NOTIFICATIONS | 打开通知 | +| 5 | QUICK_SETTINGS | 打开快速设置 | +| 6 | POWER_DIALOG | 电源菜单 | +| 7 | TOGGLE_SPLIT_SCREEN | 分屏 | +| 8 | LOCK_SCREEN | 锁屏 | +| 9 | TAKE_SCREENSHOT | 截图 | +| 10 | KEYCODE_HEADSETHOOK | 耳机挂钩 | +| 11-14 | ACCESSIBILITY_* | 无障碍按钮 | +| 15 | DISMISS_NOTIFICATION_SHADE | 关闭通知栏 | +| 16-20 | DPAD_* | 方向键 | +| 21 | MENU | 菜单按钮 | +| 22 | MEDIA_PLAY_PAUSE | 播放/暂停媒体 | + +## 使用示例 + +### 点击屏幕中心 + +```python +import androidhelper + +droid = androidhelper.Android() + +# 启动服务 +if not droid.accessibilityServiceEnabled().result: + droid.accessibilityStartService() + +# 点击中心（0,0 = 中心） +droid.accessibilityClick(0, 0, t=100) +``` + +### 滑动手势 + +```python +# 从下往上滑动（向上滚动） +droid.accessibilitySlide([0, 1.5, 0, -1.5], t=300) +``` + +### 系统导航 + +```python +# 按主屏幕 +droid.accessibilityAction(2) + +# 按返回 +droid.accessibilityAction(1) + +# 打开通知 +droid.accessibilityAction(4) +``` + +### 点击特定位置 + +```python +# 点击屏幕坐标 (500, 800) +droid.accessibilityClick(500, 800) + +# 点击相对位置（水平居中，垂直 3/4 处） +droid.accessibilityClick(0, 1.5) +``` diff --git a/source/zh/qsl4a/ui/dialogs.md b/source/zh/qsl4a/ui/dialogs.md new file mode 100644 index 0000000..454475b --- /dev/null +++ b/source/zh/qsl4a/ui/dialogs.md @@ -0,0 +1,321 @@ +# 对话框系统 + +QSL4A 提供全面的对话框支持，用于用户交互，包括警报、输入对话框、选择对话框和进度对话框。 + +## 警报对话框 + +### dialogShowAlert() +显示简单警报对话框。 + +```python +dialogShowAlert(title="Alert", message="The message of the alert.", + positiveButtonText="OK", negativeButtonText=None, + neutralButtonText=None, messageIsHtml=False) +``` + +**参数：** +- `title` (str): 对话框标题 +- `message` (str): 消息文本 +- `positiveButtonText` (str): 肯定按钮标签 +- `negativeButtonText` (str, optional): 否定按钮标签 +- `neutralButtonText` (str, optional): 中性按钮标签 +- `messageIsHtml` (bool): 将消息解析为 HTML + +**返回：** 包含点击按钮的结果 + +### dialogShowSimpleChoice() +显示带有项目的简单选择对话框。 + +```python +dialogShowSimpleChoice(title="Alert", message="The message of the alert.", + items=None, positiveButtonText="OK", + negativeButtonText=None, neutralButtonText=None, + messageIsHtml=False) +``` + +**参数：** +- `items` (list): 选择字符串列表 + +**返回：** 包含选中项目的结果 + +## 输入对话框 + +### dialogGetInput() +获取用户文本输入。 + +```python +dialogGetInput(title="Value", message="Please enter value:", + defaultText=None, messageIsHtml=False) +``` + +**返回：** 包含用户输入文本的结果 + +### dialogGetPassword() +获取密码输入。 + +```python +dialogGetPassword(title="Password", message="Please enter password:") +``` + +**返回：** 包含输入密码的结果 + +### dialogCreateInput() +创建自定义输入对话框。 + +```python +dialogCreateInput(title="Value", message="Please enter value:", + defaultText=None, inputType=None) +``` + +**参数：** +- `inputType` (str): 输入类型（例如 "text"、"number"、"textPassword"） + +### dialogCreatePassword() +创建密码输入对话框。 + +```python +dialogCreatePassword(title="Password", message="Please enter password:") +``` + +### dialogCreateSeekBar() +创建滑块/进度条对话框。 + +```python +dialogCreateSeekBar(starting_value=50, maximum_value=100, title="", message="") +``` + +**参数：** +- `starting_value` (int): 初始值 +- `maximum_value` (int): 最大值 + +## 选择对话框 + +### dialogShowSingleChoice() +显示单选（单选按钮）对话框。 + +```python +dialogShowSingleChoice(title="Alert", message="The message of the alert.", + items=None, selected=-1, positiveButtonText="OK", + negativeButtonText=None, neutralButtonText=None, + messageIsHtml=False) +``` + +**参数：** +- `items` (list): 选择字符串列表 +- `selected` (int): 默认选中索引 + +### dialogShowMultiChoice() +显示多选（复选框）对话框。 + +```python +dialogShowMultiChoice(title="Alert", message="The message of the alert.", + items=None, selected=None, positiveButtonText="OK", + negativeButtonText=None, neutralButtonText=None, + messageIsHtml=False) +``` + +**参数：** +- `items` (list): 选择字符串列表 +- `selected` (list): 初始选中索引列表 + +### dialogSetSingleChoiceItems() +为对话框设置单选项目。 + +```python +dialogSetSingleChoiceItems(items, selected=-1) +``` + +### dialogSetMultiChoiceItems() +为对话框设置多选项目。 + +```python +dialogSetMultiChoiceItems(items, selected=None) +``` + +## 进度对话框 + +### dialogCreateSpinnerProgress() +创建不确定进度对话框。 + +```python +dialogCreateSpinnerProgress(title=None, message=None, maximum_progress=100) +``` + +### dialogCreateHorizontalProgress() +创建水平进度对话框。 + +```python +dialogCreateHorizontalProgress(title=None, message=None, maximum_progress=100) +``` + +### dialogSetCurrentProgress() +更新进度值。 + +```python +dialogSetCurrentProgress(current) +``` + +### dialogSetMaxProgress() +设置最大进度值。 + +```python +dialogSetMaxProgress(max) +``` + +### dialogSetProgressMessage() +更新进度对话框消息。 + +```python +dialogSetProgressMessage(message) +``` + +## 选择器对话框 + +### dialogCreateDatePicker() +创建日期选择器对话框。 + +```python +dialogCreateDatePicker(year=1970, month=1, day=1) +``` + +### dialogCreateTimePicker() +创建时间选择器对话框。 + +```python +dialogCreateTimePicker(hour=0, minute=0, is24hour=False) +``` + +## 自定义对话框创建 + +### dialogCreateAlert() +创建自定义警报对话框。 + +```python +dialogCreateAlert(title=None, message=None) +``` + +创建一个空警报对话框。可与其他 dialogSet* 函数一起使用来自定义。 + +### dialogSetItems() +为对话框设置简单列表项目。 + +```python +dialogSetItems(items) +``` + +### dialogSetPositiveButtonText() +设置肯定按钮文本。 + +```python +dialogSetPositiveButtonText(text) +``` + +### dialogSetNegativeButtonText() +设置否定按钮文本。 + +```python +dialogSetNegativeButtonText(text) +``` + +### dialogSetNeutralButtonText() +设置中性按钮文本。 + +```python +dialogSetNeutralButtonText(text) +``` + +### dialogSetMessageIsHtml() +设置消息是否应解析为 HTML。 + +```python +dialogSetMessageIsHtml(messageIsHtml=True) +``` + +### dialogShow() +显示创建的自定义对话框。 + +```python +dialogShow() +``` + +## 对话框控制 + +### dialogDismiss() +关闭当前对话框。 + +```python +dialogDismiss() +``` + +### dialogGetResponse() +获取对话框响应。 + +```python +dialogGetResponse() +``` + +### dialogGetSelectedItems() +从选择对话框获取选中的项目。 + +```python +dialogGetSelectedItems() +``` + +## 使用示例 + +### 简单警报 + +```python +import androidhelper + +droid = androidhelper.Android() + +# 显示警报 +droid.dialogShowAlert("Warning", "This is an important message!") +``` + +### 输入对话框 + +```python +# 获取用户输入 +result = droid.dialogGetInput("Name", "Enter your name:", "John").result +print(f"Hello, {result}!") +``` + +### 带按钮的自定义对话框 + +```python +# 创建自定义对话框 +droid.dialogCreateAlert("Custom", "Choose an option") +droid.dialogSetItems(["Option 1", "Option 2", "Option 3"]) +droid.dialogShow() + +# 获取响应 +response = droid.dialogGetResponse().result +print(f"Selected: {response['item']}") +``` + +### 进度对话框 + +```python +# 创建进度对话框 +droid.dialogCreateHorizontalProgress("Loading", "Please wait...", 100) +droid.dialogShow() + +# 更新进度 +for i in range(101): + droid.dialogSetCurrentProgress(i) + time.sleep(0.05) + +droid.dialogDismiss() +``` + +### 日期选择器 + +```python +# 显示日期选择器 +droid.dialogCreateDatePicker(2024, 1, 15) +droid.dialogShow() +response = droid.dialogGetResponse().result +print(f"Selected: {response}") +``` diff --git a/source/zh/qsl4a/ui/floatview.md b/source/zh/qsl4a/ui/floatview.md new file mode 100644 index 0000000..33d3c30 --- /dev/null +++ b/source/zh/qsl4a/ui/floatview.md @@ -0,0 +1,174 @@ +# 浮动视图 + +浮动窗口支持，用于在其他应用程序上方保持显示的覆盖 UI 元素。 + +## 方法 + +### floatView() +显示或修改浮动视图。 + +```python +floatView(Args=None) +``` + +**参数：** +- `Args` (dict): 配置字典，包含以下键： + - `index` (int): 浮动视图索引（-1 创建新的，>=0 修改现有的） + - `text` (str): 要显示的文本内容 + - `html` (str): HTML 内容（如果省略 text 则使用） + - `width` (int): 视图宽度（像素）（默认：300） + - `height` (int): 视图高度（像素）（默认：150） + - `x` (int): X 位置（0 = 居中，正/负表示偏移） + - `y` (int): Y 位置（0 = 居中，正/负表示偏移） + - `backColor` (str): ARGB 十六进制背景色（默认：'7f7f7f7f'） + - `textColor` (str): ARGB 十六进制文本色（默认：'ff000000'） + - `textSize` (int): 文本大小（默认：10） + - `textAlign` (int): 文本对齐（0 = 继承） + - `script` (str): 长按关闭后运行的脚本路径 + - `arg`: 脚本参数 + - `clickRemove` (bool): 启用点击移除（默认：True） + - `flag` (int): 窗口标志（默认：40 - 可触摸） + +**返回：** 当前链列表长度 + +### floatViewCount() +获取活动浮动视图的数量。 + +```python +floatViewCount() +``` + +**返回：** 浮动视图数量 + +### floatViewResult() +获取浮动视图的结果/状态。 + +```python +floatViewResult(index=-1) +``` + +**参数：** +- `index` (int): 浮动视图索引（默认：-1，返回最后操作结果） + +**返回：** 包含操作详情的字典，包括： + - `x`, `y`: 位置 + - `time`: 时间戳 + - `operation`: 操作类型（'initial'、'move' 等） + - `index`: 视图索引 + - `removed`: 如果视图被移除则为 True + +### floatViewRemove() +移除浮动视图。 + +```python +floatViewRemove(index=-1) +``` + +**参数：** +- `index` (int): 要移除的视图索引（默认：-1 移除最后一个） + +**返回：** 如果成功则为 1，否则为 0 + +## 常量 + +- `floatView.INDEX_NEW = -1` - 创建新的浮动视图 +- `floatView.FLAG_DEFAULT_TOUCHABLE = 40` - 默认可触摸标志 +- `floatView.TEXT_ALIGNMENT_INHERIT = 0` +- `floatView.TEXT_ALIGNMENT_CENTER` - 居中文本对齐 + +## 使用示例 + +### 基本浮动视图 + +```python +import androidhelper +from androidhelper import Android + +droid = androidhelper.Android() + +# 创建简单浮动视图 +droid.floatView({ + 'index': -1, # 创建新的 + 'text': 'Hello World', + 'width': 400, + 'height': 300, + 'x': -300, # 从中心偏移 + 'y': -400, + 'backColor': 'ff0000', # 红色背景 + 'textColor': '0000ff', # 蓝色文本 + 'textSize': 16, + 'textAlign': droid.floatView.TEXT_ALIGNMENT_CENTER +}) + +# 检查数量 +print(f"Float views: {droid.floatViewCount().result}") + +# 获取结果 +result = droid.floatViewResult().result +print(f"View info: {result}") + +# 移除浮动视图 +droid.floatViewRemove(0) +``` + +### HTML 内容 + +```python +# 创建带 HTML 内容的浮动视图 +droid.floatView({ + 'text': '', # 空文本以使用 HTML + 'html': '

Title

Rich HTML content

', + 'width': 500, + 'height': 400 +}) +``` + +### 修改现有视图 + +```python +# 创建初始视图 +droid.floatView({'text': 'Initial Text', 'width': 300, 'height': 150}) + +# 修改同一视图（索引 0） +droid.floatView({ + 'index': 0, + 'text': 'Updated Text!', + 'backColor': '7f00ff00' # 绿色背景 +}) + +# 检查移动/更改结果 +result = droid.floatViewResult(0).result +print(f"Operation: {result.get('operation')}, Position: ({result.get('x')}, {result.get('y')})") +``` + +### 多个浮动视图 + +```python +# 创建多个视图 +for i in range(3): + droid.floatView({ + 'index': -1, + 'text': f'View {i}', + 'x': i * 100 - 150, + 'y': i * 100 - 150, + 'backColor': f'{i}f{i}f{i}f' + }) + +print(f"Total views: {droid.floatViewCount().result}") + +# 移除所有视图 +while droid.floatViewCount().result > 0: + droid.floatViewRemove() +``` + +### 带脚本回调 + +```python +# 创建关闭时运行脚本的浮动视图 +droid.floatView({ + 'text': 'Click to close and run script', + 'script': '/sdcard/my_script.py', + 'arg': 'hello from float view', + 'clickRemove': True +}) +``` diff --git a/source/zh/qsl4a/ui/fullscreen.md b/source/zh/qsl4a/ui/fullscreen.md new file mode 100644 index 0000000..9a52f1a --- /dev/null +++ b/source/zh/qsl4a/ui/fullscreen.md @@ -0,0 +1,171 @@ +# 全屏 UI + +使用原生 Android 布局创建自定义全屏界面。 + +## 布局方法 + +### fullShow() +显示全屏布局。 + +```python +fullShow(layout, title=None, theme=None) +``` + +**参数：** +- `layout` (str): JSON 布局定义或布局字符串 +- `title` (str, optional): 窗口标题 +- `theme` (str, optional): 主题名称 + +**返回：** 窗口 ID + +### fullDismiss() +关闭全屏窗口。 + +```python +fullDismiss() +``` + +### fullQuery() +查询所有小部件值。 + +```python +fullQuery() +``` + +**返回：** 小部件 ID 和值的字典 + +### fullQueryDetail() +查询特定小部件详情。 + +```python +fullQueryDetail(id) +``` + +## 属性方法 + +### fullGetProperty() +获取小部件属性。 + +```python +fullGetProperty(id, property) +``` + +### fullSetProperty() +设置小部件属性。 + +```python +fullSetProperty(id, property, value) +``` + +### fullSetList() +设置列表小部件项目。 + +```python +fullSetList(id, list, isHtml=False, listType=0) +``` + +### fullSetList2() +使用资源 ID 设置列表小部件项目。 + +```python +fullSetList2(id, list, intRes) +``` + +**参数：** +- `id` (str): 小部件 ID +- `list` (list): 项目列表 +- `intRes` (int): 列表项目布局的 Android 资源 ID + +### fullSetListSelected() +在列表中设置选中项目。 + +```python +fullSetListSelected(id, selected) +``` + +**参数：** +- `id` (str): 列表小部件 ID +- `selected` (int): 要选中的项目索引 + +### fullGetListSelected() +获取当前选中的列表项目索引。 + +```python +fullGetListSelected(id) +``` + +**参数：** +- `id` (str): 列表小部件 ID + +**返回：** 选中项目索引 + +## 批量属性操作 + +### fullGetProperties() +一次获取多个小部件的属性。 + +```python +fullGetProperties(ids, property) +``` + +**参数：** +- `ids` (list): 小部件 ID 列表 +- `property` (str): 要获取的属性名 + +**返回：** 映射小部件 ID 到属性值的字典 + +### fullSetProperties() +一次设置多个小部件的属性。 + +```python +fullSetProperties(ids, property, value) +``` + +**参数：** +- `ids` (list): 小部件 ID 列表 +- `property` (str): 要设置的属性名 +- `value`: 属性值 + +## 截图 + +### fullGetScreenShot() +捕获全屏截图。 + +```python +fullGetScreenShot(path=None) +``` + +**参数：** +- `path` (str, optional): 保存路径。如果为 None，则在事件中返回 + +**返回：** 包含截图数据的事件 + +## 使用示例 + +```python +import androidhelper + +droid = androidhelper.Android() + +# 定义布局 +layout = ''' +{ "type": "LinearLayout", "orientation": "vertical", + "children": [ + { "type": "TextView", "id": "title", "text": "Hello" }, + { "type": "Button", "id": "btn", "text": "Click Me" } + ] +} +''' + +# 显示布局 +droid.fullShow(layout, "My App") + +# 查询按钮点击 +event = droid.eventWaitFor('click', timeout=10) +if event.result: + widget_id = event.result['data']['id'] + if widget_id == 'btn': + print("Button clicked!") + +droid.fullDismiss() +``` diff --git a/source/zh/static/.DS_Store b/source/zh/static/.DS_Store deleted file mode 100644 index b063954..0000000 Binary files a/source/zh/static/.DS_Store and /dev/null differ diff --git a/source/zh/static/aipyapp_demo.jpg b/source/zh/static/aipyapp_demo.jpg new file mode 100644 index 0000000..00cb283 Binary files /dev/null and b/source/zh/static/aipyapp_demo.jpg differ diff --git a/source/zh/static/mov_hellolorld.mp4 b/source/zh/static/mov_hellolorld.mp4 new file mode 100644 index 0000000..55b285c Binary files /dev/null and b/source/zh/static/mov_hellolorld.mp4 differ diff --git a/source/zh/static/qpy_dashboard.jpg b/source/zh/static/qpy_dashboard.jpg new file mode 100644 index 0000000..201a84c Binary files /dev/null and b/source/zh/static/qpy_dashboard.jpg differ diff --git a/source/zh/static/qpy_editor.jpg b/source/zh/static/qpy_editor.jpg new file mode 100644 index 0000000..d00ed29 Binary files /dev/null and b/source/zh/static/qpy_editor.jpg differ diff --git a/source/zh/static/qpy_helloworld.jpg b/source/zh/static/qpy_helloworld.jpg new file mode 100644 index 0000000..6ac3785 Binary files /dev/null and b/source/zh/static/qpy_helloworld.jpg differ diff --git a/source/zh/static/qpy_wechat.jpg b/source/zh/static/qpy_wechat.jpg new file mode 100644 index 0000000..8e1a723 Binary files /dev/null and b/source/zh/static/qpy_wechat.jpg differ diff --git a/source/zh/static/qpy_wechat.png b/source/zh/static/qpy_wechat.png new file mode 100644 index 0000000..2a492ea Binary files /dev/null and b/source/zh/static/qpy_wechat.png differ diff --git a/source/zh/static/qpython_graphical_interace_demo.jpg b/source/zh/static/qpython_graphical_interace_demo.jpg new file mode 100644 index 0000000..c2cc0c9 Binary files /dev/null and b/source/zh/static/qpython_graphical_interace_demo.jpg differ diff --git a/source/zh/static/terminal_demo.jpg b/source/zh/static/terminal_demo.jpg new file mode 100644 index 0000000..4829b79 Binary files /dev/null and b/source/zh/static/terminal_demo.jpg differ diff --git a/source/zh/tutorial-hello-world.md b/source/zh/tutorial-hello-world.md new file mode 100644 index 0000000..17de91d --- /dev/null +++ b/source/zh/tutorial-hello-world.md @@ -0,0 +1,119 @@ +# 编写"Hello World" + +## Hello world + +![hello world](static/qpy_helloworld.jpg) + +好的，在您对 QPython 有了一定的了解之后，让我们在 QPython 中创建我们的第一个程序。显然，它将是 `helloworld.py`。;) + +启动 QPython，打开编辑器并输入以下代码： + +```python +#qpy:quiet +import androidhelper + +droid = androidhelper.Android() +droid.makeToast('Hello, QPYTHON!') +``` + +毫无疑问，它与其他任何 hello-world 程序并无不同。执行时，它只是在屏幕上显示弹出消息（见顶部截图）。无论如何，这是一个很好的 QPython 程序示例。 + +## 代码理解 + +它以 *import androidhelper* 开头——这是 QPython 中最有用的模块，它封装了 Python 中可用的几乎所有与 Android 的接口。任何在 QPython 中开发的脚本都以这个语句开头（至少如果它声称要与用户通信的话）。在此处阅读更多关于 [Python 库](https://docs.python.org/3.12/library/index.html) 和 [import 语句](https://docs.python.org/3.12/reference/simple_stmts.html#import) 的内容。 + + +接下来我们创建一个 `droid` 对象（实际上是一个类），它对于调用 RPC 函数以与 Android 通信是必要的。 + +我们代码的最后一行调用了这样的函数，`droid.makeToast()`，它在屏幕上显示一个小的弹出消息（"toast"）。 + +好的，让我们添加一些更多的功能。让它询问用户名并向用户打招呼。 + +## 更多示例 + +我们可以使用 `dialogGetInput` 调用显示一个带有标题、提示、编辑字段和 **确定** 和 **取消** 按钮的简单对话框。用以下代码替换您的最后一行代码并将其保存为 `hello1.py`： + +```python +#qpy:quiet +import androidhelper + +droid = androidhelper.Android() +respond = droid.dialogGetInput("Hello", "What is your name?") +``` + +好的，我认为它应该返回任何响应，任何用户反应。这就是为什么我写 `respond = ...`。但这个调用实际上返回什么？让我们检查一下。只需在最后一行后添加 print 语句： + +```python +#qpy:quiet +import androidhelper + +droid = androidhelper.Android() +respond = droid.dialogGetInput("Hello", "What is your name?") +print(respond) +``` + +然后保存并运行它... + +哎呀！没有打印？别担心。只需拉下通知栏，您就会看到"QPython Program Output: hello1.py"——点击它！ + +如您所见，`droid.dialogGetInput()` 返回一个包含三个字段的 JSON 对象。我们只需要一个——`result`，其中包含用户实际输入的内容。 + +让我们添加脚本的反应： + +```python +#qpy:quiet +import androidhelper + +droid = androidhelper.Android() +respond = droid.dialogGetInput("Hello", "What is your name?") +print(respond) +message = f'Hello, {respond.result}!' +droid.makeToast(message) +``` + +最后两行（1）格式化消息，（2）以 toast 形式向用户显示消息。如果您仍然不知道 f-string 是什么意思，请参阅 [Python 文档](https://docs.python.org/3.12/tutorial/inputoutput.html#fancier-output-formatting)。 + +哇！它工作了！;) + +现在我要在那里添加一些逻辑。想一想：如果用户点击 **取消** 按钮，或者点击 **确定** 但将输入字段留空，会发生什么？ + +您可以玩这个程序，检查 `respond` 变量在每种情况下包含什么。 + +首先，我想将用户输入的文本放入一个单独的变量中：`name = respond.result`。然后我检查它，如果它包含任何真实文本，它将被视为名称并用于问候。否则，将显示另一条消息。将第五行 `message = f'Hello, {respond.result}!'` 替换为以下代码： + +```python +name = respond.result +if name: + message = f'Hello, {name}!' +else: + message = "Hey! And you're not very polite, %Username%!" +``` + +使用工具栏上的 **<** 和 **>** 按钮来缩进/取消缩进 if 语句中的行（或者只需使用空格/退格键）。您可以在 [此处](https://docs.python.org/3.12/tutorial/introduction.html#first-steps-towards-programming) 阅读更多关于 Python 缩进的内容；if 语句在 [此处](https://docs.python.org/3.12/tutorial/controlflow.html#if-statements) 描述。 + +首先，我们将用户输入放入 `name` 变量。然后我们检查 `name` 是否包含任何内容？如果用户留空行并点击 **确定**，返回值是空字符串 `''`。如果按下了 **取消** 按钮，返回值是 `None`。在 if 语句中，两者都被视为假。因此，只有当 `name` 包含任何有意义的内容时，then 语句才会执行，并显示问候语"Hello, ...!"。如果输入为空，用户将看到"Hey! And you're not very polite, %Username%!"消息。 + +好的，这是整个程序： + +```python +#qpy:quiet +import androidhelper + +droid = androidhelper.Android() +respond = droid.dialogGetInput("Hello", "What is your name?") +print(respond) +name = respond.result +if name: + message = f'Hello, {name}!' +else: + message = "Hey! And you're not very polite, %Username%!" +droid.makeToast(message) +``` + +## 运行效果 + + + +## 下一步 + +对于 Python 新用户，推荐学习 [Python 语法实践](https://www.qpython.com.cn/courses/python-basic-syntax/) 课程来进一步学习 Python，或者在 [QPython 精选课程](https://www.qpython.com.cn/courses/) 中寻找想要学习的内容。 \ No newline at end of file diff --git a/source/zh/whats-new.md b/source/zh/whats-new.md new file mode 100644 index 0000000..6c14bf3 --- /dev/null +++ b/source/zh/whats-new.md @@ -0,0 +1,119 @@ +# 更新日志 + +## v3.9.2 / v3.9.3 + +- SDK 升级，支持 16 KB 页面大小，提供更流畅的运行环境 +- 编辑器重大更新，带来更流畅的编辑体验 +- 其他各种小改进 + +## v3.9.1 + +- SDK 升级，支持 16 KB 页面大小，提供更流畅的运行环境 +- 扩展包现在支持 MCP +- 错误修复 + +## v3.9.0 + +- SDK 升级，整合最新的 Android 功能 +- 内置 Ollama 0.9.5 升级：现在支持在 QPython 中本地运行 Gemma3n 模型，体验更强大的端侧 AI 计算能力 +- Pygame 游戏开发支持：结合 XServer，您现在可以轻松地在 QPython 上编写和运行 Pygame 游戏，释放您的创造力！ +- 个性化图标自定义：通过 QPython 设置自定义桌面图标和主题，创建独特的编程环境 + +## v3.8.11 + +- 内置 Ollama 0.9.5 升级：现在支持在 QPython 中本地运行 Gemma3n 模型，体验更强大的端侧 AI 计算能力 +- Pygame 游戏开发支持：结合 XServer，您现在可以轻松地在 QPython 上编写和运行 Pygame 游戏，释放您的创造力！ +- 个性化图标自定义：通过 QPython 设置自定义桌面图标和主题，创建独特的编程环境 + +## v3.8.10 + +- 内置 Ollama 升级：现在您可以在 QPython 中轻松本地运行 Qwen3 / Gemma3 模型！ +- 添加了强大的 MCP 库：在 Extensions -> AIPY 中添加了 mcp 库，让您随时随地携带强大的 MCP 功能！ + +## v3.8.9 + +重大更新！AI 编程完全集成到 QPython，让您的编程更轻松！ + +- 自然语言编程支持：新支持 AIPyApp，在 QPython 中实现自然语言编程。目前处于测试阶段 - 加入我们的社区获取使用说明 +- 新 QSL4A 功能：添加 notebookOpen 函数，支持自然语言控制打开 Notebook 文件 +- 内置编辑器升级：增强编辑器功能，支持打开和浏览各种文本文件 +- 便捷的文件管理：在文件管理器中添加内部存储入口，快速访问您的文件 + +## v3.8.8 + +- 文件访问权限控制的重要改进，允许用户灵活地通过 QPython 编程启用或禁用外部存储文件的访问 +- SDK 升级，增强了对新版 Android 的支持和兼容性 +- 在 Extensions -> AIPY 中添加了 Anthropic 和 Google GenAI 库 + +## v3.8.7 + +- 在现有 Tkinter 支持基础上，在 Extensions -> Tools 中添加了使用 Turtle 绘制哆啦A梦的示例代码 +- 优化了手机权限获取流程，提升用户体验和操作便利性 +- 在 Extensions -> AIPY 中添加了 Google Gen AI 库，方便访问 Gemini Developer API 和 Vertex AI + +## v3.8.6 + +- Tkinter 支持：现在支持 Tkinter 库，可通过 XServer 访问。请访问 www.qpython.org 的云盘"Extra"链接下载所需文件 +- 存储权限更新：为改善用户体验，我们添加了读取手机存储的权限，用于访问存储在其他目录中的 Python 程序 + +此更新后，QPython 和 QPythonPlus（不在应用商店上架，专为需要更多敏感权限的高级用户设计）将保持同步的版本号。 + +## v3.5.2 (2025/2/25) + +与开源 LLM 部署工具 Ollama 以及 DeepSeek 开发的 DeepSeek 实现无缝集成！ + +**功能：** +- 零门槛在移动设备上本地运行各种大型语言模型 +- 快速部署 DeepSeek 等尖端 AI 模型 +- 享受简约的 API 调用体验 +- 构建完全离线的智能编程环境 + +**能力：** +- 直接在手机上加载/管理 LLM 模型 +- 基于本地计算的实时低延迟响应 + +## v3.5.0 + +- Python 升级到 3.12.8 +- 改进仪表盘，功能更清晰、更人性化 +- 添加了众多第三方包：PyTorch / Twisted / Scrapy / FastAPI ... + +## v3.3.8 + +- 修复了 NumPy 兼容性问题 + +## v3.3.5 + +- 升级 Python 内核到 3.11.9 +- 修复了扩展中不显示模块安装状态的 bug +- 修复了扩展中删除模块失败的 bug +- 修复了其他 bug + +## v3.3.4 + +- 添加了 OpenAI/Langchain/APIGPTCloud AI 包 +- 移除不必要的文件以减少大小 + +## v3.2.5 + +- 添加了一些 SL4A 函数 +- 其他错误修复 + +## v3.2.3 + +- 更新 Python 版本到 3.11.0 +- 更新 IPython 版本到 8.6.0 +- 更新 pip 版本到 22.3.1 +- 更新科学计算包，自动软链接 +- 减少空间使用 +- 添加了一些 SL4A 函数 + 其他错误修复 + +## v3.1.8 + +- 在终端中添加了操作热键 +- 修复了编辑器在旋转时丢失内容的问题 +- 修复了其他 bug + +--- + +[在 Google Play 下载](https://play.google.com/store/apps/details?id=org.qpython.qpy)