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