view nextstep/DEV-NOTES @ 107648:babfb0a156a1

Initial support for bidirectional editing. Makefile.in (obj): Include bidi.o. (bidi.o): New target. makefile.w32-in (OBJ1): Add $(BLD)/bidi.$(O). ($(BLD)/bidi.$(O)): New target. bidi.c: New file. buffer.h (struct buffer): New members bidi_display_reordering and bidi_paragraph_direction. buffer.c (init_buffer_once): Initialize bidi_display_reordering and bidi_paragraph_direction. (syms_of_buffer): Declare Lisp variables bidi-display-reordering and bidi-paragraph-direction. (Fbuffer_swap_text): Swap the values of bidi_display_reordering and bidi_paragraph_direction. dispextern.h (BIDI_MAXLEVEL, BIDI_AT_BASE_LEVEL): New macros. (bidi_type_t, bidi_dir_t): New types. (bidi_saved_info, bidi_stack, bidi_it): New structures. (struct it): New members bidi_p, bidi_it, paragraph_embedding, prev_stop, base_level_stop, and eol_pos. (bidi_init_it, bidi_get_next_char_visually): New prototypes. (IT_STACK_SIZE): Enlarge to 5. (struct glyph_row): New member reversed_p. <string_buffer_position>: Update prototype. (PRODUCE_GLYPHS): Set the reversed_p flag in the iterator's glyph_row if bidi_it.paragraph_dir == R2L. (struct glyph): New members resolved_level and bidi_type. dispnew.c (direct_output_forward_char): Give up if we need bidi processing or buffer's direction is right-to-left. (prepare_desired_row): Preserve the reversed_p flag. (row_equal_p): Compare the reversed_p attributes as well. xdisp.c (init_iterator): Initialize it->bidi_p. Call bidi_init_it and set it->paragraph_embedding from the current buffer's value of bidi_paragraph_direction. (reseat_1): Initialize bidi_it.first_elt. (set_iterator_to_next, next_element_from_buffer): Use the value of paragraph_embedding to determine the paragraph direction. (set_iterator_to_next): Under bidi reordering, call bidi_get_next_char_visually. Call bidi_paragraph_init if the new_paragraph flag is set in the bidi iterator. (next_element_from_buffer): If bidi_it.first_elt is set, initialize paragraph direction and find the first character to display in the visual order. If reseated to a middle of a line, prime the bidi iterator starting at the line's beginning. Handle the situation where we overstepped stop_charpos due to non-linearity of the bidi iteration. Likewise for when we back up beyond the previous stop_charpos. When moving across stop_charpos, record it in prev_stop. (display_line): Set row->end and it->start for the next row to the next character in logical order. Always extend reversed_p rows to the end of line, even if they end at ZV. Copy the reversed_p flag to the next glyph row. Keep calling set_cursor_from_row for bidi-reordered rows even if we already have a possible candidate for cursor position. Set row_end after all the row's glyphs have been produced, by looping over the glyphs. Record the position after EOL in it->eol_pos, and use it to set end_pos of the last row produced for a continued line. <Qright_to_left, Qleft_to_right>: New variables. (syms_of_xdisp): Initialize and staticpro them. (string_buffer_position_lim): New function. (string_buffer_position): Most of code moved to string_buffer_position_lim. Last argument and return value are now EMACS_INT; all callers changed. (set_cursor_from_row): Rewritten to support bidirectional text and reversed glyph rows. (text_outside_line_unchanged_p, try_window_id): Disable optimizations if we are reordering bidirectional text and the paragraph direction can be affected by the change. (append_glyph, append_composite_glyph) (produce_image_glyph, append_stretch_glyph): Set the resolved_level and bidi_type members of each glyph. (append_glyph): If the glyph row is reversed, prepend the glyph rather than appending it. (handle_stop_backwards): New function. (reseat_1, pop_it, push_it): Set prev_stop and base_level_stop. (reseat): call handle_stop_backwards to recompute prev_stop and base_level_stop for the new position. (handle_invisible_prop): Under bidi iteration, skip invisible text using bidi_get_next_char_visually. If we are `reseat'ed, init the paragraph direction. Update IT->prev_stop after skipping invisible text. (move_it_in_display_line_to): New variables prev_method and prev_pos. Compare for strict equality in BUFFER_POS_REACHED_P. (try_cursor_movement): Examine all the candidate rows that occlude point, to return the best match. If rows are bidi-reordered and point moved backwards, back up to the row that is not a continuation line, and start looking for a suitable row from there. term.c (append_glyph): Reverse glyphs by pre-pending them, rather than appending, if the glyph_row's reversed_p flag is set. Set the resolved_level and bidi_type members of each glyph. .gdbinit (pbiditype): New command. (pgx): Use it to display bidi level and type of the glyph. (pitx): Display some bidi information about the iterator. (prowlims, pmtxrows): New commands. files.el: Make bidi-display-reordering safe variable for boolean values. mule.texi (International): Mention support of bidirectional editing. (Bidirectional Editing): New section. HELLO: Reorder Arabic and Hebrew into logical order, and insert RLM before the opening paren, to make the display more reasonable. Add setting for bidi-display-reordering in the local variables section. NEWS: Mention initial support for bidirectional editing.

This file summarizes primary aspects of the NS port architecture.  If
possible, it should be updated for changes.

