1This file summarizes primary aspects of the NS port architecture. If 2possible, it should be updated for changes. 3 4Currently it summarizes the state as of: 5 6 summer 2008 shortly after merging to trunk 7 8 9 10Startup 11------- 12 13Init 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 32Event Loop 33---------- 34 35In an NS application, the event loop is normally managed by system and all 36user code is event-driven. [NSApp run] is called by user and never returns. 37 38In Emacs, the event loop is managed by emacs itself. 39 40The NS port mediates between these two styles by intercepting the NS event 41dispatch at [NSApp sendEvent]. If a special event is detected, the event loop 42is broken, and control returned to Emacs. This special event is sent by 43ns_send_appdefined, which is called under these circumstances: 44 45 - if a user input event is received 46 - when a timeout fires 47 48NS event processing is instigated from Emacs through ns_select() and 49ns_read_socket() in nsterm.m. Parts of the codepaths leading to these 50functions 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 65Currently ctrl-g is not detected in as many circumstances as other emacsen. 66It is not certain whether this is due to the means of event loop integration, 67or errors of omission in the NS code. This is an area for improvement. 68 69 70 71 72Text Rendering and Font Handling 73-------------------------------- 74 75nsfont.m implements the font driver, responsible for managing fonts and 76rendering text. Fonts are obtained through NSFontManager. Rendering must be 77done at a low level due to emacs' fine control over this process, therefore 78there are different approaches under Cocoa and GNUstep. Under GNUstep, the 79original NeXT Display PostScript (DPS) APIs are available and used. Under 80Cocoa, these were removed and Quartz drawing functions replaced them. 81 82In both cases, font glyphs are accessed through UTF8 character 83representations. It would be preferable to use Unicode indices, but prior 84attempts at this have failed. 85 86Multi-script fontsets are auto-created in nsfont_make_fontset_for_font() using 87the facilities of NSTextStorage and NSLayoutManager. 88 89 90Object Architecture 91------------------- 92 93Unlike the other GUIs, the NS interface is based on a high-level and 94object-oriented API. This creates some tension in the code because emacs 95itself has been architected around the low-level Xlib and Xt APIs. The NS 96port tries to strike a balance between simplifying code on its side using OO 97features, and keeping code as similar as possible to other ports to ease 98maintenance. The following are the main classes (see nsterm.h): 99 100EmacsApp : NSApplication 101 - event loop integration, interapp comms point for Finder (NSWorkspace) msgs, 102 Services 103 - one global instance (NSApp) 104 - nsterm.m 105 106EmacsView : 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 112EmacsWindow : NSWindow 113 - utility override for resize handling 114 115EmacsScroller : NSScroller 116 - instance for each emacs window, renders scrollbar 117 - child of window's content view 118 - nsterm.m 119 120EmacsImage : NSImage 121 - image rendering, toolbar icons, stippling, fringe bitmaps 122 - instance for each image 123 - nsimage.m 124 125EmacsMenu : NSMenu 126 - menu management 127 - one tree of instances for menubar, one instance for each popup menu 128 - nsmenu.m 129 130EmacsToolbar : NSToolbar 131 - toolbar management, one instance for each frame 132 - nsmenu.m 133 134 135EmacsDialogPanel : NSPanel 136 - popup dialogs, one instance for each 137 - nsmenu.m 138 139EmacsTooltip : NSObject 140 - tooltip popups, one instance for each 141 - nsmenu.m 142 143EmacsGlyphStorage : NSObject <NSGlyphStorage> 144 - utility for text rendering 145 - nsfont.m 146 147EmacsPrefsController : 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 153EmacsSavePanel : NSSavePanel 154EmacsOpenPanel : NSOpenPanel 155 - utility override for panel notifications 156