@c This is part of the Emacs manual.
@c Copyright (C) 2021 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Haiku
@appendix Emacs and Haiku
@cindex Haiku

  Haiku is a Unix-like operating system that originated as a
re-implementation of the operating system BeOS.  As it is free
software, this port of GNU Emacs is provided for the convenience of
its users.

  This section describes the peculiarities of using Emacs built with
the Application Kit, the windowing system native to Haiku.  The
oddities described here do not apply to using Emacs on Haiku built
without windowing support, or built with X11.

@menu
* Haiku Basics::        Basic Emacs usage and installation under Haiku.
* Haiku Customization:: Customizations specific to Haiku.
* Haiku Events::        Specifics of window system event handling under Haiku.
* Haiku Resources::     The facsimile of an X resource database used on Haiku.
* Haiku Fonts::         The various options for displaying fonts on Haiku.
@end menu

@node Haiku Basics
@section Installation and usage peculiarities under Haiku
@cindex haiku application
@cindex haiku installation

  Emacs installs two separate executables under Haiku; it is up to the
user to decide which one suits him best: A regular executable, with
the lowercase name @code{emacs}, and a binary containing
Haiku-specific application metadata, with the name @code{Emacs}.

@cindex launching Emacs from the tracker
@cindex TTY Emacs in haiku
  If you are launching Emacs from the Tracker, or want to make the
Tracker open files using Emacs, you should use the binary named
@code{Emacs}; If you are going to use Emacs in the terminal, or wish
to launch separate instances of Emacs, or do not care for the
aforementioned system integration features, the binary named
@code{emacs} should be used instead.

@cindex modifier keys and system keymap (Haiku)
@cindex haiku keymap
  On Haiku, unusual modifier keys such as the Hyper key are
unsupported.  By default, the super key corresponds with the option
key defined by the operating system, the meta key with the command
key, the control key with the system control key, and the shift key
with the system shift key.  On a standard PC keyboard, Haiku should
map these keys to positions familiar to those using a GNU system, but
this may require some adjustment to your system's configuration to
work.

  If the system shift key is held down, Emacs will always use the
system shift keymap regardless of what other modifier keys are
currently held down.  Otherwise, if any other modifier key is held
down, the default system keymap will be used to map keys.  This makes
it impossible to type accented characters using the system super key
map.

  You can customize the correspondence between modifier keys known to
the system, and those known to Emacs.  See @ref{Haiku Customization}.

@cindex haiku input methods
@cindex BeCJK and Emacs
  Some popular Haiku input methods such BeCJK are known to behave
badly when interacting with Emacs.  If you are affected, you can use
an Emacs input method instead.  See @ref{Input Methods}.

@cindex tooltips (haiku)
@cindex haiku tooltips
  On Haiku, Emacs defaults to using the system tooltip mechanism.
This usually leads to more responsive tooltips, but the tooltips will
not be able to use advanced display features.  If that is what you
need, you can disable the use of system tooltips by setting the
variable @code{haiku-use-system-tooltips} to nil. (@pxref{Tooltips,,,
elisp, The Emacs Lisp Reference Manual}).

@subsection What to do when Emacs crashes
@cindex haiku debugger
@vindex haiku-debug-on-fatal-error
  If the variable @code{haiku-debug-on-fatal-error} is non-nil, Emacs
will launch the system debugger when a fatal signal is received.  It
defaults to @code{t}.  If GDB cannot be used on your system, please
attach the report generated by the system debugger when reporting a
bug.

@node Haiku Customization
@section Customizations specific to Haiku
  This section details several customizations that are specific to
Haiku windowing.

@table @code
@vindex haiku-use-system-tooltips
@item haiku-use-system-tooltips
This variable controls whether or not system tooltips will be used.

When non-nil, tooltips are displayed by the Application Kit and not
Emacs, and accordingly do not have a tooltip frame.  As such, they are
also unable to utilize any display properties.

