nextstep/DEV-NOTES

   1 This file summarizes primary aspects of the NS port architecture.  If
   2 possible, it should be updated for changes.
   3
   4 Currently it summarizes the state as of:
   5
   6   summer 2008 shortly after merging to trunk
   7
   8
   9
  10 Startup
  11 -------
  12
  13 Init sequence:
  14   emacs.c: ns_alloc_autorelease_pool()          nsterm.m
  15   emacs.c: ns_init_paths()                      nsterm.m
  16     - override EMACSLOADPATH, etc. so resources can be found in-bundle
  17   emacs.c: init_display()                       dispnew.c
  18     - sets Vwindow_system (window-system) to 'ns
  19   emacs.c: loadup.el -> startup.el -> ns-initialize-window-system
  20     -> x-open-connection (nsfns.m)
  21       - ns-list-services
  22       -> nsterm.m: ns_term_init()
  23         - EmacsApp sharedApplication
  24         - read NS defaults (org.gnu.Emacs.plist)
  25         - init X-style color list
  26         - ns_create_terminal()
  27         - NSApp run (goes to applicationDidFinishLaunching which terminates
  28                      event loop -- see below)
  29
  30
  31
  32 Event Loop
  33 ----------
  34
  35 In an NS application, the event loop is normally managed by system and all
  36 user code is event-driven.  [NSApp run] is called by user and never returns.
  37
  38 In Emacs, the event loop is managed by emacs itself.
  39
  40 The NS port mediates between these two styles by intercepting the NS event
  41 dispatch at [NSApp sendEvent].  If a special event is detected, the event loop
  42 is broken, and control returned to Emacs.  This special event is sent by
  43 ns_send_appdefined, which is called under these circumstances:
  44
  45  - if a user input event is received
  46  - when a timeout fires
  47
  48 NS event processing is instigated from Emacs through ns_select() and
  49 ns_read_socket() in nsterm.m.  Parts of the codepaths leading to these
  50 functions are:
  51
  52
  53  keyboard.c:read_avail_input()
  54      -> ns_read_socket (ns_send_appdefined) -> [NSApp run]
  55
  56  process.c:wait_reading_process_output()
  57      -> ns_select -> gobble_input (global inNsSelect=1)
  58        -> ns_read_socket (ns_send_appdefined if !expected) -> [NSApp run]
  59
  60  sysdep.c:sys_select() -> read_input_waiting()
  61      -> ns_read_socket (send_appdefined) -> [NSApp run]
  62  [this codepath may not be used]
  63
  64
  65 Currently ctrl-g is not detected in as many circumstances as other emacsen.
  66 It is not certain whether this is due to the means of event loop integration,
  67 or errors of omission in the NS code.  One area for exploration is the
  68 NO_SOCK_SIGIO define.  When it is defined, ctrl-g seems to be picked up more
  69 often, but there are some annoying side effects.  Currently it is left off by
  70 default, unless the --enable-cocoa-experimental-ctrl-g option is passed to
  71 configure [option removed Feb 2009].  (Has no effect under GNUstep.)
  72 This is an area for improvement.  Also, see the article here and its
  73 containing thread:
  74
  75 http://article.gmane.org/gmane.emacs.devel/92021/match=handling%5fsignal
  76
  77
  78
  79
  80 Text Rendering and Font Handling
  81 --------------------------------
  82
  83 nsfont.m implements the font driver, responsible for managing fonts and
  84 rendering text.  Fonts are obtained through NSFontManager.  Rendering must be
  85 done at a low level due to emacs' fine control over this process, therefore
  86 there are different approachs under Cocoa and GNUstep.  Under GNUstep, the
  87 original NeXT Display PostScript (DPS) APIs are available and used.  Under
  88 Cocoa, these were removed and Quartz drawing functions replaced them.
  89
  90 In both cases, font glyphs are accessed through UTF8 character
  91 representations.  It would be preferable to use unicode indices, but prior
  92 attempts at this have failed.
  93
  94 Multi-script fontsets are auto-created in nsfont_make_fontset_for_font() using
  95 the facilities of NSTextStorage and NSLayoutManager.
  96
  97
  98 Object Architecture
  99 -------------------
 100
 101 Unlike the other GUIs, the NS interface is based on a high-level and
 102 object-oriented API.  This creates some tension in the code because emacs
 103 itself has been architected around the low-level Xlib and Xt APIs.  The NS
 104 port tries to strike a balance between simplifying code on its side using OO
 105 features, and keeping code as similar as possible to other ports to ease
 106 maintenance.  The following are the main classes (see nsterm.h):
 107
 108 EmacsApp : NSApplication
 109   - event loop integration, interapp comms point for Finder (NSWorkspace) msgs,
 110     Services
 111   - one global instance (NSApp)
 112   - nsterm.m
 113
 114 EmacsView : NSView <TextInput>
 115   - handles rendering of text and fringe, interapp comms for drag/drop
 116   - instance for each frame
 117   - child of window's content view
 118   - nsterm.m
 119
 120 EmacsWindow : NSWindow
 121   - utility override for resize handling
 122
 123 EmacsScroller : NSScroller
 124   - instance for each emacs window, renders scrollbar
 125   - child of window's content view
 126   - nsterm.m
 127
 128 EmacsImage : NSImage
 129   - image rendering, toolbar icons, stippling, fringe bitmaps
 130   - instance for each image
 131   - nsimage.m
 132
 133 EmacsMenu : NSMenu
 134   - menu management
 135   - one tree of instances for menubar, one instance for each popup menu
 136   - nsmenu.m
 137
 138 EmacsToolbar : NSToolbar
 139   - toolbar management, one instance for each frame
 140   - nsmenu.m
 141
 142
 143 EmacsDialogPanel : NSPanel
 144   - popup dialogs, one instance for each
 145   - nsmenu.m
 146
 147 EmacsTooltip : NSObject
 148   - tooltip popups, one instance for each
 149   - nsmenu.m
 150
 151 EmacsGlyphStorage : NSObject <NSGlyphStorage>
 152   - utility for text rendering
 153   - nsfont.m
 154
 155 EmacsPrefsController : NSObject
 156   - utility for preferences panel management, one global instance
 157   - nsterm.m
 158   - nextstep/Cocoa/Emacs.base/Contents/Resources/preferences.nib
 159   - nextstep/GNUstep/Emacs.base/Resources/preferences.gorm
 160
 161 EmacsSavePanel : NSSavePanel
 162 EmacsOpenPanel : NSOpenPanel
 163   - utility override for panel notifications
 164