frames.texi

@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Frames
@chapter フレーム
@cindex フレーム

@dfn{フレーム}（frame）とは、1つかそれ以上のEmacsのウィンドウ（@pxref{Windows}）を
収めているスクリーン上のオブジェクトです。
It is the kind of object called a
``window'' in the terminology of graphical environments; but we can't
call it a ``window'' here, because Emacs uses that word in a different
way.  In Emacs Lisp, a @dfn{frame object} is a Lisp object that
represents a frame on the screen.  @xref{Frame Type}.

フレームには最初は1つのウィンドウ（およびミニバッファ用ウィンドウ）が
ありますが、それを上下や左右に小さなウィンドウに分割できます。
@xref{Splitting Windows}.

@cindex terminal
  A @dfn{terminal} is a display device capable of displaying one or
more Emacs frames.  In Emacs Lisp, a @dfn{terminal object} is a Lisp
object that represents a terminal.  @xref{Terminal Type}.

@cindex text terminal
@cindex graphical terminal
@cindex graphical display
  There are two classes of terminals: @dfn{text terminals} and
@dfn{graphical terminals}.  Text terminals are non-graphics-capable
displays, including @command{xterm} and other terminal emulators.  On
a text terminal, each Emacs frame occupies the terminal's entire
screen; although you can create additional frames and switch between
them, the terminal only shows one frame at a time.  Graphical
terminals, on the other hand, are managed by graphical display systems
such as the X Window System, which allow Emacs to show multiple frames
simultaneously on the same display.

  On GNU and Unix systems, you can create additional frames on any
available terminal, within a single Emacs session, regardless of
whether Emacs was started on a text or graphical terminal.  Emacs can
display on both graphical and text terminals simultaneously.  This
comes in handy, for instance, when you connect to the same session
from several remote locations.  @xref{Multiple Terminals}.

@defun framep object
この述語関数は、@var{object}がフレームならば非@code{nil}値を返し、
さもなければ@code{nil}を返す。
For a frame, the value indicates which
kind of display the frame uses:

@table @code
@item t
The frame is displayed on a text terminal.
@item x
The frame is displayed on an X graphical terminal.
@item w32
The frame is displayed on a MS-Windows graphical terminal.
@item ns
The frame is displayed on a GNUstep or Macintosh Cocoa graphical
terminal.
@item pc
The frame is displayed on an MS-DOS terminal.
@end table
@end defun

@defun frame-terminal &optional frame
This function returns the terminal object that displays @var{frame}.
If @var{frame} is @code{nil} or unspecified, it defaults to the
selected frame.
@end defun

@defun terminal-live-p object
This predicate returns a non-@code{nil} value if @var{object} is a
terminal that is live (i.e., not deleted), and @code{nil} otherwise.
For live terminals, the return value indicates what kind of frames are
displayed on that terminal; the list of possible values is the same as
for @code{framep} above.
@end defun

@menu
* Creating Frames::             Creating additional frames.
* Multiple Terminals::          Displaying on several different devices.
* Frame Parameters::            Controlling frame size, position, font, etc.
* Terminal Parameters::         Parameters common for all frames on terminal.
* Frame Titles::                Automatic updating of frame titles.
* Deleting Frames::             Frames last until explicitly deleted.
* Finding All Frames::          How to examine all existing frames.
* Minibuffers and Frames::      How a frame finds the minibuffer to use.
* Input Focus::                 Specifying the selected frame.
* Visibility of Frames::        Frames may be visible or invisible, or icons.
* Raising and Lowering::        Raising a frame makes it hide other windows;
                                  lowering it makes the others hide it.
* Frame Configurations::        Saving the state of all frames.
* Mouse Tracking::              Getting events that say when the mouse moves.
* Mouse Position::              Asking where the mouse is, or moving it.
* Pop-Up Menus::                Displaying a menu for the user to select from.
* Dialog Boxes::                Displaying a box to ask yes or no.
* Pointer Shape::               Specifying the shape of the mouse pointer.
* Window System Selections::    Transferring text to and from other X clients.
* Drag and Drop::               Internals of Drag-and-Drop implementation.
* Color Names::                 Getting the definitions of color names.
* Text Terminal Colors::        Defining colors for text terminals.
* Resources::                   Getting resource values from the server.
* Display Feature Testing::     Determining the features of a terminal.
@end menu

@node Creating Frames
@section フレームの作成
@cindex frame creation

新たなフレームを作成するには、関数@code{make-frame}を呼び出す。

@deffn Command make-frame &optional alist
この関数は新たなフレームを作成し、現在のバッファを表示する。

引数@var{alist}はフレームパラメータを指定する連想リストである。
@xref{Frame Parameters}.  If you specify the
@code{terminal} parameter in @var{alist}, the new frame is created on
that terminal.  Otherwise, if you specify the @code{window-system}
frame parameter in @var{alist}, that determines whether the frame
should be displayed on a text terminal or a graphical terminal.
@xref{Window Systems}.  If neither is specified, the new frame is
created in the same terminal as the selected frame.

@var{alist}で指定していないパラメータは、
変数@code{default-frame-alist}の値に従って決まる（@pxref{Initial Parameters}）。
それでも決まらないパラメータは、
標準のXリソースやそれにかわる読者のオペレーティングシステムの設定を使う
（@pxref{X Resources,, X Resources,
emacs, The GNU Emacs Manual}）。
After the frame is created, Emacs
applies any parameters listed in @code{frame-inherited-parameters}
(see below) and not present in the argument, taking the values from
the frame that was selected when @code{make-frame} was called.

Note that on multi-monitor displays (@pxref{Multiple Terminals}), the
window manager might position the frame differently than specified by
the positional parameters in @var{alist} (@pxref{Position
Parameters}).  For example, some window managers have a policy of
displaying the frame on the monitor that contains the largest part of
the window (a.k.a.@: the @dfn{dominating} monitor).

This function itself does not make the new frame the selected frame.
@xref{Input Focus}.  The previously selected frame remains selected.
On graphical terminals, however, the windowing system may select the
new frame for its own reasons.
@end deffn

@defvar before-make-frame-hook
@code{make-frame}がフレームを実際に作成する直前に実行するノーマルフック。
@end defvar

@defvar after-make-frame-functions
@code{make-frame}がフレームを作成後に実行するアブノーマルフック。
@code{after-make-frame-functions}の各関数は、1つの引数、
つまり、作成したばかりのフレームを受け取る。
@end defvar

@defvar frame-inherited-parameters
This variable specifies the list of frame parameters that a newly
created frame inherits from the currently selected frame.  For each
parameter (a symbol) that is an element in the list and is not present
in the argument to @code{make-frame}, the function sets the value of
that parameter in the created frame to its value in the selected
frame.
@end defvar

@node Multiple Terminals
@section 複数端末
@cindex 端末、複数
@cindex multi-tty
@cindex 複数のX端末
@cindex displays, multiple

  Emacs represents each terminal as a @dfn{terminal object} data type
(@pxref{Terminal Type}).  On GNU and Unix systems, Emacs can use
multiple terminals simultaneously in each session.  On other systems,
it can only use a single terminal.  Each terminal object has the
following attributes:

@itemize @bullet
@item
The name of the device used by the terminal (e.g., @samp{:0.0} or
@file{/dev/tty}).

@item
The terminal and keyboard coding systems used on the terminal.
@xref{Terminal I/O Encoding}.

@item
The kind of display associated with the terminal.  This is the symbol
returned by the function @code{terminal-live-p} (i.e., @code{x},
@code{t}, @code{w32}, @code{ns}, or @code{pc}).  @xref{Frames}.

@item
A list of terminal parameters.  @xref{Terminal Parameters}.
@end itemize

  There is no primitive for creating terminal objects.  Emacs creates
them as needed, such as when you call @code{make-frame-on-display}
(described below).

@defun terminal-name &optional terminal
This function returns the file name of the device used by
@var{terminal}.  If @var{terminal} is omitted or @code{nil}, it
defaults to the selected frame's terminal.  @var{terminal} can also be
a frame, meaning that frame's terminal.
@end defun

@defun terminal-list
This function returns a list of all live terminal objects.
@end defun

@defun get-device-terminal device
This function returns a terminal whose device name is given by
@var{device}.  If @var{device} is a string, it can be either the file
name of a terminal device, or the name of an X display of the form
@samp{@var{host}:@var{server}.@var{screen}}.  If @var{device} is a
frame, this function returns that frame's terminal; @code{nil} means
the selected frame.  Finally, if @var{device} is a terminal object
that represents a live terminal, that terminal is returned.  The
function signals an error if its argument is none of the above.
@end defun

@defun delete-terminal &optional terminal force
This function deletes all frames on @var{terminal} and frees the
resources used by it.  It runs the abnormal hook
@code{delete-terminal-functions}, passing @var{terminal} as the
argument to each function.

If @var{terminal} is omitted or @code{nil}, it defaults to the
selected frame's terminal.  @var{terminal} can also be a frame,
meaning that frame's terminal.

Normally, this function signals an error if you attempt to delete the
sole active terminal, but if @var{force} is non-@code{nil}, you are
allowed to do so.  Emacs automatically calls this function when the
last frame on a terminal is deleted (@pxref{Deleting Frames}).
@end defun

@defvar delete-terminal-functions
An abnormal hook run by @code{delete-terminal}.  Each function
receives one argument, the @var{terminal} argument passed to
@code{delete-terminal}.  Due to technical details, the functions may
be called either just before the terminal is deleted, or just
afterwards.
@end defvar

@cindex terminal-local variables
  A few Lisp variables are @dfn{terminal-local}; that is, they have a
separate binding for each terminal.  The binding in effect at any time
is the one for the terminal that the currently selected frame belongs
to.  These variables include @code{default-minibuffer-frame},
@code{defining-kbd-macro}, @code{last-kbd-macro}, and
@code{system-key-alist}.  They are always terminal-local, and can
never be buffer-local (@pxref{Buffer-Local Variables}).

  On GNU and Unix systems, each X display is a separate graphical
terminal.  When Emacs is started from within the X window system, it
uses the X display specified by the @env{DISPLAY} environment
variable, or by the @samp{--display} option (@pxref{Initial Options,,,
emacs, The GNU Emacs Manual}).  Emacs can connect to other X displays
via the command @code{make-frame-on-display}.  Each X display has its
own selected frame and its own minibuffer windows; however, only one
of those frames is ``@emph{the} selected frame'' at any given moment
(@pxref{Input Focus}).  Emacs can even connect to other text
terminals, by interacting with the @command{emacsclient} program.
@xref{Emacs Server,,, emacs, The GNU Emacs Manual}.

@cindex X display names
@cindex display name on X
  A single X server can handle more than one display.  Each X display
has a three-part name,
@samp{@var{hostname}:@var{displaynumber}.@var{screennumber}}.  The
first part, @var{hostname}, specifies the name of the machine to which
the display is physically connected.  The second part,
@var{displaynumber}, is a zero-based number that identifies one or
more monitors connected to that machine that share a common keyboard
and pointing device (mouse, tablet, etc.).  The third part,
@var{screennumber}, identifies a zero-based screen number (a separate
monitor) that is part of a single monitor collection on that X server.
When you use two or more screens belonging to one server, Emacs knows
by the similarity in their names that they share a single keyboard.

  Systems that don't use the X window system, such as MS-Windows,
don't support the notion of X displays, and have only one display on
each host.  The display name on these systems doesn't follow the above
3-part format; for example, the display name on MS-Windows systems is
a constant string @samp{w32}, and exists for compatibility, so that
you could pass it to functions that expect a display name.

@deffn Command make-frame-on-display display &optional parameters
新たなフレームをディスプレイ@var{display}上に作成する。
他のフレームパラメータは@var{parameters}から得る。
@var{display} should be the name of an X display (a string).

Before creating the frame, this function ensures that Emacs is ``set
up'' to display graphics.  For instance, if Emacs has not processed X
resources (e.g., if it was started on a text terminal), it does so at
this time.  In all other respects, this function behaves like
@code{make-frame} (@pxref{Creating Frames}).
@end deffn

@defun x-display-list
Emacsが接続しているXディスプレイを表すリストを返す。
リストの要素は文字列であり、それぞれはディスプレイ名である。
@end defun

@defun x-open-connection display &optional xrm-string must-succeed
この関数はXディスプレイ@var{display}との接続を、フレームは作らずに開く。
Normally, Emacs Lisp
programs need not call this function, as @code{make-frame-on-display}
calls it automatically.  The only reason for calling it is to check
whether communication can be established with a given X display.
この関数を呼び出す唯一の理由は、
当該ディスプレイと通信可能かどうか検査するためである。

省略可能な引数@var{xrm-string}が@code{nil}でなければ、
ファイル@file{.Xresources}で使われ書式と同じ
リソース名と値を表す文字列である。
@xref{X Resources,, X Resources, emacs, The
GNU Emacs Manual}.
これに指定した値は、Xサーバー自体に記録されているリソースの値に優先し、
Emacsが当該ディスプレイ上に作成するすべてのフレームに適用される。
この文字列の例を以下に示す。

@example
"*BorderWidth: 3\n*InternalBorder: 2\n"
@end example

If @var{must-succeed} is non-@code{nil}, failure to open the connection
terminates Emacs.  Otherwise, it is an ordinary Lisp error.
@end defun

@defun x-close-connection display
この関数はディスプレイ@var{display}との接続を閉じる。
これを行うまえに、
まず当該ディスプレイ上に作ったフレームをすべて削除しなければならない
（@pxref{Deleting Frames}）。
@end defun

@cindex multi-monitor
  On some ``multi-monitor'' setups, a single X display outputs to more
than one physical monitor.  You can use the functions
@code{display-monitor-attributes-list} and @code{frame-monitor-attributes}
to obtain information about such setups.

@defun display-monitor-attributes-list &optional display
This function returns a list of physical monitor attributes on
@var{display}, which can be a display name (a string), a terminal, or
a frame; if omitted or @code{nil}, it defaults to the selected frame's
display.  Each element of the list is an association list,
representing the attributes of a physical monitor.  The first element
corresponds to the primary monitor.  The attribute keys and values
are:

