Homepage: https://www.gnu.org/software/emacs
Author: Eric M. Ludlam
Dedicate frame support modes
This code was developed and maintained as a part of speedbar since 1996.
It became its own support utility in Aug 2000.
Dedicated frame mode is an Emacs independent library for supporting
a program/buffer combination that resides in a dedicated frame.
Support of this nature requires several complex interactions with the
user which this library will provide, including:
* Creation of a frame. Positioned relatively.
Includes a frame cache for User position caching.
* Switching between frames.
* Timed activities using idle-timers
* Frame/buffer killing hooks
* Mouse-3 position relative menu
* Mouse motion, help-echo hacks
* Mouse clicking & double clicking
* Mode line hacking
* Utilities for use in a program covering:
o keymap massage for some actions
o working with an associated buffer
o shift-click
o detaching a frame
o focus-shifting & optional frame jumping
o currently active frame.
o message/y-or-n-p
o mouse set point
To Use:
1) (require 'dframe)
2) Variable Setup:
-frame-parameters -- Frame parameters for Emacs.
-- Not on parameter lists: They can optionally include width
and height. If width or height is not included, then it will
be provided to match the originating frame. In general,
turning off the menu bar, mode line, and minibuffer can
provide a smaller window, or more display area.
-track-mouse-flag -- mouse tracking on/off specific to your tool.
-update-flag -- app toggle for timer use. Init from
`dframe-have-timer-flag'. This is nil for terminals, since
updating a frame in a terminal is not useful to the user.
-key-map -- Your keymap. Call `dframe-update-keymap' on it.
-buffer, -frame, -cached-frame -- Variables used to track your
applications buffer, frame, or frame cache (when hidden). See
`dframe-frame-mode' for details.
-before-delete-hook, -before-popup-hook, -after-create-hook --
Hooks to have called. The `-after-create-hook' probably wants
to call a function which calls `dframe-reposition-frame' in an
appropriate manner.
3) Function Setup:
your-frame-mode -- function to toggle your app frame on and off.
its tasks are:
a) create a buffer
b) Call `dframe-frame-mode'. (See its doc)
c) If successful (your -frame variable has a value), call
timer setup if applicable.
your-frame-reposition- -- Function to call from after-create-hook to
reposition your frame with `dframe-reposition-frame'.
your-mode -- Set up the major mode of the buffer for your app.
Set these variables: dframe-track-mouse-function,
dframe-help-echo-function,
dframe-mouse-click-function,
dframe-mouse-position-function.
See speedbar's implementation of these functions.
`speedbar-current-frame', `speedbar-get-focus', `speedbar-message',
`speedbar-y-or-n-p', `speedbar-set-timer', `speedbar-click',
`speedbar-position-cursor-on-line'
4) Handling mouse clicks, and help text:
dframe-track-mouse, dframe-help-echo-function --
These variables need to be set to functions that display info
based on the mouse's position.
Text property 'help-echo, set to `dframe-help-echo', which will
call `dframe-help-echo-function'.
Have a `-click' function, it can call `dframe-quick-mouse' for
positioning. If the variable `dframe-power-click' is non-nil,
then `shift' was held down during the click.
Bugs
* The timer managers doesn't handle multiple different timeouts.
* You can't specify continuous timeouts (as opposed to just idle timers.)