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