admin/notes/nextstep

   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.  This is an area for improvement.
  68
  69
  70
  71
  72 Text Rendering and Font Handling
  73 --------------------------------
  74
  75 nsfont.m implements the font driver, responsible for managing fonts and
  76 rendering text.  Fonts are obtained through NSFontManager.  Rendering must be
  77 done at a low level due to emacs' fine control over this process, therefore
  78 there are different approaches under Cocoa and GNUstep.  Under GNUstep, the
  79 original NeXT Display PostScript (DPS) APIs are available and used.  Under
  80 Cocoa, these were removed and Quartz drawing functions replaced them.
  81
  82 In both cases, font glyphs are accessed through UTF8 character
  83 representations.  It would be preferable to use Unicode indices, but prior
  84 attempts at this have failed.
  85
  86 Multi-script fontsets are auto-created in nsfont_make_fontset_for_font() using
  87 the facilities of NSTextStorage and NSLayoutManager.
  88
  89
  90 Object Architecture
  91 -------------------
  92
  93 Unlike the other GUIs, the NS interface is based on a high-level and
  94 object-oriented API.  This creates some tension in the code because emacs
  95 itself has been architected around the low-level Xlib and Xt APIs.  The NS
  96 port tries to strike a balance between simplifying code on its side using OO
  97 features, and keeping code as similar as possible to other ports to ease
  98 maintenance.  The following are the main classes (see nsterm.h):
  99
 100 EmacsApp : NSApplication
 101   - event loop integration, interapp comms point for Finder (NSWorkspace) msgs,
 102     Services
 103   - one global instance (NSApp)
 104   - nsterm.m
 105
 106 EmacsView : NSView <TextInput>
 107   - handles rendering of text and fringe, interapp comms for drag/drop
 108   - instance for each frame
 109   - child of window's content view
 110   - nsterm.m
 111
 112 EmacsWindow : NSWindow
 113   - utility override for resize handling
 114
 115 EmacsScroller : NSScroller
 116   - instance for each emacs window, renders scrollbar
 117   - child of window's content view
 118   - nsterm.m
 119
 120 EmacsImage : NSImage
 121   - image rendering, toolbar icons, stippling, fringe bitmaps
 122   - instance for each image
 123   - nsimage.m
 124
 125 EmacsMenu : NSMenu
 126   - menu management
 127   - one tree of instances for menubar, one instance for each popup menu
 128   - nsmenu.m
 129
 130 EmacsToolbar : NSToolbar
 131   - toolbar management, one instance for each frame
 132   - nsmenu.m
 133
 134
 135 EmacsDialogPanel : NSPanel
 136   - popup dialogs, one instance for each
 137   - nsmenu.m
 138
 139 EmacsTooltip : NSObject
 140   - tooltip popups, one instance for each
 141   - nsmenu.m
 142
 143 EmacsGlyphStorage : NSObject <NSGlyphStorage>
 144   - utility for text rendering
 145   - nsfont.m
 146
 147 EmacsPrefsController : NSObject
 148   - utility for preferences panel management, one global instance
 149   - nsterm.m
 150   - nextstep/Cocoa/Emacs.base/Contents/Resources/preferences.nib
 151   - nextstep/GNUstep/Emacs.base/Resources/preferences.gorm
 152
 153 EmacsSavePanel : NSSavePanel
 154 EmacsOpenPanel : NSOpenPanel
 155   - utility override for panel notifications