mirror of
git://git.sv.gnu.org/emacs.git
synced 2025-12-15 10:30:25 -08:00
ad59d8986a
* doc/emacs/android.texi (Android, Android Environment): Improve
documentation.
* doc/lispref/commands.texi (Touchscreen Events): Document
changes to touchscreen support.
* doc/lispref/display.texi (Defining Faces, Window Systems):
* doc/lispref/frames.texi (Frame Layout, Font and Color
Parameters):
* doc/lispref/os.texi (System Environment): Document Android in
various places.
* java/org/gnu/emacs/EmacsWindow.java (figureChange): Fix crash.
* lisp/loadup.el: ("touch-screen"): Load touch-screen.el.
* lisp/pixel-scroll.el: Autoload two functions.
* lisp/term/android-win.el: Add require 'touch-screen.
* lisp/touch-screen.el (touch-screen-current-tool)
(touch-screen-current-timer, touch-screen-delay)
(touch-screen-relative-xy, touch-screen-handle-scroll)
(touch-screen-handle-timeout, touch-screen-handle-point-update)
(touch-screen-handle-point-up, touch-screen-handle-touch)
(global-map, touch-screen): New file.
* src/android.c (android_run_debug_thread): Fix build on 64 bit
systems.
(JNICALL, android_put_pixel): Likewise.
(android_transform_coordinates, android_four_corners_bilinear)
(android_fetch_pixel_bilinear, android_project_image_bilinear)
(android_fetch_pixel_nearest_24, android_fetch_pixel_nearest_1)
(android_project_image_nearest): New functions.
* src/androidgui.h (struct android_transform): New structure.
* src/androidterm.c (android_note_mouse_movement): Remove
obsolete TODO.
(android_get_scale_factor): New function.
(android_draw_underwave): Scale underwave correctly.
* src/dispextern.h: Support native image transforms on Android.
* src/image.c (matrix_identity, matrix_rotate)
(matrix_mirror_horizontal, matrix_translate): New functions.
(image_set_transform): Implement native image transforms on
Android.
(Fimage_transforms_p): Implement on Android.
* src/keyboard.c (make_lispy_event, syms_of_keyboard): Handle
touch screen- menu bar events.
* src/sfnt.c: Fix typo in comment.
* src/sfntfont-android.c (sfntfont_android_blend, U255TO256)
(sfntfont_android_put_glyphs): Avoid redundant swizzling.
* src/sfntfont.c (sfntfont_lookup_char): Fix build on 64 bit
systems.
349 lines
13 KiB
Text
349 lines
13 KiB
Text
@c This is part of the Emacs manual.
|
|
@c Copyright (C) 2021--2023 Free Software Foundation, Inc.
|
|
@c See file emacs.texi for copying conditions.
|
|
@node Android
|
|
@appendix Emacs and Android
|
|
@cindex Android
|
|
|
|
Android is a mobile operating system developed by the Open Handset
|
|
Alliance. This section describes the peculiarities of using Emacs on
|
|
an Android device running Android 2.2 or later.
|
|
|
|
@menu
|
|
* What is Android?:: Preamble.
|
|
* Android Startup:: Starting up Emacs on Android.
|
|
* Android File System:: The Android file system.
|
|
* Android Environment:: Running Emacs under Android.
|
|
* Android Fonts:: Font selection under Android.
|
|
@end menu
|
|
|
|
@node What is Android?
|
|
@section Android history
|
|
|
|
Android is an operating system for mobile devices developed by the
|
|
Open Handset Alliance, a group of companies interested in developing
|
|
handsets that can run a common set of software. It is supposedly free
|
|
software.
|
|
|
|
Like the X Consortium of times past, the Open Handset Alliance
|
|
believes that ``openness'' (namely, the regular release of the Android
|
|
source code) is simply a tool to increase the popularity of the
|
|
Android platform. Computer companies normally produce proprietary
|
|
software. The companies in the Open Handset Alliance are no different
|
|
-- most versions of Android installed on devices are proprietary, by
|
|
virtue of containing proprietary components, that often cannot even be
|
|
replaced by the user.
|
|
|
|
Android is not designed to respect users' freedom. Almost all
|
|
versions of Android (including some which are supposedly free
|
|
software) include support for Digital Restrictions Management,
|
|
technology that is designed to limit users' ability to copy media to
|
|
and from their own devices. Most Android devices also come with
|
|
proprietary Google applications which are required to run the system,
|
|
and many other Android applications.
|
|
|
|
Thus, it must be necessary to consider Android proprietary software
|
|
from a practical standpoint. That is an injustice. If you use
|
|
Android, we urge you to switch to a free operating system, if only for
|
|
your freedom's sake.
|
|
|
|
We support GNU Emacs on proprietary operating systems because we
|
|
hope this taste of freedom will inspire users to escape from them.
|
|
|
|
@node Android Startup
|
|
@section Starting up Emacs on Android
|
|
|
|
Emacs is not installed on Android devices from source code, or by a
|
|
package manager. Instead, Emacs is compiled for Android on a
|
|
different operating system, with the resulting binaries packaged into
|
|
an archive, that is then transferred to the device and unpacked.
|
|
|
|
After being unpacked, Emacs instructs the system to display an
|
|
application icon on the desktop. Emacs then starts up once the
|
|
application icon is clicked.
|
|
|
|
@cindex ``adb logcat''
|
|
|
|
During startup, Emacs will display messages in the system log buffer;
|
|
reading that buffer requires the Android Debug Bridge (@code{adb})
|
|
utility to be installed on another computer; it cannot be read on the
|
|
computer running Android itself.
|
|
|
|
After enabling the ``USB Debugging'' feature on the Android system,
|
|
and connecting it via USB to another system with the @code{adb}
|
|
utility installed, the log can be viewed by running the following
|
|
command on that other system:
|
|
|
|
@example
|
|
$ adb logcat | grep -E "(android_run_debug_thread|[Ee]macs)"
|
|
@end example
|
|
|
|
@node Android File System
|
|
@section What files Emacs can access under Android
|
|
@cindex /assets directory, android
|
|
|
|
Emacs exposes a special directory on Android systems: the name of
|
|
the directory is @file{/assets}, and it contains the @file{etc},
|
|
@file{lisp} and @file{info} directories which are normally installed
|
|
in @file{/usr/share/emacs} directory on GNU and Unix systems.
|
|
|
|
@cindex limitations of the /assets directory
|
|
|
|
This directory exists because Android does not extract the contents of
|
|
application packages on to the file system while unpacking them, but
|
|
instead requires programs like Emacs to access its contents using a
|
|
special ``asset manager'' interface. Here are the peculiarities that
|
|
result from such an implementation:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Subprocesses (such as @command{ls}) can not run from the
|
|
@file{/assets} directory, so Dired, and functions such as
|
|
@code{list-directory} do not work.
|
|
|
|
@item
|
|
There are no @file{.} and @file{..} directories inside the
|
|
@file{/assets} directory.
|
|
|
|
@item
|
|
Files in the @file{/assets} directory are always read only, and have
|
|
to be completely read in to memory each time they are opened.
|
|
|
|
@item
|
|
@code{directory-files} does not return a useful value on the
|
|
@file{/assets} directory itself, and does not return subdirectories
|
|
inside subdirectories of the @file{/assets} directory.
|
|
@end itemize
|
|
|
|
Aside from the @file{/assets} directory, Android programs normally
|
|
have access to three other directories. They are:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The @dfn{app data} directory. This also serves as the home directory
|
|
for Emacs, and is always accessible read-write.
|
|
|
|
@item
|
|
The @dfn{app library} directory. This is automatically appended to
|
|
@code{exec-path} upon startup.
|
|
|
|
@item
|
|
The @dfn{external storage} directory. This is accessible to Emacs
|
|
when the user grants the @code{Files and media} permission to Emacs
|
|
via system settings.
|
|
@end itemize
|
|
|
|
The external storage directory is found at @file{/sdcard}; the other
|
|
directories are not found at any fixed location.
|
|
|
|
@node Android Environment
|
|
@section Running Emacs under Android
|
|
|
|
From the perspective of users, Android is mostly a single user
|
|
operating system; however, from the perspective of applications and
|
|
Emacs, the system has an overwhelming number of users!
|
|
|
|
Each application runs in its own user, with his own home directory,
|
|
which is the app data directory (@pxref{Android File System}.)
|
|
|
|
Each application is also prohibited from accessing system
|
|
directories, and the app data directories of other applications. In
|
|
recent versions of Android, the system also prohibits, for security
|
|
reasons, even Emacs itself from running executables inside the app
|
|
data directory!
|
|
|
|
Emacs comes with several binaries. While being executable files,
|
|
they are packaged as libraries in the library directory, because
|
|
otherwise the system will not unpack them while Emacs is being
|
|
installed. This means, instead of specifying @code{ctags} or
|
|
@code{emacsclient} in a subprocess, Lisp code must specify
|
|
@code{libctags.so} or @code{libemacsclient.so} on the commnd line
|
|
instead when starting either of those programs in a subprocess.
|
|
|
|
@c TODO: remove this limitation.
|
|
In addition, the @file{/assets} directory containing Emacs start-up
|
|
files is inaccessible to processes not directly created by
|
|
@code{zygote}, the system service responsible for starting
|
|
applications. This makes it impossible to run Emacs in a subprocess
|
|
within itself.
|
|
|
|
@section Running Emacs in the background
|
|
@cindex emacs killed, android
|
|
@cindex emacs in the background, android
|
|
|
|
Application processes are treated as disposable entities by the
|
|
system. When all Emacs frames move to the background, Emacs is liable
|
|
to be killed by the system at any time, for the purpose of saving
|
|
resources. There is currently no easy way to bypass these
|
|
restrictions, aside from keeping Emacs constantly running in the
|
|
foreground.
|
|
|
|
@section Android permissions
|
|
@cindex external storage, android
|
|
|
|
Android also defines a permissions system that determines what
|
|
system services Emacs is allowed to access. Programs must specify
|
|
what permissions they want; what then happens depends on the version
|
|
of Android being used:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
On Android 5.1 and earlier, Emacs automatically receives the following
|
|
permissions it has requested upon being installed:
|
|
|
|
@itemize @minus
|
|
@item
|
|
@code{android.permission.READ_CONTACTS}
|
|
@item
|
|
@code{android.permission.WRITE_CONTACTS}
|
|
@item
|
|
@code{android.permission.VIBRATE}
|
|
@item
|
|
@code{android.permission.ACCESS_COARSE_LOCATION}
|
|
@item
|
|
@code{android.permission.INTERNET}
|
|
@item
|
|
@code{android.permission.SET_WALLPAPER}
|
|
@item
|
|
@code{android.permission.WRITE_EXTERNAL_STORAGE}
|
|
@item
|
|
@code{android.permission.SEND_SMS}
|
|
@item
|
|
@code{android.permission.RECEIVE_SMS}
|
|
@item
|
|
@code{android.permission.RECEIVE_MMS}
|
|
@item
|
|
@code{android.permission.WRITE_SMS}
|
|
@item
|
|
@code{android.permission.READ_SMS}
|
|
@item
|
|
@code{android.permission.NFC}
|
|
@item
|
|
@code{android.permission.TRANSMIT_IR}
|
|
@item
|
|
@code{android.permission.READ_PHONE_STATE}
|
|
@item
|
|
@code{android.permission.WAKE_LOCK}
|
|
@item
|
|
@code{android.permission.FOREGROUND_SEVICE}
|
|
@item
|
|
@code{android.permission.REQUEST_INSTALL_PACKAGES}
|
|
@item
|
|
@code{android.permission.REQUEST_DELETE_PACKAGES}
|
|
@item
|
|
@code{android.permission.SYSTEM_ALERT_WINDOW}
|
|
@item
|
|
@code{android.permission.RECORD_AUDIO}
|
|
@item
|
|
@code{android.permission.CAMERA}
|
|
@end itemize
|
|
|
|
While most of these permissions are left unused by Emacs itself, they
|
|
are declared by Emacs as they could be useful for other programs; for
|
|
example, the permission to access contacts may be useful for EUDC.
|
|
|
|
@item
|
|
On Android 6.0 and later, Emacs only receives the following
|
|
permissions upon installation:
|
|
|
|
@itemize @minus
|
|
@item
|
|
@code{android.permission.VIBRATE}
|
|
@item
|
|
@code{android.permission.INTERNET}
|
|
@item
|
|
@code{android.permission.SET_WALLPAPER}
|
|
@item
|
|
@code{android.permission.NFC}
|
|
@item
|
|
@code{android.permission.TRANSMIT_IR}
|
|
@item
|
|
@code{android.permission.WAKE_LOCK}
|
|
@end itemize
|
|
|
|
Other permissions must be granted by the user through the system
|
|
settings application. Consult the manufacturer of your device for
|
|
more details, as how to do this varies by device.
|
|
@end itemize
|
|
|
|
@section Android windowing
|
|
|
|
Android has an unusual window system; there, all windows are
|
|
maximized or full-screen, and only one window can be displayed at a
|
|
time. On larger devices, the system allows up to four windows to be
|
|
tiled on the screen at any time.
|
|
|
|
Windows on Android do not continue to exist indefinitely after they
|
|
are created. Instead, the system may choose to terminate windows that
|
|
are not on screen in order to save memory, with the assumption that
|
|
the program will save its contents to disk and restore them later,
|
|
when the user asks to open it again. As this is obvious not possible
|
|
with Emacs, Emacs separates a frame from a system window.
|
|
|
|
Each system window created (including the initial window created
|
|
during Emacs startup) is appended to a list of windows that do not
|
|
have associated frames. When a frame is created, Emacs looks up any
|
|
window within that list, and displays the contents of the frame
|
|
within; if there is no window at all, then one is created. Likewise,
|
|
when a new window is created by the system, Emacs places the contents
|
|
of any frame that is not already displayed within a window inside.
|
|
When a frame is closed, the corresponding system window is also
|
|
closed.
|
|
|
|
This strategy works as long as one window is in the foreground.
|
|
Otherwise, Emacs can only run in the background for a limited amount
|
|
of time before the process is killed completely.
|
|
|
|
@cindex windowing limitations, android
|
|
@cindex frame parameters, android
|
|
Due to the unusual nature of the Android windowing environment, Emacs
|
|
only supports a limited subset of GUI features. Here is a list of
|
|
known limitations, and features which are not implemented:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The functions @code{raise-frame} and @code{lower-frame} are
|
|
non-functional, because of bugs in the window system.
|
|
|
|
@item
|
|
Scroll bars are not supported, as they are close to useless on Android
|
|
devices.
|
|
|
|
@item
|
|
The @code{alpha}, @code{alpha-background}, @code{z-group},
|
|
@code{override-redirect}, @code{mouse-color}, @code{cursor-color},
|
|
@code{cursor-type}, @code{title}, @code{wait-for-wm}, @code{sticky},
|
|
@code{undecorated} and @code{tool-bar-position} frame parameters
|
|
(@pxref{Frame Parameters,,, elisp, the Emacs Lisp Reference Manual})
|
|
are unsupported.
|
|
|
|
@item
|
|
The @code{fullscreen} frame parameter is always @code{maximized} for
|
|
top-level frames.
|
|
@end itemize
|
|
|
|
@node Android Fonts
|
|
@section Font backends and selection under Android
|
|
@cindex fonts, android
|
|
|
|
Emacs supports two font backends under Android: they are respectively
|
|
named @code{sfnt-android} and @code{android}.
|
|
|
|
Upon startup, Emacs enumerates all the TrueType format fonts in the
|
|
directory @file{/system/fonts}; this is where the Android system
|
|
places fonts. Emacs assumes there will always be a font named ``Droid
|
|
Sans Mono'', and then defaults to using this font. These fonts are
|
|
then rendered by the @code{sfnt-android} font driver.
|
|
|
|
When running on Android, Emacs currently lacks support for TrueType
|
|
Container and OpenType fonts. This means that only a subset of the
|
|
fonts installed on the system are currently available to Emacs. If
|
|
you are interested in raising this limitation, please contact
|
|
@email{emacs-devel@@gnu.org}.
|
|
|
|
If the @code{sfnt-android} font driver fails to find any fonts at all,
|
|
Emacs falls back to the @code{android} font driver. This is a very
|
|
lousy font driver, because of limitations and inaccuracies in the font
|
|
metrics provided by the Android platform. In that case, Emacs uses
|
|
the ``Monospace'' typeface configured on your system; this should
|
|
always be Droid Sans Mono.
|