@table @samp
@item geometry
Position of the top-left corner of the monitor's screen and its size,
in pixels, as @samp{(@var{x} @var{y} @var{width} @var{height})}.  Note
that, if the monitor is not the primary monitor, some of the
coordinates might be negative.

@item workarea
Position of the top-left corner and size of the work area (``usable''
space) in pixels as @samp{(@var{x} @var{y} @var{width} @var{height})}.
This may be different from @samp{geometry} in that space occupied by
various window manager features (docks, taskbars, etc.)@: may be
excluded from the work area.  Whether or not such features actually
subtract from the work area depends on the platform and environment.
Again, if the monitor is not the primary monitor, some of the
coordinates might be negative.

@item mm-size
Width and height in millimeters as @samp{(@var{width} @var{height})}

@item frames
List of frames that this physical monitor dominates (see below).

@item name
Name of the physical monitor as @var{string}.

@item source
Source of the multi-monitor information as @var{string};
e.g., @samp{XRandr} or @samp{Xinerama}.
@end table

@var{x}, @var{y}, @var{width}, and @var{height} are integers.
@samp{name} and @samp{source} may be absent.

A frame is @dfn{dominated} by a physical monitor when either the
largest area of the frame resides in that monitor, or (if the frame
does not intersect any physical monitors) that monitor is the closest
to the frame.  Every (non-tooltip) frame (whether visible or not) in a
graphical display is dominated by exactly one physical monitor at a
time, though the frame can span multiple (or no) physical monitors.

Here's an example of the data produced by this function on a 2-monitor
display:

