Commit | Line | Data |
---|---|---|
7630ec39 AR |
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 | |
abbf750d GM |
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: | |
7630ec39 AR |
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 |