@vindex haiku-use-system-debugger
@item haiku-use-system-debugger
When non-nil, Emacs will ask the system to launch the system debugger
whenever it experiences a fatal error.  This behaviour is standard
among Haiku applications.
@end table

@subsection Modifier keys
@cindex modifier key customization (Haiku)
You can customize which Emacs modifiers the various system modifier
keys correspond to through the following variables:

@table @code
@vindex haiku-meta-keysym
@item haiku-meta-keysym
The system modifier key that will be treated as the Meta key by Emacs.
It defaults to @code{command}.

@vindex haiku-control-keysym
@item haiku-control-keysym
The system modifier key that will be treated as the Control key by
Emacs.  It defaults to @code{control}.

@vindex haiku-super-keysym
@item haiku-super-keysym
The system modifier key that will be treated as the Super key by
Emacs.  It defaults to @code{option}.

@vindex haiku-shift-keysym
@item haiku-super-keysym
The system modifier key that will be treated as the Shift key by
Emacs.  It defaults to @code{shift}.
@end table

The value of each variable can one of the symbols @code{command},
@code{control}, @code{option}, @code{shift}, or @code{nil}.
@code{nil} or any other value will cause the default value to be used
instead.

@node Haiku Events
@section Window system events under Haiku
@cindex events on Haiku

  On Haiku, Emacs can receive events that have no equivalent under the
X window system.  These are sent as specially defined key events,
which do not correspond to any sequence of keystrokes.  Under Emacs,
these key events can be bound to functions just like ordinary
keystrokes.  Here is a list of these events.

@table @key
@item haiku-refs-found
This event is received whenever the operating system tells Emacs to
open a file, such as when a file's icon is dropped onto the
@code{Emacs} binary in the Tracker, or when a file is dropped onto a
frame.  The event itself is a list, the second item of which is a
string containing the path of the file to be opened.

For an explanation of the purpose of the @code{Emacs} binary, see
@ref{Haiku Basics}.

@item haiku-quit-requested
This event is received whenever the operating system tells Emacs that
the user has asked Emacs to quit, optionally seeking confirmation if
the user has any unsaved documents. By default, it is bound to
@code{save-buffers-kill-emacs}, see @ref{Exiting}.
@end table

@node Haiku Resources
@section Using the X defaults database on Haiku
@cindex X resources, haiku
@cindex x-get-resource, haiku

  As there is no equivalent to an X resource database on Haiku, a
facsimile is provided in its place.  This facsimile does not attempt
to process X resource files, but is responsive to the @kbd{--xrm}
command-line argument.  For details about using this argument, see
@ref{Resources}.

@node Haiku Fonts
@section Font and font backend selection on Haiku
@cindex font backend selection (Haiku)

  Emacs, when built with Haiku windowing support, can be built with
several different font backends.  You can specify font backends by
specifying @kbd{-xrm Emacs.fontBackend:BACKEND} on the command line
used to invoke Emacs, where @kbd{BACKEND} is one of the backends
specified below, or on a per-frame basis by changing the
@code{font-backend} frame parameter. (@pxref{Parameter Access,,,
elisp, The Emacs Lisp Reference Manual}).

@cindex ftcr font backend

  The @code{ftcr} font backend is available whenever Emacs is built
with Cairo support.  It is the most fully featured, but will cause
display issues when used on a frame with double-buffering disabled.

@cindex haiku font backend
@cindex fonts (Haiku)

  The @code{haiku} font backend is always available.  At present, it
is incapable of displaying color emoji and advanced compositions
(though this may change if Haiku gains support for both at some later
time, independent of Emacs).

  This font backend has a known problem with displaying certain bold
or italic fonts on older Haiku systems.  It is documented in
@file{etc/PROBLEMS}, see @ref{Known Problems}.

@cindex HarfBuzz support (Haiku)

  The @code{ftcr} backend features HarfBuzz variants when Emacs is
built with HarfBuzz support.  The HarfBuzz variant is named
@code{ftcrhb}.