@lisp
  (display-monitor-attributes-list)
  @result{}
  (((geometry 0 0 1920 1080) ;; @r{Left-hand, primary monitor}
    (workarea 0 0 1920 1050) ;; @r{A taskbar occupies some of the height}
    (mm-size 677 381)
    (name . "DISPLAY1")
    (frames #<frame emacs@@host *Messages* 0x11578c0>
            #<frame emacs@@host *scratch* 0x114b838>))
   ((geometry 1920 0 1680 1050) ;; @r{Right-hand monitor}
    (workarea 1920 0 1680 1050) ;; @r{Whole screen can be used}
    (mm-size 593 370)
    (name . "DISPLAY2")
    (frames)))
@end lisp

@end defun

@defun frame-monitor-attributes &optional frame
This function returns the attributes of the physical monitor
dominating (see above) @var{frame}, which defaults to the selected frame.
@end defun

@node Frame Parameters
@section フレームパラメータ
@cindex frame parameters

フレームには、その見ためやふるまいを制御する多くのパラメータがあります。
フレームのパラメータの種類は、使用する表示機構に依存します。

フレームパラメータはグラフィック表示向けです。
多くのパラメータはテキスト端末に適用されたときは効果がありません。
@code{height}、@code{width}、@code{name}、@code{title}、
@code{menu-bar-lines}、@code{buffer-list}、
そして@code{buffer-predicate}のパラメータだけが意味を持ちます。
If the
terminal supports colors, the parameters @code{foreground-color},
@code{background-color}, @code{background-mode} and
@code{display-type} are also meaningful.  If the terminal supports
frame transparency, the parameter @code{alpha} is also meaningful.

@menu
* Parameter Access::       How to change a frame's parameters.
* Initial Parameters::     Specifying frame parameters when you make a frame.
* Window Frame Parameters:: List of frame parameters for window systems.
* Size and Position::      Changing the size and position of a frame.
* Geometry::               Parsing geometry specifications.
@end menu

@node Parameter Access
@subsection フレームパラメータの参照

これらの関数は、フレームのパラメータの値を読んだり変更するためのものです。

@defun frame-parameter frame parameter
This function returns the value of the parameter @var{parameter} (a
symbol) of @var{frame}.  If @var{frame} is @code{nil}, it returns the
selected frame's parameter.  If @var{frame} has no setting for
@var{parameter}, this function returns @code{nil}.
@end defun

@defun frame-parameters &optional frame
関数@code{frame-parameters}は、
@var{frame}のすべてのパラメータとそれらの値から成る連想リストを返す。
If @var{frame} is
@code{nil} or omitted, this returns the selected frame's parameters
@end defun

@defun modify-frame-parameters frame alist
この関数は、@var{alist}の要素に基づいてフレーム@var{frame}の
パラメータを変更する。
@var{alist}の各要素は@code{(@var{parm} . @var{value})}の形であり、
@var{parm}はパラメータを表すシンボルである。
@var{alist}に指定しないパラメータの値は変更されない。
If @var{frame} is @code{nil}, it defaults to the selected
frame.
@end defun

@defun set-frame-parameter frame parm value
This function sets the frame parameter @var{parm} to the specified
@var{value}.  If @var{frame} is @code{nil}, it defaults to the
selected frame.
@end defun

@defun modify-all-frames-parameters alist
This function alters the frame parameters of all existing frames
according to @var{alist}, then modifies @code{default-frame-alist}
(and, if necessary, @code{initial-frame-alist}) to apply the same
parameter values to frames that will be created henceforth.
@end defun

@node Initial Parameters
@subsection 初期フレームのパラメータ
@cindex parameters of initial frame

読者のファイル（@pxref{Init
File}）で@code{initial-frame-alist}に設定すれば、
起動時の初期フレームのパラメータを指定できます。

@defopt initial-frame-alist
この変数の値は、初期フレームを作るときに
使用するパラメータの値から成る連想リストである。
この変数を指定すれば初期フレームの見ためを指定できるが、
それ以降に作成するフレームには影響しない。
各要素はつぎの形である。

@example
(@var{parameter} . @var{value})
@end example

Emacsは初期設定ファイルを読むまえに初期フレームを作る。
このファイルを読んだあとに、Emacsは@code{initial-frame-alist}を検査し
異なる値が設定されているパラメータをすでに作成した初期フレームに適用する。

これらの設定がフレームの大きさと位置や見ために関するものであると、
指定とは違うフレームが現れてから指定したものに変わるのを目にする。
これがわずらわしい場合には、Xリソースにも同じ大きさと位置や見ためを指定する。
Xリソースはフレームを作成するまえに適用される。
@xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}。

Xリソースの設定は、典型的にはすべてのフレームに適用される。
初期フレームだけに特定のXリソースを指定し、
それ以降のフレームに適用したくない場合には、つぎのようにする。
パラメータを@code{default-frame-alist}で指定し、
以降のフレーム向けのXリソースを無効にする。
そしてそれらが初期フレームに影響しないように、
@code{initial-frame-alist}のパラメータでXリソースに一致する値を指定する。
@end defopt

@cindex minibuffer-only frame
これらのパラメータにミニバッファ専用のフレームを作る
@code{(minibuffer . nil)}を指定しているのに
@dfn{ミニバッファ専用フレーム}を作っていないと、Emacsがそれを作成します。

@defopt minibuffer-frame-alist
この変数の値は、初期のミニバッファ専用フレームを作るときに使用する
パラメータの連想リストである。
(i.e., the minibuffer-only
frame that Emacs creates if @code{initial-frame-alist} specifies a
frame with no minibuffer)
@end defopt

@defopt default-frame-alist
これは、Emacsのすべてのフレーム、つまり、
初期フレームとそれ以降のフレームのフレームパラメータのデフォルト値を
指定する連想リストである。
Xウィンドウシステムを使っているときには、多くの場合、
Xリソースによっても同じ結果を得られる。

Setting this variable does not affect existing frames.  Furthermore,
functions that display a buffer in a separate frame may override the
default parameters by supplying their own parameters.
@end defopt

Emacsを起動するときにウィンドウの姿形を指定するオプションを使うと、
それらは@code{initial-frame-alist}または@code{default-frame-alist}に要素を追加することで効果を発揮します。
Options
which affect just the initial frame, such as @samp{--geometry} and
@samp{--maximized}, add to @code{initial-frame-alist}; the others add
to @code{default-frame-alist}.  @pxref{Emacs Invocation,, Command Line
Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}.

@node Window Frame Parameters
@subsection ウィンドウフレームのパラメータ
@cindex frame parameters for windowed displays

フレームのパラメータの種類は、使用する表示機構に依存します。
ウィンドウフレームにおいて特別な意味を持つパラメータの一覧をつぎに示します。
これらのうち、@code{name}、@code{title}、@code{height}、
@code{width}、@code{buffer-list}、@code{buffer-predicate}は
端末フレームでも意味を持ち、
@code{tty-color-mode}はテキスト端末でしか意味を持たない。

@menu
* Basic Parameters::            Parameters that are fundamental.
* Position Parameters::         The position of the frame on the screen.
* Size Parameters::             Frame's size.
* Layout Parameters::           Size of parts of the frame, and
                                  enabling or disabling some parts.
* Buffer Parameters::           Which buffers have been or should be shown.
* Management Parameters::       Communicating with the window manager.
* Cursor Parameters::           Controlling the cursor appearance.
* Font and Color Parameters::   Fonts and colors for the frame text.
@end menu

@node Basic Parameters
@subsubsection Basic Parameters

  These frame parameters give the most basic information about the
frame.  @code{title} and @code{name} are meaningful on all terminals.

@table @code
@vindex display, a frame parameter
@item display
このフレームを開くディスプレイ。
環境変数@env{DISPLAY}と同様に、
@samp{@var{host}:@var{dpy}.@var{screen}}の形の文字列であること。
@xref{Multiple Terminals}, for
more details about display names.

@vindex display-type, a frame parameter
@item display-type
このパラメータはこのフレームで使用可能な表示色の範囲を表す。
値は、@code{color}、@code{grayscale}、@code{mono}のいずれかである。

@vindex title, a frame parameter
@item title
フレームが@code{nil}以外のタイトルであれば、
フレーム向けのウィンドウシステムの枠にタイトルが現れる。
また、@code{mode-line-frame-identification}に@samp{%F}
（@pxref{%-Constructs}）を使っていれば、
当該フレームのモード行にもタイトルが現れる。
Emacsがウィンドウシステムを使っていない場合には、
これは普通はモード行に表示され一度に1つのフレームだけを表示できる。
@xref{Frame Titles}。

@vindex name, a frame parameter
@item name
フレームの名前。
パラメータ@code{title}を指定しないか@code{nil}であると、
フレーム名はフレームタイトルのデフォルトになる。
名前を指定しないと、Emacsが自動的にフレーム名を設定する
（@pxref{Frame Titles}）。

フレームを作るときにフレーム名を明示的に指定すると、
その名前は（Emacsの実行形式ファイルの名前のかわりに）
フレーム向けのXリソースを探すためにも使われる。

@item explicit-name
If the frame name was specified explicitly when the frame was created,
this parameter will be that name.  If the frame wasn't explicitly
named, this parameter will be @code{nil}.
@end table

@node Position Parameters
@subsubsection Position Parameters
@cindex window position on display
@cindex frame position

  Position parameters' values are normally measured in pixels, but on
text terminals they count characters or lines instead.

@table @code
@vindex left, a frame parameter
@item left
スクリーンの左端を基準にしたピクセル単位の左端位置。
この値は以下のいずれかである。

@table @asis
@item 整数
正の整数は、フレームの左端とスクリーンの左端を関係を定める。
負の整数は、フレームの右端とスクリーンの右端を関係を定める。

@item @code{(+ @var{pos})}
スクリーンの左端を基準にしたウィンドウの左端位置を指定する。
The integer @var{pos} may be positive or negative; a
negative value specifies a position outside the screen or on a monitor
other than the primary one (for multi-monitor displays).

@item @code{(- @var{pos})}
スクリーンの右端を基準にしたウィンドウの右端位置を指定する。
The integer @var{pos} may be positive or negative; a
negative value specifies a position outside the screen or on a monitor
other than the primary one (for multi-monitor displays).
@end table

Some window managers ignore program-specified positions.  If you want to
be sure the position you specify is not ignored, specify a
non-@code{nil} value for the @code{user-position} parameter as well.

@vindex top, a frame parameter
@item top
The screen position of the top (or bottom) edge, in pixels, with respect
to the top (or bottom) edge of the screen.  It works just like
@code{left}, except vertically instead of horizontally.

@vindex icon-left, a frame parameter
@item icon-left
スクリーンの左端を基準にした
フレームのアイコンのピクセル単位の左端位置。
ウィンドウマネージャがアイコン化の機能を持つ場合、フレームをアイコンにしたときに効果を発揮する。
If you specify a value for this parameter, then you must also specify a
value for @code{icon-top} and vice versa.

@vindex icon-top, a frame parameter
@item icon-top
スクリーンの上端を基準にした
フレームのアイコンのピクセル単位の上端位置。
ウィンドウマネージャがアイコン化の機能を持つ場合、フレームをアイコンにしたときに効果を発揮する。

@vindex user-position, a frame parameter
@item user-position
パラメータ@code{left}と@code{top}でスクリーン上の位置を指定して
フレームを作るときに、このパラメータは指定位置が、
（利用者がなんらかの方法で与えた）ユーザー指定のものなのか、
（プログラムが選んだ）プログラム指定のものなのかを指定する。
@code{nil}以外の値であるとユーザー指定の位置であることを意味する。

@cindex window positions and window managers
ウィンドウマネージャはユーザー指定の位置を一般に尊重し、
プログラム指定の位置も尊重するものもある。
しかしその多くはプログラム指定の位置を無視し、
デフォルトに基づいてウィンドウを配置したり、
マウスでユーザーに配置させる。
@code{twm}を含むウィンドウマネージャには、
プログラム指定の位置に従うかそれらを無視するかを
ユーザーが指定できるものもある。

@code{make-frame}を呼び出すときには、
パラメータ@code{left}と@code{top}の値がユーザーの希望を表す場合には
このパラメータの値には@code{nil}以外を指定すること。
さもなければ@code{nil}を指定する。
@end table


@node Size Parameters
@subsubsection Size Parameters
@cindex window size on display

  Frame parameters specify frame sizes in character units.  On
graphical displays, the @code{default} face determines the actual
pixel sizes of these character units (@pxref{Face Attributes}).

@table @code
@vindex height, a frame parameter
@item height
フレームの内側の文字単位の高さ（@pxref{Size and Position}）。

@vindex width, a frame parameter
@item width
フレームの内側の文字単位の幅（@pxref{Size and Position}）。

@vindex user-size, a frame parameter
@item user-size
This does for the size parameters @code{height} and @code{width} what
the @code{user-position} parameter (@pxref{Position Parameters,
user-position}) does for the position parameters @code{top} and
@code{left}.

@cindex full-screen frames
@vindex fullscreen, a frame parameter
@item fullscreen
Specify that width, height or both shall be maximized.  The value
@code{fullwidth} specifies that width shall be as wide as possible.  The
value @code{fullheight} specifies that height shall be as tall as
possible.  The value @code{fullboth} specifies that both the width and
the height shall be set to the size of the screen.  The value
@code{maximized} specifies that the frame shall be maximized.

The difference between @code{maximized} and @code{fullboth} is that a
maximized frame usually keeps its title bar and the buttons for resizing
and closing the frame.  Also, maximized frames typically avoid hiding
any task bar or panels displayed on the desktop.  ``Fullboth'' frames,
on the other hand, usually omit the title bar and occupy the entire
available screen space.

``Fullheight'' and ``fullwidth'' frames are more similar to maximized
frames in this regard.  However, these typically display an external
border which might be absent with maximized frames.  Hence the heights
of maximized and fullheight frames and the widths of maximized and
fullwidth frames often differ by a few pixels.

With some window managers you may have to customize the variable
@code{frame-resize-pixelwise} (@pxref{Size and Position}) in order to
make a frame truly appear ``maximized'' or ``fullscreen''.  Moreover,
some window managers might not support smooth transition between the
various fullscreen or maximization states.  Customizing the variable
@code{x-frame-normalize-before-maximize} can help to overcome that.

@vindex fullscreen-restore, a frame parameter
@item fullscreen-restore
This parameter specifies the desired ``fullscreen'' state of the frame
after invoking the @code{toggle-frame-fullscreen} command (@pxref{Frame
Commands,,, emacs, The GNU Emacs Manual}) in the ``fullboth'' state.
Normally this parameter is installed automatically by that command when
toggling the state to fullboth.  If, however, you start Emacs in the
fullboth state, you have to specify the desired behavior in your initial
file as, for example

@example
(setq default-frame-alist
    '((fullscreen . fullboth) (fullscreen-restore . fullheight)))
@end example

This will give a new frame full height after typing in it @key{F11} for
the first time.
@end table


@node Layout Parameters
@subsubsection Layout Parameters
@cindex layout parameters of frames
@cindex frame layout parameters

  These frame parameters enable or disable various parts of the
frame, or control their sizes.

@table @code
@vindex border-width, a frame parameter
@item border-width
ウィンドウ枠のピクセル単位の幅。

@vindex internal-border-width, a frame parameter
@item internal-border-width
枠とテキスト（またはフリンジ）のあいだのピクセル単位の間隔。

@vindex vertical-scroll-bars, a frame parameter
@item vertical-scroll-bars
フレームに垂直スクロール用のスクロールバーを付けるかどうか、
どちら側に付けるかを表す。
指定できる値は、@code{left}、@code{right}、あるいは
スクロールバーなしを意味する@code{nil}。

@vindex horizontal-scroll-bars, a frame parameter
@item horizontal-scroll-bars
水平スクロール用のスクロールバーを付けるかどうかを表す。
(@code{t} and @code{bottom} mean yes, @code{nil} means no).

@vindex scroll-bar-width, a frame parameter
@item scroll-bar-width
垂直スクロールバーのピクセル単位の幅。
@code{nil} meaning to
use the default width.

@vindex scroll-bar-height, a frame parameter
@item scroll-bar-height
The height of horizontal scroll bars, in pixels, or @code{nil} meaning
to use the default height.

@vindex left-fringe, a frame parameter
@vindex right-fringe, a frame parameter
@item left-fringe
@itemx right-fringe
The default width of the left and right fringes of windows in this
frame (@pxref{Fringes}).  If either of these is zero, that effectively
removes the corresponding fringe.

When you use @code{frame-parameter} to query the value of either of
these two frame parameters, the return value is always an integer.
When using @code{set-frame-parameter}, passing a @code{nil} value
imposes an actual default value of 8 pixels.

@vindex right-divider-width, a frame parameter
@item right-divider-width
The width (thickness) reserved for the right divider (@pxref{Window
Dividers}) of any window on the frame, in pixels.  A value of zero means
to not draw right dividers.

@vindex bottom-divider-width, a frame parameter
@item bottom-divider-width
The width (thickness) reserved for the bottom divider (@pxref{Window
Dividers}) of any window on the frame, in pixels.  A value of zero means
to not draw bottom dividers.

@vindex menu-bar-lines frame parameter
@item menu-bar-lines
フレームの上端に割り当てるメニューバー向けの行の個数。
メニューバーモードが有効ならデフォルトは1で、そうでなければ０である。
@xref{Menu Bars,,,emacs, The GNU Emacs Manual}.

@vindex tool-bar-lines frame parameter
@item tool-bar-lines
The number of lines to use for the tool bar.  The default is 1 if Tool
Bar mode is enabled, and 0 otherwise.  @xref{Tool Bars,,,emacs, The
GNU Emacs Manual}.

@vindex tool-bar-position frame parameter
@item tool-bar-position
The position of the tool bar.  Currently only for the GTK tool bar.
Value can be one of @code{top}, @code{bottom} @code{left}, @code{right}.
The default is  @code{top}.

@vindex line-spacing, a frame parameter
@item line-spacing
Additional space to leave below each text line, in pixels (a positive
integer).  @xref{Line Height}, for more information.
@end table

@node Buffer Parameters
@subsubsection Buffer Parameters
@cindex frame, which buffers to display
@cindex buffers to display on frame

  These frame parameters, meaningful on all kinds of terminals, deal
with which buffers have been, or should, be displayed in the frame.

@table @code
@vindex minibuffer, a frame parameter
@item minibuffer
このフレームに独自のミニバッファがあるかどうかを表す。
値@code{t}はあることを表し、@code{nil}はないことを表す。
@code{only}は、このフレームがミニバッファだけであることを表す。
（別のフレームの）値がミニバッファだけであると、
新たなフレームはそのミニバッファを使う。

This frame parameter takes effect when the frame is created, and can
not be changed afterwards.

@vindex buffer-predicate, a frame parameter
@item buffer-predicate
このフレーム向けのバッファ述語関数。
これが@code{nil}でなければ、
関数@code{other-buffer}が（選択されているフレームから）この述語を使用して、
どのバッファにするかを決定する。
当該関数は各バッファごとにバッファを引数としてこの述語関数を呼び出す。
この述語が@code{nil}以外を返すと当該バッファを選ぶ。

@vindex buffer-list, a frame parameter
@item buffer-list
このフレームで選択されたバッファを
もっとも最近に選択されたものから順に並べたリスト。

@vindex unsplittable, a frame parameter
@item unsplittable
@code{nil}以外であると、このフレームのウィンドウをけっして自動的に分割しない。
@end table

@node Management Parameters
@subsubsection Window Management Parameters
@cindex window manager interaction, and frame parameters

  The following frame parameters control various aspects of the
frame's interaction with the window manager.  They have no effect on
text terminals.

@table @code
@vindex visibility, a frame parameter
@item visibility
フレームの可視性。
不可視を表す@code{nil}、可視を表す@code{t}、
アイコンになっていることを表す@code{icon}の3の可能性がある。
@xref{Visibility of Frames}。

@vindex auto-raise, a frame parameter
@item auto-raise
フレームを選択したときにフレームを手前に移動するかどうかを表す
（@code{nil}以外であるとそのようにする）。
Some window managers do not allow this.

@vindex auto-lower, a frame parameter
@item auto-lower
フレームの選択を止めたときにフレームを奥へ移動するかどうかを表す
（@code{nil}以外であるとそのようにする）。
Some window managers do not allow this.

@vindex icon-type, a frame parameter
@item icon-type
このフレームをアイコンにしたときに使うアイコンの種類。
値が文字列であると、使用するビットマップを収めたファイルを指定する。
それ以外の@code{nil}以外の値はデフォルトのビットマップアイコン
を指定する。
@code{nil}はアイコンなしを指定する。

@vindex icon-name, a frame parameter
@item icon-name
このフレーム向けのアイコンを表示するときに使用するアイコンの名前。
これが@code{nil}であると、フレームのタイトルを使う。

@vindex window-id, a frame parameter
@item window-id
The ID number which the graphical display uses for this frame.  Emacs
assigns this parameter when the frame is created; changing the
parameter has no effect on the actual ID number.

@vindex outer-window-id, a frame parameter
@item outer-window-id
The ID number of the outermost window-system window in which the frame
exists.  As with @code{window-id}, changing this parameter has no
actual effect.

@vindex wait-for-wm, a frame parameter
@item wait-for-wm
If non-@code{nil}, tell Xt to wait for the window manager to confirm
geometry changes.  Some window managers, including versions of Fvwm2
and KDE, fail to confirm, so Xt hangs.  Set this to @code{nil} to
prevent hanging with those window managers.

@vindex sticky, a frame parameter
@item sticky
If non-@code{nil}, the frame is visible on all virtual desktops on systems
with virtual desktops.

@ignore
@vindex parent-id, a frame parameter
@item parent-id
@c ??? Not yet working.
The X window number of the window that should be the parent of this one.
Specifying this lets you create an Emacs window inside some other
application's window.  (It is not certain this will be implemented; try
it and see if it works.)
@end ignore
@end table

@node Cursor Parameters
@subsubsection Cursor Parameters
@cindex cursor, and frame parameters

  This frame parameter controls the way the cursor looks.

@table @code
@vindex cursor-type, a frame parameter
@item cursor-type
カーソルの表示方法。
取りうる値は：

@table @code
@item box
黒い塗りつぶされた箱型を表示。（これがデフォルト）
@item hollow
黒い箱を表示。
@item nil
カーソルを表示しない。
@item bar
文字のあいだに縦棒を表示する。
@item (bar . @var{width})
Display a vertical bar @var{width} pixels wide between characters.
@item hbar
Display a horizontal bar.
@item (hbar . @var{height})
Display a horizontal bar @var{height} pixels high.
@end table
@end table

@vindex cursor-type
The @code{cursor-type} frame parameter may be overridden by the
variables @code{cursor-type} and
@code{cursor-in-non-selected-windows}:

@defvar cursor-type
This buffer-local variable controls how the cursor looks in a selected
window showing the buffer.  If its value is @code{t}, that means to
use the cursor specified by the @code{cursor-type} frame parameter.
Otherwise, the value should be one of the cursor types listed above,
and it overrides the @code{cursor-type} frame parameter.
@end defvar

@defopt cursor-in-non-selected-windows
This buffer-local variable controls how the cursor looks in a window
that is not selected.  It supports the same values as the
@code{cursor-type} frame parameter; also, @code{nil} means don't
display a cursor in nonselected windows, and @code{t} (the default)
means use a standard modification of the usual cursor type (solid box
becomes hollow box, and bar becomes a narrower bar).
@end defopt

@defopt blink-cursor-alist
This variable specifies how to blink the cursor.  Each element has the
form @code{(@var{on-state} . @var{off-state})}.  Whenever the cursor
type equals @var{on-state} (comparing using @code{equal}), the
corresponding @var{off-state} specifies what the cursor looks like
when it blinks ``off''.  Both @var{on-state} and @var{off-state}
should be suitable values for the @code{cursor-type} frame parameter.

There are various defaults for how to blink each type of cursor, if
the type is not mentioned as an @var{on-state} here.  Changes in this
variable do not take effect immediately, only when you specify the
@code{cursor-type} frame parameter.
@end defopt

@node Font and Color Parameters
@subsubsection Font and Color Parameters
@cindex font and color, frame parameters

  These frame parameters control the use of fonts and colors.

@table @code
@vindex font-backend, a frame parameter
@item font-backend
A list of symbols, specifying the @dfn{font backends} to use for
drawing fonts in the frame, in order of priority.  On X, there are
currently two available font backends: @code{x} (the X core font
driver) and @code{xft} (the Xft font driver).  On MS-Windows, there are
currently two available font backends: @code{gdi} and
@code{uniscribe} (@pxref{Windows Fonts,,, emacs, The GNU Emacs
Manual}).  On other systems, there is only one available font backend,
so it does not make sense to modify this frame parameter.

@vindex background-mode, a frame parameter
@item background-mode
This parameter is either @code{dark} or @code{light}, according
to whether the background color is a light one or a dark one.

@vindex tty-color-mode, a frame parameter
@item tty-color-mode
@cindex standard colors for character terminals
This parameter overrides the terminal's color support as given by the
system's terminal capabilities database in that this parameter's value
specifies the color mode to use on a text terminal.  The value can be
either a symbol or a number.  A number specifies the number of colors
to use (and, indirectly, what commands to issue to produce each
color).  For example, @code{(tty-color-mode . 8)} specifies use of the
ANSI escape sequences for 8 standard text colors.  A value of -1 turns
off color support.

If the parameter's value is a symbol, it specifies a number through
the value of @code{tty-color-mode-alist}, and the associated number is
used instead.

@vindex screen-gamma, a frame parameter
@item screen-gamma
@cindex gamma correction
If this is a number, Emacs performs ``gamma correction'' which adjusts
the brightness of all colors.  The value should be the screen gamma of
your display.

Usual PC monitors have a screen gamma of 2.2, so color values in
Emacs, and in X windows generally, are calibrated to display properly
on a monitor with that gamma value.  If you specify 2.2 for
@code{screen-gamma}, that means no correction is needed.  Other values
request correction, designed to make the corrected colors appear on
your screen the way they would have appeared without correction on an
ordinary monitor with a gamma value of 2.2.

If your monitor displays colors too light, you should specify a
@code{screen-gamma} value smaller than 2.2.  This requests correction
that makes colors darker.  A screen gamma value of 1.5 may give good
results for LCD color displays.

@vindex alpha, a frame parameter
@item alpha
@cindex opacity, frame
@cindex transparency, frame
@vindex frame-alpha-lower-limit
This parameter specifies the opacity of the frame, on graphical
displays that support variable opacity.  It should be an integer
between 0 and 100, where 0 means completely transparent and 100 means
completely opaque.  It can also have a @code{nil} value, which tells
Emacs not to set the frame opacity (leaving it to the window manager).

To prevent the frame from disappearing completely from view, the
variable @code{frame-alpha-lower-limit} defines a lower opacity limit.
If the value of the frame parameter is less than the value of this
variable, Emacs uses the latter.  By default,
@code{frame-alpha-lower-limit} is 20.

The @code{alpha} frame parameter can also be a cons cell
@code{(@samp{active} . @samp{inactive})}, where @samp{active} is the
opacity of the frame when it is selected, and @samp{inactive} is the
opacity when it is not selected.
@end table

The following frame parameters are semi-obsolete in that they are
automatically equivalent to particular face attributes of particular
faces (@pxref{Standard Faces,,, emacs, The Emacs Manual}):

@table @code
@vindex font, a frame parameter
@item font
フレーム内でテキストの表示に使うフォントの名前。
これは、読者のシステムにおいて正しいフォントの名前であるか
Emacsのフォントセット（@pxref{Fontsets}）の名前を表す文字列である。
It is equivalent to the @code{font}
attribute of the @code{default} face.

@vindex foreground-color, a frame parameter
@item foreground-color
文字の描画に使う表示色。
It is equivalent to
the @code{:foreground} attribute of the @code{default} face.

@vindex background-color, a frame parameter
@item background-color
文字の背景に使う表示色。
It is equivalent to
the @code{:background} attribute of the @code{default} face.

@vindex mouse-color, a frame parameter
@item mouse-color
マウスポインタの表示色。
It is equivalent to the @code{:background}
attribute of the @code{mouse} face.

@vindex cursor-color, a frame parameter
@item cursor-color
ポイントを表すカーソルの表示色。
It is equivalent to the
@code{:background} attribute of the @code{cursor} face.

@vindex border-color, a frame parameter
@item border-color
フレームの枠の表示色。
It is equivalent to the
@code{:background} attribute of the @code{border} face.

@vindex scroll-bar-foreground, a frame parameter
@item scroll-bar-foreground
If non-@code{nil}, the color for the foreground of scroll bars.  It is
equivalent to the @code{:foreground} attribute of the
@code{scroll-bar} face.

@vindex scroll-bar-background, a frame parameter
@item scroll-bar-background
If non-@code{nil}, the color for the background of scroll bars.  It is
equivalent to the @code{:background} attribute of the
@code{scroll-bar} face.
@end table


@node Size and Position
@subsection フレームのサイズと位置
@cindex フレームサイズ
@cindex サイズ、フレーム
@cindex サイズ、スクリーン
@cindex リサイズ、フレーム

フレームパラメータ@code{left}、@code{top}、@code{height}、@code{width}を
使って、フレームのサイズや位置を読み取ったり変更できます。
指定しなかった大きさと位置のパラメータは、
ウィンドウマネージャが通常どおりに選びます。

以下はサイズや位置を操作する特別な機能です。
Most of the functions described below use a @var{frame} argument which
has to specify a live frame.  If omitted or @code{nil}, it specifies the
selected frame, see @ref{Input Focus}.

@defun set-frame-position frame left top
この関数は、フレーム@var{frame}の左上隅の位置を
@var{left}（左端）と@var{top}（上端）にする。
これらの引数は、スクリーンの左上隅から、
ウィンドウマネージャによって割り当てられた矩形領域の左上隅までを
ピクセル単位で数える。

パラメータ値が負であると、スクリーンの下端から測ってウィンドウの下端を
位置決めしたり、スクリーンの右端から測ってウィンドウの右端を位置決めする。
つねに左端や上端から測った値にして、負の値はフレームを
スクリーンの上端や左端から部分的にはみ出して位置決めする
意味にするほうがよいかもしれないが、
現状ではそのように変えるのは不適当と思われる。
@end defun

@cindex frame default font
@cindex default font of a frame
Each frame has a @dfn{default font} which specifies the canonical height
and width of a character on that frame.  The default font is used when
retrieving or changing the size of a frame in terms of columns or lines.
It is also used when resizing (@pxref{Window Sizes}) or splitting
(@pxref{Splitting Windows}) windows.

@defun frame-char-height &optional frame
@defunx frame-char-width &optional frame
これらの関数は、フレーム@var{frame}内の文字の高さや幅をピクセル単位で返す。
Together, these values establish the
size of the default font on @var{frame}.  The values depend on the
choice of font for @var{frame}, see @ref{Font and Color Parameters}.
@end defun

The default font can be also set directly with the following function:

@deffn Command set-frame-font font &optional keep-size frames
This sets the default font to @var{font}.  When called interactively, it
prompts for the name of a font, and uses that font on the selected
frame.  When called from Lisp, @var{font} should be a font name (a
string), a font object, font entity, or a font spec.

If the optional argument @var{keep-size} is @code{nil}, this keeps the
number of frame lines and columns fixed.  (If non-@code{nil}, the option
@code{frame-inhibit-implied-resize} described below will override this.)
If @var{keep-size} is non-@code{nil} (or with a prefix argument), it
tries to keep the size of the display area of the current frame fixed by
adjusting the number of lines and columns.

If the optional argument @var{frames} is @code{nil}, this applies the
font to the selected frame only.  If @var{frames} is non-@code{nil}, it
should be a list of frames to act upon, or @code{t} meaning all existing
graphical frames.
@end deffn

@cindex frame display area
@cindex display area of a frame
The @dfn{display area} of a frame is a rectangular area within the area
allotted to the frame by the window manager.  The display area neither
includes the title bar (@pxref{Frame Titles}) nor any other decorations
provided by the window manager (like an external border used for
resizing frames via mouse dragging).

   The actual height of the display area depends on the window-system
and toolkit in use.  With GTK+, the display area does not include any
tool bar or menu bar.  With the Motif or Lucid toolkits and with
Windows, the display area includes the tool bar but not the menu bar.
In a graphical version with no toolkit, it includes both the tool bar
and menu bar.  On a text terminal, the display area includes the menu
bar.

@defun frame-pixel-height &optional frame
@defunx frame-pixel-width &optional frame
これらの関数は、フレーム@var{frame}の高さや幅をピクセル単位で返す。
For a text terminal, the results are
in characters rather than pixels.
@end defun

@cindex frame text area
@cindex text area of a frame
   The @dfn{text area} of a frame is a concept implicitly used by all
functions that change a frame's height or width.  It is a rectangle
located within the display area.  Its size is obtained from that of the
display area by subtracting the sizes of any tool or menu bars that are
part of the display area, any internal borders, one vertical and one
horizontal scroll bar, and one left and one right fringe as specified
for this frame, see @ref{Layout Parameters}.

@defun frame-text-height &optional frame
@defunx frame-text-width &optional frame
These functions return the height and width of the text area of
@var{frame}, measured in pixels.  For a text terminal, the results are
in characters rather than pixels.

The value returned by @code{frame-text-height} differs from that
returned by @code{frame-pixel-height} by not including the heights of
any tool bar or menu bar, the height of one horizontal scroll bar and
the widths of the internal border.

The value returned by @code{frame-text-width} differs from that returned
by @code{frame-pixel-width} by not including the width of one vertical
scroll bar, the widths of one left and one right fringe and the widths
of the internal border.
@end defun

@defun frame-height &optional frame
@defunx frame-width &optional frame
この関数は、フレーム@var{frame}のテキスト領域の高さや幅を、
デフォルトフォントの高さや幅の単位で返す。
@var{frame}を指定しないと、選択されているフレームを使う。
These functions are plain shorthands for writing
@code{(frame-parameter frame 'height)} and @code{(frame-parameter frame
'width)}.

If the text area of @var{frame} measured in pixles is not a multiple of
its default font size, the values returned by this functions are rounded
down to the number of characters of the default font that fully fit into
the text area.
@end defun

@defopt frame-resize-pixelwise
If this option is @code{nil}, a frame's size is usually rounded to a
multiple of the current values of that frame's @code{frame-char-height}
and @code{frame-char-width}.  If this is non-@code{nil}, no rounding
occurs, hence frame sizes can increase/decrease by one pixel.

Setting this causes the next resize operation to pass the corresponding
size hints to the window manager.  This means that this variable should
be set only in a user's initial file; applications should never bind it
temporarily.

The precise meaning of a value of @code{nil} for this option depends
on the toolkit used.  Dragging the frame border with the mouse is usually
done character-wise.  Calling @code{set-frame-size} (see below)
with arguments that do not specify the frame size as an integer multiple
of its character size, however, may: be ignored, cause a
rounding (GTK+), or be accepted (Lucid, Motif, MS-Windows).

With some window managers you may have to set this to non-@code{nil} in
order to make a frame appear truly ``maximized'' or ``fullscreen''.
@end defopt

@defun set-frame-size frame width height pixelwise
この関数は、フレーム@var{frame}の大きさを文字単位で指定する。
@var{width}と@var{height}は、新たな幅と高さを指定する。

The optional argument @var{pixelwise} non-@code{nil} means to measure
the new width and height in units of pixels instead.  Note that if
@code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to
fully honor the request if it does not increase/decrease the frame size
to a multiple of its character size.
@end defun

@defun set-frame-height frame height &optional pretend pixelwise
この関数は、フレーム@var{frame}の高さを@var{height}行に変える。
それに合わせて@var{frame}内の既存のウィンドウの大きさは比例して変わる。

@var{pretend}が@code{nil}以外であると、
Emacsは@var{frame}の@var{height}だけを表示するが、
フレームの実際の高さは変更しない。
これは端末フレームでのみ有用である。
実際の端末より小さな高さを使うと、小さなスクリーンでの動作を再現したり、
スクリーン全体を使うと端末が誤動作するような場合に有用である。
フレームの『実際』の高さを指定してもつねにそうなるとは限らない。
端末フレーム上で正しくカーソルを位置決めするには、
実サイズを知る必要がある場合もあるからである。

The optional fourth argument @var{pixelwise} non-@code{nil} means that
@var{frame} should be @var{height} pixels high.  Note that if
@code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to
fully honor the request if it does not increase/decrease the frame
height to a multiple of its character height.
@end defun

@defun set-frame-width frame width &optional pretend pixelwise
この関数は、フレーム@var{frame}の幅を設定する。
引数@var{pretend}は@code{set-frame-height}と同じ意味を持つ。

The optional fourth argument @var{pixelwise} non-@code{nil} means that
@var{frame} should be @var{width} pixels wide.  Note that if
@code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to
fully honor the request if it does not increase/decrease the frame width
to a multiple of its character width.
@end defun

None of these three functions will make a frame smaller than needed to
display all of its windows together with their scroll bars, fringes,
margins, dividers, mode and header lines.  This contrasts with requests
by the window manager triggered, for example, by dragging the external
border of a frame with the mouse.  Such requests are always honored by
clipping, if necessary, portions that cannot be displayed at the right,
bottom corner of the frame.

   By default, Emacs tries to keep the number of lines and columns of a
frame's text area unaltered when, for example, adding or removing a menu
bar, changing the default font or setting the width of the frame's
scroll bars.  This means, however, that in such case Emacs must ask the
window manager to resize the display area of the frame in order to
accommodate the size change.  Note that wrapping a menu or tool bar
usually does not resize the frame's display area, hence this will alter
the number of displayed lines.

   Occasionally, such implied resizing of the display area may be
unwanted, for example, when the frame is maximized or made fullscreen
where it's turned off by default.  In other cases you can disable
implied resizing with the following option:

@defopt frame-inhibit-implied-resize
If this option is @code{nil}, changing font, menu bar, tool bar,
internal borders, fringes or scroll bars of a specific frame may
implicitly resize the frame's display area in order to preserve the
number of columns or lines the frame displays.  If this option is
non-@code{nil}, no implied resizing is done.

The value of this option can be also be a list of frame parameters.  In
that case, implied resizing is inhibited when changing a parameter that
appears in this list.  The frame parameters currently handled by this
option are: @code{font}, @code{font-backend},
@code{internal-border-width}, @code{menu-bar-lines} and
@code{tool-bar-lines}.

Changing any of the @code{scroll-bar-width}, @code{scroll-bar-height},
@code{vertical-scroll-bars}, @code{horizontal-scroll-bars},
@code{left-fringe} and @code{right-fringe} frame parameters is handled
as if the frame contained just one live window.  This means, for
example, that removing vertical scroll bars on a frame containing
several side by side windows will shrink the frame width by the width of
one scroll bar provided this option is @code{nil} and keep it unchanged
if this option is either @code{t} or a list containing
@code{vertical-scroll-bars}.

The default value is @code{'(tool-bar-lines)} for Lucid, Motif and
Windows (which means that adding/removing a tool bar there does not
change the frame height), @code{nil} on all other window systems
including GTK+ (which means that changing any of the parameters listed
above may change the size of the frame), and @code{t} otherwise (which
means the frame size never changes implicitly when there's no window
system support).

Note that when a frame is not large enough to accommodate a change of
any of the parameters listed above, Emacs may try to enlarge the frame
even if this option is non-@code{nil}.
@end defopt

@c FIXME?  Belongs more in Emacs manual than here?
@c But, e.g., fit-window-to-buffer is in this manual.
If you have a frame that displays only one window, you can fit that
frame to its buffer using the command @code{fit-frame-to-buffer}.

@deffn Command fit-frame-to-buffer &optional frame max-height min-height max-width min-width only
This command adjusts the size of @var{frame} to display the contents of
its buffer exactly.  @var{frame} can be any live frame and defaults to
the selected one.  Fitting is done only if @var{frame}'s root window is
live.  The arguments @var{max-height}, @var{min-height}, @var{max-width}
and @var{min-width} specify bounds on the new total size of
@var{frame}'s root window.  @var{min-height} and @var{min-width} default
to the values of @code{window-min-height} and @code{window-min-width}
respectively.

If the optional argument @var{only} is @code{vertically}, this function
may resize the frame vertically only.  If @var{only} is
@code{horizontally}, it may resize the frame horizontally only.
@end deffn

The behavior of @code{fit-frame-to-buffer} can be controlled with the
help of the two options listed next.

@defopt fit-frame-to-buffer-margins
This option can be used to specify margins around frames to be fit by
@code{fit-frame-to-buffer}.  Such margins can be useful to avoid, for
example, that such frames overlap the taskbar.

It specifies the numbers of pixels to be left free on the left, above,
the right, and below a frame that shall be fit.  The default specifies
@code{nil} for each which means to use no margins.  The value specified
here can be overridden for a specific frame by that frame's
@code{fit-frame-to-buffer-margins} parameter, if present.
@end defopt

@defopt fit-frame-to-buffer-sizes
This option specifies size boundaries for @code{fit-frame-to-buffer}.
It specifies the total maximum and minimum lines and maximum and minimum
columns of the root window of any frame that shall be fit to its buffer.
If any of these values is non-@code{nil}, it overrides the corresponding
argument of @code{fit-frame-to-buffer}.
@end defopt


@node Geometry
@subsection Geometry

  Here's how to examine the data in an X-style window geometry
specification:

@defun x-parse-geometry geom
@cindex ジオメトリ指定
関数@code{x-parse-geometry}は、Xウィンドウの標準のジオメトリ文字列を
@code{make-frame}の引数の一部に使えるように連想リストに変換する。

この連想リストは、@var{geom}で指定されているパラメータとその値を記述する。
各要素は@code{(@var{parameter} . @var{value})}の形である。
@var{parameter}の可能な値は、
@code{left}、@code{top}、@code{width}、@code{height}である。

大きさを表すパラメータでは、その値は整数であること。
位置を表すパラメータでは、右端や下端の位置を表す値もあるので、
@code{left}や@code{top}というパラメータ名は必ずしも正確ではない。
位置を表すパラメータの可能な@var{value}は、
前に説明（@pxref{Position Parameters}）したように、
整数、リスト@code{(+ @var{pos})}、またはリスト@code{(- @var{pos})}
となる。

例を示す。

@example
(x-parse-geometry "35x70+0-0")
     @result{} ((height . 70) (width . 35)
         (top - 0) (left . 0))
@end example
@end defun

@node Terminal Parameters
@section Terminal Parameters
@cindex terminal parameters

  Each terminal has a list of associated parameters.  These
@dfn{terminal parameters} are mostly a convenient way of storage for
terminal-local variables, but some terminal parameters have a special
meaning.

  This section describes functions to read and change the parameter values
of a terminal.  They all accept as their argument either a terminal or
a frame; the latter means use that frame's terminal.  An argument of
@code{nil} means the selected frame's terminal.

@defun terminal-parameters &optional terminal
This function returns an alist listing all the parameters of
@var{terminal} and their values.
@end defun

@defun terminal-parameter terminal parameter
This function returns the value of the parameter @var{parameter} (a
symbol) of @var{terminal}.  If @var{terminal} has no setting for
@var{parameter}, this function returns @code{nil}.
@end defun

@defun set-terminal-parameter terminal parameter value
This function sets the parameter @var{parm} of @var{terminal} to the
specified @var{value}, and returns the previous value of that
parameter.
@end defun

Here's a list of a few terminal parameters that have a special
meaning:

@table @code
@item background-mode
The classification of the terminal's background color, either
@code{light} or @code{dark}.
@item normal-erase-is-backspace
Value is either 1 or 0, depending on whether
@code{normal-erase-is-backspace-mode} is turned on or off on this
terminal.  @xref{DEL Does Not Delete,,, emacs, The Emacs Manual}.
@item terminal-initted
After the terminal is initialized, this is set to the
terminal-specific initialization function.
@item tty-mode-set-strings
When present, a list of strings containing escape sequences that Emacs
will output while configuring a tty for rendering.  Emacs emits these
strings only when configuring a terminal: if you want to enable a mode
on a terminal that is already active (for example, while in
@code{tty-setup-hook}), explicitly output the necessary escape
sequence using @code{send-string-to-terminal} in addition to adding
the sequence to @code{tty-mode-set-strings}.
@item tty-mode-reset-strings
When present, a list of strings that undo the effects of the strings
in @code{tty-mode-set-strings}.  Emacs emits these strings when
exiting, deleting a terminal, or suspending itself.
@end table

@node Frame Titles
@section フレームタイトル
@cindex frame title

各フレームにはパラメータ@code{name}があります。
これは、典型的にはウィンドウシステムがフレームの先頭に表示する
フレームタイトルのデフォルトにもなります。
フレーム属性@code{name}に設定することで明示的に名前を指定できます。

通常は名前を明示的に指定しないでしょうから、
変数@code{frame-title-format}に保持してある雛型から
Emacsが自動的にフレーム名を計算します。
Emacsは、フレームを再表示するたびに名前を再計算します。

@defvar frame-title-format
この変数は、読者がフレーム名を明示的に指定しなかったときの
フレーム向けの名前の計算方法を指定する。
変数の値は実際には、@code{mode-line-format}のようなモード行構成であるが、
@samp{%c}と@samp{%l}構成は無視される。
@xref{Mode Line
Data}。
@end defvar

@defvar icon-title-format
この変数は、フレームタイトルを明示的に指定しなかったときの
アイコンにしたフレーム向けの名前の計算方法を指定する。
これはアイコンそのものに現れる。
@end defvar

@defvar multiple-frames
この変数はEmacsが自動的に設定する。
（ミニバッファ専用のフレームや不可視フレームを数えずに）
複数個のフレームがあるとこの値が@code{t}である。
@code{frame-title-format}のデフォルト値では@code{multiple-frames}を使っており、
複数のフレームがあるときに限りフレームタイトルにバッファ名が入るようにする。

The value of this variable is not guaranteed to be accurate except
while processing @code{frame-title-format} or
@code{icon-title-format}.
@end defvar

@node Deleting Frames
@section フレームの削除
@cindex 削除、フレーム

フレームを明示的に@dfn{削除}（delete）しない限り、
フレームは見える可能性があります。
フレームを削除するとスクリーンに表示できなくなりますが、
それを参照するものがなくならない限りLispオブジェクトとしては存在し続けます。

@deffn Command delete-frame &optional frame force
@vindex delete-frame-functions
この関数はフレーム@var{frame}を削除する。
Unless @var{frame} is a
tooltip, it first runs the hook @code{delete-frame-functions} (each
function gets one argument, @var{frame}).
デフォルトでは、@var{frame}は選択されているフレームである。

A frame cannot be deleted if its minibuffer is used by other frames.
Normally, you cannot delete a frame if all other frames are invisible,
but if @var{force} is non-@code{nil}, then you are allowed to do so.
@end deffn

@defun frame-live-p frame
関数@code{frame-live-p}は、フレーム@var{frame}が削除されていなければ
@code{nil}以外を返す。
The possible non-@code{nil} return
values are like those of @code{framep}.  @xref{Frames}.
@end defun

ウィンドウを削除するコマンドを与えるウィンドウマネージャもあります。
それらは、ウィンドウを操作しているプログラムに特別なメッセージを
送ることで動作します。
Emacsがそのようなコマンドを受け取ると、
イベント@code{delete-frame}を生成します。
このイベントの普通の定義は、関数@code{delete-frame}を呼び出すコマンドです。
@xref{Misc Events}。

@node Finding All Frames
@section すべてのフレームを探す
@cindex frames, scanning all

@defun frame-list
この関数は、削除されていないすべてのフレームから成るリストを返す。
これは、バッファに対する@code{buffer-list}に相当する。
得られるリストは新たに作成したものであり、
このリストを変更してもEmacs内部にはなんの効果もない。
@end defun

@defun visible-frame-list
この関数は、現在可視のフレームだけのリストを返す。
@xref{Visibility of Frames}。
（選択されているフレームだけが実際に表示されている場合でも、
端末フレームはすべてつねに『可視』とみなす。）
@end defun

@defun next-frame &optional frame minibuf
この関数により、
任意の位置から始めてすべてのフレームを便利に巡回できる。
巡回順の中で@var{frame}の『つぎ』のフレームを返す。
@var{frame}を省略したり@code{nil}であると、
デフォルトでは選択されているフレームを使う。
(@pxref{Input
Focus})

第2引数@var{minibuf}は、対象とするフレームを指定する。

@table @asis
@item @code{nil}
ミニバッファ専用のフレームを除外する。
@item @code{visible}
すべての可視なフレームを対象にする。
@item 0
すべての可視なフレームやアイコンにしたフレームを対象にする。
@item ウィンドウ
ミニバッファとして特定のウィンドウを使っているフレームのみを対象にする。
@item その他
すべてのフレームを対象にする。
@end table
@end defun

@defun previous-frame &optional frame minibuf
@code{next-frame}と同様であるが、すべてのフレームを逆方向に巡回する。
@end defun

@ref{Cyclic Window Ordering}の@code{next-window}と@code{previous-window}も
参照してください。

@node Minibuffers and Frames
@section ミニバッファとフレーム

通常、各フレームにはそれ独自のミニバッファ用ウィンドウが底にあり、
フレームが選択されているときにはいつもそれが使われます。
フレームにミニバッファがあれば、@code{minibuffer-window}
（@pxref{Definition of
minibuffer-window}）でそれを得られます。

@cindex frame without a minibuffer
しかし、ミニバッファのないフレームを作ることもできます。
そのようなフレームでは、別のフレームのミニバッファ用ウィンドウを
使う必要があります。
そのようなフレームを作成するときには、
使用する（他のフレームの）ミニバッファを明示的に指定できます。
そうしないと、変数@code{default-minibuffer-frame}の値で指定される
フレームのミニバッファを使います。
その値は、ミニバッファを有したフレームである必要があります。

ミニバッファ専用のフレームを使うときは、
ミニバッファで入力するときにそのフレームが
自動的に手前にくるようにしたいでしょう。
そうしたい場合には、変数@code{minibuffer-auto-raise}に@code{t}に設定します。
@xref{Raising and Lowering}。

@defvar default-minibuffer-frame
この変数は、デフォルトで使うミニバッファ用ウィンドウのフレームを指定する。
この変数は現在の端末につねにローカルであり、
バッファローカルにはなりえない。
@xref{Multiple
Terminals}.
@end defvar

@node Input Focus
@section 入力フォーカス
@cindex 入力フォーカス
@c @cindex selected frame    Duplicates selected-frame, same for selected-window.

ある時点では、Emacsの1つのフレームが@dfn{選択されているフレーム}
（selected frame）です。
選択されているウィンドウは選択されているフレームの中につねにあります。

When Emacs displays its frames on several terminals (@pxref{Multiple
Terminals}), each terminal has its own selected frame.  But only one
of these is ``@emph{the} selected frame'': it's the frame that belongs
to the terminal from which the most recent input came.  That is, when
Emacs runs a command that came from a certain terminal, the selected
frame is the one of that terminal.  Since Emacs runs only a single
command at any given time, it needs to consider only one selected
frame at a time; this frame is what we call @dfn{the selected frame}
in this manual.  The display on which the selected frame is shown is
the @dfn{selected frame's display}.

@defun selected-frame
この関数は選択されているフレームを返す。
@end defun

マウスが入っているウィンドウにキーボード入力を振り向ける
ウィンドウシステムやウィンドウマネージャがあります。
ウィンドウに@dfn{フォーカスを置く}ために、
明示的にクリックしたりコマンドを必要とするものもあります。
いずれであっても、Emacsはどのフレームにフォーカスがあるかを
自動的に追跡します。
To
explicitly switch to a different frame from a Lisp function, call
@code{select-frame-set-input-focus}.

Lispプログラムからは、関数@code{select-frame}を呼ぶことで、
『一時的に』フレームを切り替えることもできます。
これは、ウィンドウシステムのフォーカスは変えません。
というよりは、プログラムで指定するまで
ウィンドウシステムの制御を回避します。

テキスト端末を使っているときには、
１フレームのみが端末に表示できるため、
@code{select-frame}を呼び出した後、
次に行われる再描画は実際には新しく選択したフレームを表示します。
This frame
remains selected until a subsequent call to @code{select-frame}.
各テキスト端末上のフレームには番号が付いていて、
選択されているフレームの番号がモード行内のバッファ名のまえに現れます
（@pxref{Mode Line Variables}）。

@defun select-frame-set-input-focus frame &optional norecord
This function selects @var{frame}, raises it (should it happen to be
obscured by other frames) and tries to give it the X server's focus.
On a text terminal, the next redisplay displays the new frame on the
entire terminal screen.  The optional argument @var{norecord} has the
same meaning as for @code{select-frame} (see below).  The return value
of this function is not significant.
@end defun

@deffn Command select-frame frame &optional norecord
この関数はフレーム@var{frame}を選択し、
Xサーバーのフォーカスを一時的に無視する。
@var{frame}を選択している状態は、
ユーザーが別のフレームを選択する動作を行うか
再度この関数が呼ばれるまで持続する。

The specified @var{frame} becomes the selected frame, and its terminal
becomes the selected terminal.  This function then calls
@code{select-window} as a subroutine, passing the window selected
within @var{frame} as its first argument and @var{norecord} as its
second argument (hence, if @var{norecord} is non-@code{nil}, this
avoids changing the order of recently selected windows nor the buffer
list).  @xref{Selecting Windows}.

This function returns @var{frame}, or @code{nil} if @var{frame} has
been deleted.

In general, you should never use @code{select-frame} in a way that
could switch to a different terminal without switching back when
you're done.
@end deffn

サーバーやウィンドウマネジャーの要請にしたがって
フレームを選択するようにして、
Emacsはウィンドウシステムと協調します。
必要なときには@dfn{フォーカス} (focus) イベントと呼ばれる特別な入力イベントを
生成することでこのようにします。
コマンドループは@code{handle-switch-frame}を呼び出すことで
イベントフォーカスを処理します。
@xref{Focus Events}。

@deffn Command handle-switch-frame frame
この関数は、フレーム@var{frame}を選択することでフォーカスイベントを
処理する。

フォーカスイベントは、通常、このコマンドを起動することで処理される。
それ以外の理由ではこれを呼び出さないこと。
@end deffn

@defun redirect-frame-focus frame &optional focus-frame
この関数は、フォーカスを@var{frame}から@var{focus-frame}へ振り向ける。
つまり、以降の打鍵やイベントは、@var{frame}ではなく、
@var{focus-frame}が受け取ることになる。
そのようなイベントのあとでは、
@code{last-event-frame}の値は@var{focus-frame}になる。
また、フレーム@var{frame}を指定したフレーム切替イベントは、
代わりに@var{focus-frame}を選ぶ。

@var{focus-frame}が省略されたり@code{nil}であると、@var{frame}での振り向けを取り消し、
そのイベントをふたたび受けるようになる。

フォーカスの振り向けの用途の1つは、
ミニバッファを持たないフレームのためである。
これらのフレームでは、別のフレームのミニバッファを使う。
別のフレームのミニバッファを活性にすると、
フォーカスを当該フレームへ振り向ける。
これにより、ミニバッファを活性にしたフレームにマウスが入っていても、
ミニバッファのフレームにフォーカスを置ける。

フレームを選択してもフォーカスの振り向けを変更する。
フレーム@code{foo}を選択しているときにフレーム@code{bar}を選択すると、
@code{foo}への振り向けを@code{bar}へ振り向けるように変更する。
これにより、@code{select-window}を使ってユーザーが
別のフレームへ切り替えても、フォーカスの振り向けが正しく動作する。

これは、フォーカスを自分自身へ振り向けているフレームは、
フォーカスを振り向けていないフレームとは異なる扱いを受けることを意味する。
@code{select-frame}は前者に影響するが後者には影響しない。

@code{redirect-frame-focus}で変更するまで、振り向けは持続する。
@end defun

@defvar focus-in-hook
This is a normal hook run when an Emacs frame gains input focus.
@end defvar

@defvar focus-out-hook
This is a normal hook run when an Emacs frame loses input focus.
@end defvar

@defopt focus-follows-mouse
このオプションは、ユーザーがマウスを動かしたときに
ウィンドウマネージャがフォーカスを移動するかどうかをEmacsに伝える。
@code{nil}以外であるとフォーカスが移動することを意味する。
その場合、コマンド@code{other-frame}は、
新たに選択されたフレームに適合するような位置にマウスを移動する。
@end defopt

@node Visibility of Frames
@section フレームの可視性
@cindex 可視なフレーム
@cindex 不可視なフレーム
@cindex アイコンにしたフレーム
@cindex minimized frame
@cindex フレームの可視性

ウィンドウフレームは、@dfn{可視}、
@dfn{不可視}、@dfn{アイコン化}のいずれかです。
フレームが可視であると、その内容を見ることができます。
アイコン化されるとフレームの内容はスクリーンで見えませんが、
アイコンは見えます。
（幾つかのウィンドウマネージャは、この状態を
@dfn{アイコン化}よりは@dfn{最小化}として参照します。）
フレームが不可視であると、それはスクリーン上に見えず
アイコンでもありません。

端末フレームは選択されているものだけが表示されるので、
端末フレームでは可視性は意味がありません。

@defun frame-visible-p frame
この関数は、フレーム@var{frame}の可視性を返す。
その値は、@var{frame}が可視ならば@code{t}、
不可視ならば@code{nil}、アイコンになっていれば@code{icon}である。

On a text terminal, all frames are considered ``visible'' for the
purposes of this function, even though only one frame is displayed.
@xref{Raising and Lowering}.
@end defun

@deffn Command iconify-frame &optional frame
この関数は、フレーム@var{frame}をアイコンにする。
@var{frame}を省略すると、選択されているフレームをアイコンにする。
@end deffn

@deffn Command make-frame-visible &optional frame
この関数は、フレーム@var{frame}を可視にする。
@var{frame}を省略すると、選択されているフレームを可視にする。
This does not raise
the frame, but you can do that with @code{raise-frame} if you wish
(@pxref{Raising and Lowering}).
@end deffn

@deffn Command make-frame-invisible &optional frame force
この関数は、フレーム@var{frame}を不可視にする。
@var{frame}を省略すると、選択されているフレームを不可視にする。

Unless @var{force} is non-@code{nil}, this function refuses to make
@var{frame} invisible if all other frames are invisible..
@end deffn

フレームの可視性は、フレームパラメータとしても得られます。
フレームパラメータとして読んだり変更できます。
@xref{Management
Parameters}.
ユーザーは、ウィンドウマネージャを用いて
フレームをアイコンにしたりアイコンを開けます。
これは、Emacsが制御できるレベルよりしたで行われますが、
Emacsはそのような変更を追跡できるようにイベントを提供します。
@xref{Misc Events}。

@node Raising and Lowering
@section フレームを手前にしたり奥へ置く

@cindex raising a frame
@cindex lowering a frame
ほとんどのウィンドウシステムでは、机のたとえを使います。
つまり、スクリーンの面に垂直な方向を概念的な3軸目と考えて、
ウィンドウは積み重なっていて、
もっとも手前からもっとも奥に順序がついています。
2つのウィンドウが重なり合っているところでは、
手前のものがそのしたのものを隠しています。
フレームは、関数@code{raise-frame}や@code{lower-frame}で
@dfn{手前へ移動}したり@dfn{奥へ移動}できます。

@deffn Command raise-frame &optional frame
この関数は、フレーム@var{frame}を手前に置く
（デフォルトは選択されているフレーム）。
If @var{frame} is invisible or iconified, this makes it visible.
@end deffn

@deffn Command lower-frame &optional frame
この関数は、フレーム@var{frame}を奥に置く
（デフォルトは選択されているフレーム）。
@end deffn

@defopt minibuffer-auto-raise
これが@code{nil}以外であると、ミニバッファが活性になると
ミニバッファ用ウィンドウがあるフレームを手前に置く。
@end defopt

  On window systems, you can also enable auto-raising (on frame
selection) or auto-lowering (on frame deselection) using frame
parameters.  @xref{Management Parameters}.

@cindex top frame
  The concept of raising and lowering frames also applies to text
terminal frames.  On each text terminal, only the top frame is
displayed at any one time.

@defun tty-top-frame terminal
This function returns the top frame on @var{terminal}.  @var{terminal}
should be a terminal object, a frame (meaning that frame's terminal),
or @code{nil} (meaning the selected frame's terminal).  If it does not
refer to a text terminal, the return value is @code{nil}.
@end defun

@node Frame Configurations
@section フレーム構成
@cindex フレーム構成

@dfn{フレーム構成}（frame configuration）は、
現在のフレームの配置、それらのすべての属性、それぞれのウィンドウ構成を
記録したものです。
（@xref{Window Configurations}。）

@defun current-frame-configuration
この関数は、現在のフレームの配置とそれらの内容を記述した
フレーム構成のリストを返す。
@end defun

@defun set-frame-configuration configuration &optional nodelete
この関数は、@var{configuration}で記述されたフレームの状態に復元する。
However, this function does not restore deleted
frames.

Ordinarily, this function deletes all existing frames not listed in
@var{configuration}.  But if @var{nodelete} is non-@code{nil}, the
unwanted frames are iconified instead.
@end defun

@node Mouse Tracking
@section マウスの追跡
@cindex マウスの追跡
@c @cindex tracking the mouse   Duplicates track-mouse

マウスを@dfn{追跡}（track）できると有用なことがあります。
つまり、マウスがどこにあるかを表す指示子を表示して
マウスの移動に従って指示子を動かすのです。
効率よくマウスを追跡するには、マウスが実際に移動するまで待つ手段が必要です。

マウスを追跡する便利な方法は、マウスの移動を表すイベントを待つことです。
そうすれば、そのようなイベントを待てばマウスの移動を待てます。
さらに、発生しうるそれ以外の種類のイベントを扱うのも簡単です。
普通はマウスを永遠に追跡し続けたいのではなく
ボタンを離すなどの別のイベントを待ちたいのでしょうから、
これは有用です。

@defspec track-mouse body@dots{}
このスペシャルフォームは、マウスモーションイベントを生成するようにして
@var{body}を実行する。
典型的には@var{body}では@code{read-event}を使って
モーションイベントを読み、それに従って表示を変更する。
マウスモーションイベントの形式については、
@xref{Motion
Events}。

@code{track-mouse}の値は@var{body}の最後のフォームの値である。
@var{body}は、ボタンを離したことを表すイベントや
追跡を終えるべきイベントに出会うと戻るように設計すること。
@end defspec

マウスの移動を追跡する普通の目的は、
現在の位置でボタンを押したり離すとなにが起こるかを
スクリーン上に示すことです。

多くの場面では、テキスト属性@code{mouse-face}（@pxref{Special Properties}）
を使えば、マウスを追跡する必要はなくなります。
これはとても低いレベルで動作し、
Lispレベルでマウスを追跡するより滑らかに動作します。

@ignore
@c These are not implemented yet.

These functions change the screen appearance instantaneously.  The
effect is transient, only until the next ordinary Emacs redisplay.  That
is OK for mouse tracking, since it doesn't make sense for mouse tracking
to change the text, and the body of @code{track-mouse} normally reads
the events itself and does not do redisplay.

@defun x-contour-region window beg end
This function draws lines to make a box around the text from @var{beg}
to @var{end}, in window @var{window}.
@end defun

@defun x-uncontour-region window beg end
This function erases the lines that would make a box around the text
from @var{beg} to @var{end}, in window @var{window}.  Use it to remove
a contour that you previously made by calling @code{x-contour-region}.
@end defun

@defun x-draw-rectangle frame left top right bottom
This function draws a hollow rectangle on frame @var{frame} with the
specified edge coordinates, all measured in pixels from the inside top
left corner.  It uses the cursor color, the one used for indicating the
location of point.
@end defun

@defun x-erase-rectangle frame left top right bottom
This function erases a hollow rectangle on frame @var{frame} with the
specified edge coordinates, all measured in pixels from the inside top
left corner.  Erasure means redrawing the text and background that
normally belong in the specified rectangle.
@end defun
@end ignore

@node Mouse Position
@section マウスの位置
@cindex マウスの位置
@cindex 位置、マウス

関数@code{mouse-position}と@code{set-mouse-position}で、
マウスの現在位置を参照できます。

@defun mouse-position
この関数は、マウスの位置を表すものを返す。
その値は@code{(@var{frame} @var{x} . @var{y})}の形であり、
@var{x}と@var{y}はフレーム@var{frame}の内側の左上隅を基準にした
文字数で数えた位置を表す整数である。
@end defun

@defvar mouse-position-function
If non-@code{nil}, the value of this variable is a function for
@code{mouse-position} to call.  @code{mouse-position} calls this
function just before returning, with its normal return value as the
sole argument, and it returns whatever this function returns to it.

This abnormal hook exists for the benefit of packages like
@file{xt-mouse.el} that need to do mouse handling at the Lisp level.
@end defvar

@defun set-mouse-position frame x y
この関数は、フレーム@var{frame}内で@var{x}と@var{y}の位置に@dfn{マウスを移動}する。
引数@var{x}と@var{y}は整数であり、
フレーム@var{frame}の内側の左上隅を基準にした文字数で数えた位置である。
@var{frame}が不可視であると、この関数はなにもしない。
戻り値には意味はない。
@end defun

@defun mouse-pixel-position
この関数は@code{mouse-position}に似ているが、
文字単位ではなくピクセル単位で座標を返す。
@end defun

@defun set-mouse-pixel-position frame x y
この関数は@code{set-mouse-position}のようにマウスを移動するが、
@var{x}と@var{y}は文字単位でなくピクセル単位である。
これらの座標はフレームの内側にある必要はない。

@var{frame}が不可視であると、この関数はなにもしない。
戻り値には意味はない。
@end defun

@defun frame-pointer-visible-p &optional frame
This predicate function returns non-@code{nil} if the mouse pointer
displayed on @var{frame} is visible; otherwise it returns @code{nil}.
@var{frame} omitted or @code{nil} means the selected frame.  This is
useful when @code{make-pointer-invisible} is set to @code{t}: it
allows to know if the pointer has been hidden.
@xref{Mouse Avoidance,,,emacs, The Emacs Manual}.
@end defun

@need 3000

@node Pop-Up Menus
@section ポップアップメニュー
@cindex menus, popup

ウィンドウシステムを使っているときには、
ユーザーがマウスで選択できるように
Lispプログラムからメニューをポップアップできます。
On a text terminal, if the mouse is not
available, the user can choose an alternative using the keyboard
motion keys---@kbd{C-n}, @kbd{C-p}, or up- and down-arrow keys.

@defun x-popup-menu position menu
この関数はポップアップメニューを表示し、
ユーザーが行った選択を表す指示子を返す。

引数@var{position}は、スクリーンのどこにメニューを置くかを指定する。
それはマウスのボタンイベント（ユーザーがボタンを押した場所にメニューを置く）か
つぎの形のリストでもよい。

@example
((@var{xoffset} @var{yoffset}) @var{window})
@end example

@noindent
ここで、@var{xoffset}と@var{yoffset}は
@var{window}の左上隅から測ったピクセル単位の座標である。
@var{window}
may be a window or a frame.

@var{position}が@code{t}であるとマウスの現在位置を使うことを意味する。
@var{position}が@code{nil}であると、
メニューを実際には表示せずに、
@var{menu}に指定してあるキーマップに等価なキーバインディングを
あらかじめ計算することを意味する。

引数@var{menu}は、メニューに表示するものを指定する。
それはキーマップかキーマップのリストである（@pxref{Menu Keymaps}）。
In this case, the
return value is the list of events corresponding to the user's choice.
This list has more than one element if the choice occurred in a
submenu.  (Note that @code{x-popup-menu} does not actually execute the
command bound to that sequence of events.)  On text terminals and
toolkits that support menu titles, the title is taken from the prompt
string of @var{menu} if @var{menu} is a keymap, or from the prompt
string of the first keymap in @var{menu} if it is a list of keymaps
(@pxref{Defining Menus}).

あるいは、@var{menu}はつぎの形でもよい。

@example
(@var{title} @var{pane1} @var{pane2}...)
@end example

@noindent
ここで、各ペインはつぎの形のリストである。

@example
(@var{title} @var{item1} @var{item2}...)
@end example

各@var{item}は@code{(@var{line} . @var{value})},というconsセルであり、
セルの@var{line}は文字列、@var{value}は
対応する@var{line}が選ばれたときに返される値であること。
Unlike in a menu keymap, a @code{nil}
@var{value} does not make the menu item non-selectable.
Alternatively, each @var{item} can be a string rather than a cons
cell; this makes a non-selectable menu item.

If the user gets rid of the menu without making a valid choice, for
instance by clicking the mouse away from a valid choice or by typing
@kbd{C-g}, then this normally results in a quit and
@code{x-popup-menu} does not return.  But if @var{position} is a mouse
button event (indicating that the user invoked the menu with the
mouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}.
@end defun

@strong{使用上の注意：}
メニューキーマップで定義したプレフィックスキーでできることには、
メニューを表示するために@code{x-popup-menu}を使ってはいけない。
メニューキーマップを使ってメニューを実装すると、
@kbd{C-h c}や@kbd{C-h a}で当該メニューの個々の項目を見ることができ、
それらに対するヘルプを提供できる。
@code{x-popup-menu}を呼び出すコマンドを定義してメニューを実装すると、
ヘルプ機能には当該コマンドの内側でなにがなされるかわからないので、
メニューの項目に対するヘルプを提供できない。

マウスの移動でサブメニューを切り替えられるメニューバーの機構では、
@code{x-popup-menu}を呼び出すコマンドの定義を調べられません。
したがって、@code{x-popup-menu}を使ってサブメニューを実装すると、
それらはメニューバーに適応した動作をできません。
このために、メニューバーのすべてのサブメニューは、
親メニュー内のメニューキーマップとして実装してあり、
@code{x-popup-menu}は使っていません。
@xref{Menu Bar}。

メニューバーに内容が変化するサブメニューを使いたいときでも、
メニューキーマップを使って実装するべきです。
内容を変えるには、必要に応じてメニューキーの内容を更新するために
@code{menu-bar-update-hook}にフック関数を追加します。

@node Dialog Boxes
@section 対話ボックス
@cindex 対話ボックス

対話ボックスはポップアップメニューの変形です。
少々異なって見えますが、フレームの中央につねに現れ、
たった1つのレベルで1つのペインです。
対話ボックスの主な用途は、
ユーザーが『yes』、『no』、および他の少数の選択肢で答えるような
問い合わせを行うためです。
関数@code{y-or-n-p}と@code{yes-or-no-p}は、
マウスクリックで起動されたコマンドから呼ばれると
キーボードではなく対話ボックスを使います。

@defun x-popup-dialog position contents &optional header
この関数は、対話ボックスを表示し、
ユーザーが選んだ選択肢を表す指示子を返す。
引数@var{contents}は表示する選択肢を指定し、つぎの形である。

@example
(@var{title} (@var{string} . @var{value})@dots{})
@end example

@noindent
これは、@code{x-popup-menu}に対して単一のペインを指定するリストに似ている。

戻り値は、選ばれた選択肢の@var{value}である。

@code{x-popup-menu}においては、
リストの要素は、@code{(@var{string} . @var{value})}の形の
コンスセルのかわりに単に文字列でもよい。
そうすると、対話ボックスでは選択できなくなる。

リストに@code{nil}が現れると、それは左側の項目と右側の項目を区切る。
@code{nil}のまえの項目は左側に現れ、
@code{nil}に続く項目は右側に現れる。
リストに@code{nil}を含めなければ、項目のほぼ半分がそれぞれの側に現れる。

対話ボックスはフレームの中央につねに現れ、
引数@var{position}はそのフレームを指定する。
可能な値は@code{x-popup-menu}と同様であるが、
正確な座標は関係なくフレームだけが意味を持つ。

If @var{header} is non-@code{nil}, the frame title for the box is
@samp{Information}, otherwise it is @samp{Question}.  The former is used
for @code{message-box} (@pxref{message-box}).  (On text terminals, the
box title is not displayed.)

場合によっては、Emacsは本当の対話ボックスを表示できない。
そのときにはフレームの中央にポップアップメニューで同じ項目を表示する。

If the user gets rid of the dialog box without making a valid choice,
for instance using the window manager, then this produces a quit and
@code{x-popup-dialog} does not return.
@end defun

@node Pointer Shape
@section ポインタの形状
@cindex ポインタの形状
@cindex マウスポインタの形状

これらの変数は、Xウィンドウシステムを使っているときに
さまざまな場面で使用するマウスポインタの形状を指定します。
  You can specify the mouse pointer style for particular text or
images using the @code{pointer} text property, and for images with the
@code{:pointer} and @code{:map} image properties.  The values you can
use in these properties are @code{text} (or @code{nil}), @code{arrow},
@code{hand}, @code{vdrag}, @code{hdrag}, @code{modeline}, and
@code{hourglass}.  @code{text} stands for the usual mouse pointer
style used over text.

  Over void parts of the window (parts that do not correspond to any
of the buffer contents), the mouse pointer usually uses the
@code{arrow} style, but you can specify a different style (one of
those above) by setting @code{void-text-area-pointer}.

@defopt void-text-area-pointer
This variable specifies the mouse pointer style for void text areas.
These include the areas after the end of a line or below the last line
in the buffer.  The default is to use the @code{arrow} (non-text)
pointer style.
@end defopt

  When using X, you can specify what the @code{text} pointer style
really looks like by setting the variable @code{x-pointer-shape}.

@defvar x-pointer-shape
この変数は、Emacsのフレーム内で@code{text}ポインタスタイルに普通に使うポインタ形状を指定する。
@end defvar

@defvar x-sensitive-text-pointer-shape
This variable specifies the pointer shape to use when the mouse
is over mouse-sensitive text.
この変数は、マウスに反応するテキスト上にマウスがあるときに
使用するポインタ形状を指定する。
@end defvar

これらの変数は、新たに作成したフレームに影響します。
既存のフレームには通常は影響しません。
しかし、フレームのマウスの表示色を設定すると、
これら２変数の現在値に基づいてポインタ形状も更新します。
@xref{Font and Color Parameters}。

これらのポインタ形状の指定に使える値は、
ファイル@file{lisp/term/x-win.el}で定義してあります。
それらの一覧を見るには
@kbd{M-x apropos @key{RET} x-pointer @key{RET}}を使います。

@node Window System Selections
@section ウィンドウシステムのセレクション
@cindex セレクション（Xウィンドウシステム）
@cindex clipboard
@cindex primary selection
@cindex secondary selection

Xサーバーは、アプリケーションプログラムのあいだでデータを
転送するための@dfn{セレクション}（selection）の集まりを記録します。
X defines an arbitrary
number of @dfn{selection types}, each of which can store its own data;
however, only three are commonly used: the @dfn{clipboard},
@dfn{primary selection}, and @dfn{secondary selection}.  @xref{Cut and
Paste,, Cut and Paste, emacs, The GNU Emacs Manual}, for Emacs
commands that make use of these selections.  This section documents
the low-level functions for reading and setting X selections.

@deffn Command x-set-selection type data
この関数は、Xサーバーに『セレクション』を設定する。
これは2つの引数、セレクション型@var{type}と
それに割り当てる値@var{data}を取る。

@var{type}はシンボルであり、
その値は通常、@code{PRIMARY}か@code{SECONDARY}か@code{CLIPBOARD}である。
これらのシンボルは、Xウィンドウシステムの慣習に従って
大文字の名前である。
@var{type}が@code{nil}ならば、デフォルトは@code{PRIMARY}として扱われる。

@var{data}が@code{nil}ならば、当該セレクションを削除することを意味する。
さもなければ@var{data}は、文字列、シンボル、
整数（あるいは2つの数のコンスセルかリスト）、
オーバレイ、同じバッファを指す2つのマーカのコンスセルのいずれかである。
オーバレイやマーカの対は、
オーバレイのテキストやマーカのあいだのテキストを表す。
引数@var{data}は、ベクトルではない正しいセレクション値のベクトルでもよい。

This function returns @var{data}.
@end deffn

@defun x-get-selection &optional type data-type
この関数は、Emacsや他のXクライアントが設定したセレクションを参照する。
これは2つの引数、@var{type}と@var{data-type}を取る。
セレクション型@var{type}のデフォルトは@code{PRIMARY}である。

引数@var{data-type}は、他のXクライアントから得た生データを
Lispデータに変換するために使用するデータ変換の書式を指定する。
意味のある値は、@code{TEXT}、@code{STRING}、@code{UTF8_STRING}、
@code{TARGETS}、@code{LENGTH}、@code{DELETE}、@code{FILE_NAME}、
@code{CHARACTER_POSITION}、@code{NAME}、@code{LINE_NUMBER}、@code{COLUMN_NUMBER}、
@code{OWNER_OS}、@code{HOST_NAME}、@code{USER}、@code{CLASS}、
@code{ATOM}、@code{INTEGER}である。
（これらのシンボルは、Xウィンドウシステムの慣習に従って
大文字の名前である。）
@var{data-type}のデフォルトは@code{STRING}である。
@end defun

@defopt selection-coding-system
この変数は、セレクションまたはクリップボードを
読み書きするときに使うコーディングシステムを指定する。
@xref{Coding Systems}。
The default is @code{compound-text-with-extensions}, which
converts to the text representation that X11 normally uses.
@end defopt

@cindex clipboard support (for MS-Windows)
When Emacs runs on MS-Windows, it does not implement X selections in
general, but it does support the clipboard.  @code{x-get-selection}
and @code{x-set-selection} on MS-Windows support the text data type
only; if the clipboard holds other types of data, Emacs treats the
clipboard as empty.

@node Drag and Drop
@section Drag and Drop
@cindex drag and drop

@vindex x-dnd-test-function
@vindex x-dnd-known-types
  When a user drags something from another application over Emacs, that other
application expects Emacs to tell it if Emacs can handle the data that is
dragged.  The variable @code{x-dnd-test-function} is used by Emacs to determine
what to reply.  The default value is @code{x-dnd-default-test-function}
which accepts drops if the type of the data to be dropped is present in
@code{x-dnd-known-types}.  You can customize @code{x-dnd-test-function} and/or
@code{x-dnd-known-types} if you want Emacs to accept or reject drops based
on some other criteria.

@vindex x-dnd-types-alist
  If you want to change the way Emacs handles drop of different types
or add a new type, customize @code{x-dnd-types-alist}.  This requires
detailed knowledge of what types other applications use for drag and
drop.

@vindex dnd-protocol-alist
  When an URL is dropped on Emacs it may be a file, but it may also be
another URL type (ftp, http, etc.).  Emacs first checks
@code{dnd-protocol-alist} to determine what to do with the URL@.  If
there is no match there and if @code{browse-url-browser-function} is
an alist, Emacs looks for a match there.  If no match is found the
text for the URL is inserted.  If you want to alter Emacs behavior,
you can customize these variables.

@node Color Names
@section 表示色名

@cindex color names
@cindex specify color
@cindex numerical RGB color specification
  A color name is text (usually in a string) that specifies a color.
Symbolic names such as @samp{black}, @samp{white}, @samp{red}, etc.,
are allowed; use @kbd{M-x list-colors-display} to see a list of
defined names.  You can also specify colors numerically in forms such
as @samp{#@var{rgb}} and @samp{RGB:@var{r}/@var{g}/@var{b}}, where
@var{r} specifies the red level, @var{g} specifies the green level,
and @var{b} specifies the blue level.  You can use either one, two,
three, or four hex digits for @var{r}; then you must use the same
number of hex digits for all @var{g} and @var{b} as well, making
either 3, 6, 9 or 12 hex digits in all.  (See the documentation of the
X Window System for more details about numerical RGB specification of
colors.)

  These functions provide a way to determine which color names are
valid, and what they look like.  In some cases, the value depends on the
@dfn{selected frame}, as described below; see @ref{Input Focus}, for the
meaning of the term ``selected frame''.

  To read user input of color names with completion, use
@code{read-color} (@pxref{High-Level Completion, read-color}).

@defun color-defined-p color &optional frame
この関数は、表示色名が意味のあるものかどうかを報告する。
意味があれば@code{t}を返し、さもなければ@code{nil}を返す。
引数@var{frame}は、どのフレームで調べるかを指定する。
@var{frame}を省略したり@code{nil}であると、選択されているフレームを使う。

この関数では、読者が使用しているディスプレイで
当該表示色を実際に表示できるかどうかはわからない。
Xサーバでは、どんな種類のディスプレイでも定義されていればどんな表示色でも
問い合わせることができ、なんらかの結果を得られる。
読者のディスプレイで特定の表示色が使えるかどうかを
決定するには、@code{color-supported-p}関数（後述）を用いる。

@findex x-color-defined-p
This function used to be called @code{x-color-defined-p},
and that name is still supported as an alias.
@end defun

@defun defined-colors &optional frame
This function returns a list of the color names that are defined
and supported on frame @var{frame} (default, the selected frame).
If @var{frame} does not support colors, the value is @code{nil}.

@findex x-defined-colors
This function used to be called @code{x-defined-colors},
and that name is still supported as an alias.
@end defun

@defun color-supported-p color &optional frame background-p
This returns @code{t} if @var{frame} can really display the color
@var{color} (or at least something close to it).  If @var{frame} is
omitted or @code{nil}, the question applies to the selected frame.

Some terminals support a different set of colors for foreground and
background.  If @var{background-p} is non-@code{nil}, that means you are
asking whether @var{color} can be used as a background; otherwise you
are asking whether it can be used as a foreground.

The argument @var{color} must be a valid color name.
@end defun

@defun color-gray-p color &optional frame
This returns @code{t} if @var{color} is a shade of gray, as defined on
@var{frame}'s display.  If @var{frame} is omitted or @code{nil}, the
question applies to the selected frame.  If @var{color} is not a valid
color name, this function returns @code{nil}.
@end defun

@defun color-values color &optional frame
@cindex rgb value
この関数は、表示色@var{color}が理想的には@var{frame}でどのように見えるかを記述した値を返す。
@var{color}が定義されていれば、その値は、赤の分量、緑の分量、青の分量を表す
3つの整数のリストである。
各整数の範囲は原理的には0から65535であるが、
幾つかのディスプレイはこの範囲を完全に扱えないようである。
This three-element list is called the @dfn{rgb values} of the
color.

If @var{color} is not defined, the value is @code{nil}.

@example
(color-values "black")
     @result{} (0 0 0)
(color-values "white")
     @result{} (65280 65280 65280)
(color-values "red")
     @result{} (65280 0 0)
(color-values "pink")
     @result{} (65280 49152 51968)
(color-values "hungry")
     @result{} nil
@end example

フレーム@var{frame}のディスプレイに対する表示色の値を返す。
@var{frame}を省略したり@code{nil}であると、
選択されているフレームのディスプレイに対する値を返す。
If the frame cannot display colors, the
value is @code{nil}.

@findex x-color-values
This function used to be called @code{x-color-values},
and that name is still supported as an alias.
@end defun

@node Text Terminal Colors
@section Text Terminal Colors
@cindex colors on text terminals

  Text terminals usually support only a small number of colors, and
the computer uses small integers to select colors on the terminal.
This means that the computer cannot reliably tell what the selected
color looks like; instead, you have to inform your application which
small integers correspond to which colors.  However, Emacs does know
the standard set of colors and will try to use them automatically.

  The functions described in this section control how terminal colors
are used by Emacs.

  Several of these functions use or return @dfn{rgb values}, described
in @ref{Color Names}.

  These functions accept a display (either a frame or the name of a
terminal) as an optional argument.  We hope in the future to make
Emacs support different colors on different text terminals; then this
argument will specify which terminal to operate on (the default being
the selected frame's terminal; @pxref{Input Focus}).  At present,
though, the @var{frame} argument has no effect.

@defun tty-color-define name number &optional rgb frame
This function associates the color name @var{name} with
color number @var{number} on the terminal.

The optional argument @var{rgb}, if specified, is an rgb value, a list
of three numbers that specify what the color actually looks like.
If you do not specify @var{rgb}, then this color cannot be used by
@code{tty-color-approximate} to approximate other colors, because
Emacs will not know what it looks like.
@end defun

@defun tty-color-clear &optional frame
This function clears the table of defined colors for a text terminal.
@end defun

@defun tty-color-alist &optional frame
This function returns an alist recording the known colors supported by
a text terminal.

Each element has the form @code{(@var{name} @var{number} . @var{rgb})}
or @code{(@var{name} @var{number})}.  Here, @var{name} is the color
name, @var{number} is the number used to specify it to the terminal.
If present, @var{rgb} is a list of three color values (for red, green,
and blue) that says what the color actually looks like.
@end defun

@defun tty-color-approximate rgb &optional frame
This function finds the closest color, among the known colors
supported for @var{display}, to that described by the rgb value
@var{rgb} (a list of color values).  The return value is an element of
@code{tty-color-alist}.
@end defun

@defun tty-color-translate color &optional frame
This function finds the closest color to @var{color} among the known
colors supported for @var{display} and returns its index (an integer).
If the name @var{color} is not defined, the value is @code{nil}.
@end defun

@node Resources
@section Xリソース

This section describes some of the functions and variables for
querying and using X resources, or their equivalent on your operating
system.  @xref{X Resources,, X Resources, emacs, The GNU Emacs
Manual}, for more information about X resources.

@defun x-get-resource attribute class &optional component subclass
関数@code{x-get-resource}は、
Xウィンドウのデフォルトのデータベースからリソースの値を取り出す。

リソースは、@dfn{key}と@dfn{class}の組み合わせで添字付けされる。
この関数は@samp{@var{instance}.@var{attribute}}の形
（@var{instance}はEmacsを起動した名前）のキーと
クラスとして@samp{Emacs.@var{class}}を使って探索する。

省略可能な引数@var{component}と@var{subclass}は、それぞれ、
キーとクラスに追加される。
2つを指定するかまったく指定しないこと。
これらを指定すると、
キーは@samp{@var{instance}.@var{component}.@var{attribute}}であり、
クラスは@samp{Emacs.@var{class}.@var{subclass}}である。
@end defun

@defvar x-resource-class
この変数は、@code{x-get-resource}が探すアプリケーション名を指定する。
デフォルト値は@code{"Emacs"}である。
@code{x-get-resource}を呼び出す周りでこの変数に別の文字列を束縛すれば、
『Emacs』以外のアプリケーション名でXリソースを探せる。
@end defvar

@defvar x-resource-name
This variable specifies the instance name that @code{x-get-resource}
should look up.  The default value is the name Emacs was invoked with,
or the value specified with the @samp{-name} or @samp{-rn} switches.
@end defvar

To illustrate some of the above, suppose that you have the line:

@example
xterm.vt100.background: yellow
@end example

@noindent
in your X resources file (whose name is usually @file{~/.Xdefaults}
or @file{~/.Xresources}).  Then:

@example
@group
(let ((x-resource-class "XTerm") (x-resource-name "xterm"))
  (x-get-resource "vt100.background" "VT100.Background"))
     @result{} "yellow"
@end group
@group
(let ((x-resource-class "XTerm") (x-resource-name "xterm"))
  (x-get-resource "background" "VT100" "vt100" "Background"))
     @result{} "yellow"
@end group
@end example

@defvar inhibit-x-resources
If this variable is non-@code{nil}, Emacs does not look up X
resources, and X resources do not have any effect when creating new
frames.
@end defvar

@node Display Feature Testing
@section Display Feature Testing
@cindex display feature testing

本節では、Emacsが使っているXディスプレイの能力や製造元に関する情報を
得るために使う関数について述べます。
Lisp programs can use them to adapt their behavior
to what the display can do.  For example, a program that ordinarily uses
a popup menu could use the minibuffer if popup menus are not supported.

以下の各関数では、ディスプレイ名を
オプション引数@var{display}で指定できます。
この引数には、ディスプレイ名か
フレーム（が表示されいるディスプレイを意味する）か、または
@code{nil}（現在選択されているフレームのディスプレイを参照する。
@pxref{Input Focus}）を指定できます。

  @xref{Color Names}, @ref{Text Terminal Colors}, for other functions to
obtain information about displays.

@defun display-popup-menus-p &optional display
This function returns @code{t} if popup menus are supported on
@var{display}, @code{nil} if not.  Support for popup menus requires
that the mouse be available, since the menu is popped up by clicking
the mouse on some portion of the Emacs display.
@end defun

@defun display-graphic-p &optional display
This function returns @code{t} if @var{display} is a graphic display
capable of displaying several frames and several different fonts at
once.  This is true for displays that use a window system such as X,
and false for text terminals.
@end defun

@defun display-mouse-p &optional display
@cindex mouse, availability
This function returns @code{t} if @var{display} has a mouse available,
@code{nil} if not.
@end defun

@defun display-color-p &optional display
@findex x-display-color-p
この関数は、スクリーンがカラースクリーンならば@code{t}を返す。
It used to be called @code{x-display-color-p}, and that name
is still supported as an alias.
@end defun

@defun display-grayscale-p &optional display
この関数は、スクリーンで白黒の濃淡を表示できると@code{t}を返す。
(All color displays can do this.)
@end defun

@defun display-supports-face-attributes-p attributes &optional display
@anchor{Display Face Attribute Testing}
This function returns non-@code{nil} if all the face attributes in
@var{attributes} are supported (@pxref{Face Attributes}).

The definition of ``supported'' is somewhat heuristic, but basically
means that a face containing all the attributes in @var{attributes},
when merged with the default face for display, can be represented in a
way that's

@enumerate
@item
different in appearance than the default face, and

@item
``close in spirit'' to what the attributes specify, if not exact.
@end enumerate

Point (2) implies that a @code{:weight black} attribute will be
satisfied by any display that can display bold, as will
@code{:foreground "yellow"} as long as some yellowish color can be
displayed, but @code{:slant italic} will @emph{not} be satisfied by
the tty display code's automatic substitution of a ``dim'' face for
italic.
@end defun

@defun display-selections-p &optional display
This function returns @code{t} if @var{display} supports selections.
Windowed displays normally support selections, but they may also be
supported in some other cases.
@end defun

@defun display-images-p &optional display
This function returns @code{t} if @var{display} can display images.
Windowed displays ought in principle to handle images, but some
systems lack the support for that.  On a display that does not support
images, Emacs cannot display a tool bar.
@end defun

@defun display-screens &optional display
This function returns the number of screens associated with the display.
この関数は、ディスプレイに対応付けられているスクリーンの個数を返す。
@end defun

@defun display-pixel-height &optional display
この関数はスクリーンのピクセル単位の高さを返す。
On a character terminal, it gives the height in characters.

For graphical terminals, note that on ``multi-monitor'' setups this
refers to the pixel height for all physical monitors associated with
@var{display}.  @xref{Multiple Terminals}.
@end defun

@defun display-pixel-width &optional display
この関数はスクリーンのピクセル単位の幅を返す。
On a character terminal, it gives the width in characters.

For graphical terminals, note that on ``multi-monitor'' setups this
refers to the pixel width for all physical monitors associated with
@var{display}.  @xref{Multiple Terminals}.
@end defun

@defun display-mm-height &optional display
この関数はスクリーンのミリメートル単位の高さを返す。
This function returns the height of the screen in millimeters,
or @code{nil} if Emacs cannot get that information.

For graphical terminals, note that on ``multi-monitor'' setups this
refers to the height for all physical monitors associated with
@var{display}.  @xref{Multiple Terminals}.
@end defun

@defun display-mm-width &optional display
この関数はスクリーンのミリメートル単位の幅を返す。
This function returns the width of the screen in millimeters,
or @code{nil} if Emacs cannot get that information.

For graphical terminals, note that on ``multi-monitor'' setups this
refers to the width for all physical monitors associated with
@var{display}.  @xref{Multiple Terminals}.
@end defun

@defopt display-mm-dimensions-alist
This variable allows the user to specify the dimensions of graphical
displays returned by @code{display-mm-height} and
@code{display-mm-width} in case the system provides incorrect values.
@end defopt

@cindex backing store
@defun display-backing-store &optional display
この関数は、スクリーンのバッキングストア機能を返す。
Backing store means recording the pixels of windows (and parts of
windows) that are not exposed, so that when exposed they can be
displayed very quickly.

その値は、@code{always}、@code{when-mapped}、@code{not-useful}のシンボルの
いずれかである。
The function can also return @code{nil}
when the question is inapplicable to a certain kind of display.
@end defun

@cindex SaveUnder feature
@defun display-save-under &optional display
この関数は、ディスプレイにセーブアンダー機能があれば@code{nil}以外を返す。
That feature is used by pop-up windows
to save the pixels they obscure, so that they can pop down
quickly.
@end defun

@defun display-planes &optional display
この関数は、ディスプレイのプレイン数を返す。
This function returns the number of planes the display supports.
This is typically the number of bits per pixel.
For a tty display, it is log to base two of the number of colors supported.
@end defun

@defun display-visual-class &optional display
この関数は、スクリーンのビジュアルクラスを返す。
その値は、@code{static-gray}（制限された、変更できない階調数のグレースケール）、
@code{gray-scale}（全範囲のグレースケール）、
@code{static-color}（制限された、変更できない色数のカラー）、
@code{pseudo-color}（制限された色数のカラー）、
@code{true-color}（全範囲のカラー）、
@code{direct-color}（全範囲のカラー）のシンボルのいずれかである。
@end defun

@defun display-color-cells &optional display
この関数はスクリーンで使えるカラーセルの個数を返す。
@end defun

  These functions obtain additional information about the window
system in use where Emacs shows the specified @var{display}.  (Their
names begin with @code{x-} for historical reasons.)

@defun x-server-version &optional display
この関数は、ディスプレイで動作中のXサーバーの版番号のリストを返す。
This function returns the list of version numbers of the GUI window
system running on @var{display}, such as the X server on GNU and Unix
systems.  The value is a list of three integers: the major and minor
version numbers of the protocol, and the distributor-specific release
number of the window system software itself.  On GNU and Unix systems,
these are normally the version of the X protocol and the
distributor-specific release number of the X server software.  On
MS-Windows, this is the version of the Windows OS.
@end defun

@defun x-server-vendor &optional display
この関数は、Xサーバーソフトウェアの提供業者を返す。
This function returns the ``vendor'' that provided the window system
software (as a string).  On GNU and Unix systems this really means
whoever distributes the X server.  On MS-Windows this is the vendor ID
string of the Windows OS (Microsoft).

When the developers of X labeled software distributors as
``vendors'', they showed their false assumption that no system could
ever be developed and distributed noncommercially.
@end defun

@ignore
@defvar x-no-window-manager
This variable's value is @code{t} if no X window manager is in use.
@end defvar
@end ignore

@ignore
@item
The functions @code{x-pixel-width} and @code{x-pixel-height} return the
width and height of an X Window frame, measured in pixels.
@end ignore