Currently it summarizes the state as of:

  summer 2008 shortly after merging to trunk



Startup
-------

Init sequence:
  emacs.c: ns_alloc_autorelease_pool()		nsterm.m
  emacs.c: ns_init_paths()			nsterm.m
    - override EMACSLOADPATH, etc. so resources can be found in-bundle
  emacs.c: init_display()			dispnew.c
    - sets Vwindow_system (window-system) to 'ns
  emacs.c: loadup.el -> startup.el -> ns-initialize-window-system
    -> x-open-connection (nsfns.m)
      - ns-list-services
      -> nsterm.m: ns_term_init()
	- EmacsApp sharedApplication
	- read NS defaults (org.gnu.Emacs.plist)
	- init X-style color list
	- ns_create_terminal()
	- NSApp run (goes to applicationDidFinishLaunching which terminates
	  	     event loop -- see below)



Event Loop
----------

In an NS application, the event loop is normally managed by system and all
user code is event-driven.  [NSApp run] is called by user and never returns.

In Emacs, the event loop is managed by emacs itself.

The NS port mediates between these two styles by intercepting the NS event
dispatch at [NSApp sendEvent].  If a special event is detected, the event loop
is broken, and control returned to Emacs.  This special event is sent by
ns_send_appdefined, which is called under these circumstances:

 - if a user input event is received
 - when a timeout fires

NS event processing is instigated from Emacs through ns_select() and
ns_read_socket() in nsterm.m.  Parts of the codepaths leading to these
functions are:


 keyboard.c:read_avail_input()
     -> ns_read_socket (ns_send_appdefined) -> [NSApp run]

 process.c:wait_reading_process_output()
     -> ns_select -> gobble_input (global inNsSelect=1)
       -> ns_read_socket (ns_send_appdefined if !expected) -> [NSApp run]

 sysdep.c:sys_select() -> read_input_waiting()
     -> ns_read_socket (send_appdefined) -> [NSApp run]
 [this codepath may not be used]


Currently ctrl-g is not detected in as many circumstances as other emacsen.
It is not certain whether this is due to the means of event loop integration,
or errors of omission in the NS code.  One area for exploration is the
NO_SOCK_SIGIO define.  When it is defined, ctrl-g seems to be picked up more
often, but there are some annoying side effects.  Currently it is left off by
default, unless the --enable-cocoa-experimental-ctrl-g option is passed to
configure [option removed Feb 2009].  (Has no effect under GNUstep.)
This is an area for improvement.  Also, see the article here and its
containing thread:

http://article.gmane.org/gmane.emacs.devel/92021/match=handling%5fsignal




Text Rendering and Font Handling
--------------------------------

nsfont.m implements the font driver, responsible for managing fonts and
rendering text.  Fonts are obtained through NSFontManager.  Rendering must be
done at a low level due to emacs' fine control over this process, therefore
there are different approachs under Cocoa and GNUstep.  Under GNUstep, the
original NeXT Display PostScript (DPS) APIs are available and used.  Under
Cocoa, these were removed and Quartz drawing functions replaced them.

In both cases, font glyphs are accessed through UTF8 character
representations.  It would be preferable to use unicode indices, but prior
attempts at this have failed.

Multi-script fontsets are auto-created in nsfont_make_fontset_for_font() using
the facilities of NSTextStorage and NSLayoutManager.


Object Architecture
-------------------

Unlike the other GUIs, the NS interface is based on a high-level and
object-oriented API.  This creates some tension in the code because emacs
itself has been architected around the low-level Xlib and Xt APIs.  The NS
port tries to strike a balance between simplifying code on its side using OO
features, and keeping code as similar as possible to other ports to ease
maintenance.  The following are the main classes (see nsterm.h):

EmacsApp : NSApplication
  - event loop integration, interapp comms point for Finder (NSWorkspace) msgs,
    Services
  - one global instance (NSApp)
  - nsterm.m

EmacsView : NSView <TextInput>
  - handles rendering of text and fringe, interapp comms for drag/drop
  - instance for each frame
  - child of window's content view
  - nsterm.m

EmacsWindow : NSWindow
  - utility override for resize handling

EmacsScroller : NSScroller
  - instance for each emacs window, renders scrollbar
  - child of window's content view
  - nsterm.m

EmacsImage : NSImage
  - image rendering, toolbar icons, stippling, fringe bitmaps
  - instance for each image
  - nsimage.m

EmacsMenu : NSMenu
  - menu management
  - one tree of instances for menubar, one instance for each popup menu
  - nsmenu.m

EmacsToolbar : NSToolbar
  - toolbar management, one instance for each frame
  - nsmenu.m


EmacsDialogPanel : NSPanel
  - popup dialogs, one instance for each
  - nsmenu.m

EmacsTooltip : NSObject
  - tooltip popups, one instance for each
  - nsmenu.m

EmacsGlyphStorage : NSObject <NSGlyphStorage>
  - utility for text rendering
  - nsfont.m

EmacsPrefsController : NSObject
  - utility for preferences panel management, one global instance
  - nsterm.m
  - nextstep/Cocoa/Emacs.base/Contents/Resources/preferences.nib
  - nextstep/GNUstep/Emacs.base/Resources/preferences.gorm

EmacsSavePanel : NSSavePanel
EmacsOpenPanel : NSOpenPanel
  - utility override for panel notifications