jcs.org
an experiment in making a cocoa webkit browser manageable under X11
adjust some wording, capitalize
+26
-23
+26
-23
README.md
+26
-23
README.md
···
1
1
## shadowebkit
2
-
by joshua stein
3
-
http://jcs.org/
2
+
by joshua stein - http://jcs.org/
4
3
5
4
6
-
### about
7
-
this is an experiment in making a simple cocoa webkit-based browser that behaves like a normal X11 window and can be managed by a tiling X11 window manager under OS X.
5
+
### About
6
+
This is an experiment in making a simple Cocoa WebKit-based browser that behaves like a normal X11 window and can be managed by a tiling X11 window manager under OS X.
8
7
9
-
while it is possible to build webkit's gtk port on OS X and use existing minimalistic browsers like vimprobable or xxxterm, webkit-gtk's dependencies are quite numerous and font issues may cause rendering problems. shadowebkit uses the high-performance cocoa-based webkit framework already included on OS X.
8
+
While WebKit's GTK+ port will probably build on OS X to enable the use of existing minimalistic browsers like vimprobable or xxxterm, WebKitGTK's dependencies are quite numerous and font issues may cause rendering issues. shadowebkit uses the high-performance Cocoa-based WebKit framework already included and maintained on OS X.
10
9
11
10
12
-
### demo
13
-
this is ratpoison under X11.app, with shadowebkit running in the upper right frame.
11
+
### Demo
12
+
This screenshot shows the ratpoison window manager under X11.app, with shadowebkit running in the upper right frame:
14
13
15
14
16
15
17
16
18
-
### building
19
-
type 'xcodebuild' and then run 'build/Release/shadowebkit'.
17
+
### Building
18
+
Type `xcodebuild` and then run `build/Release/shadowebkit`. A URL can be passed as an argument to navigate to it.
20
19
21
20
22
-
### implementation
23
-
for a cocoa-based application to be able to be managed by an X11 window manager, an X11 window must be present in the X11 space and the window in the cocoa space cannot be a normal application. a normal cocoa application would present itself as a separate application from X11.app, taking away keyboard focus from the window manager. this means that to resize or move it, X11.app must be manually re-focused with cmd+tab every time.
21
+
### Implementation
22
+
For a Cocoa-based application to be able to be managed by an X11 window manager, an X11 window must be present in the X11 space and the window in the Cocoa space cannot be a "normal" application. A normal Cocoa application would present itself as separate from X11.app, taking away keyboard focus from the X11 window manager and requiring X11.app to be manually re-focused with cmd+tab every time, as well as being drawn with normal window controls and an imposing shadow.
23
+
24
+
shadowebkit starts by creating a simple X11 window that the tiling window manager manages and adjusts the size of. A Cocoa window is then drawn on top of it without any decorations and contains the WebKit frame and a URL bar.
25
+
26
+
The X11 window listens for events notifying it that its size or position has changed or that it has gained focus, and then moves the Cocoa window to those same coordinates on the screen. This way the X11 window is never really visible, but remains as a "shadow" under the Cocoa window.
24
27
25
-
shadowebkit starts by creating a simple X11 window that the tiling window manager manages and adjusts the size of. a cocoa window is also drawn without any decorations, which contains the webkit frame and a url bar.
28
+
While the Cocoa window can receive mouse inputs and clicking links and using dropdown boxes works, it is never actually focused by OS X's window server and does not receive keyboard input. Keyboard events are received by the currently focused cocoa app (X11.app) which then sends them to the X11 window of shadowebkit, which then converts XKeyEvent key events into NSEvents to send back to the Cocoa window.
26
29
27
-
the X11 window listens for X11 events notifying it that its size or position has changed or that it has gained focus, and then moves the cocoa window to those same coordinates. this way the X11 window is never really visible, but remains as a "shadow" to the cocoa window.
30
+
shadowebkit is multithreaded, managing the WebKit Cocoa window in its main thread and the X11 runloop in another. This lets each respond to events in its own environment like window positioning or mouse movements. When the WebKit window loads a new page and changes its title, the X11 window's title is updated to make it visible to the window manager.
28
31
29
-
while the cocoa window can receive mouse inputs, it is never actually focused by OS X's window server, so it does not receive keyboard input properly. keyboard events are received under X11.app by the X11 window of shadowebkit, which then converts key events into NSEvents to send back to the cocoa window.
30
32
31
-
shadowebkit is multithreaded, managing the webkit cocoa window in its main thread and the X11 runloop in another. this lets each respond to events in its own environment like window positioning or mouse movements. when the webkit window loads a new page and changes its title, the X11 window's title is updated to be visible to the window manager.
33
+
### Problems
34
+
Due to the keyboard proxying that is necessary for the focus issue, the normal command+c/v keys do not work since they are captured directly by X11.app. shadowebkit's X11 window does not see them, so it cannot proxy them over to the cocoa window.
32
35
36
+
Since the keycode conversion is done manually, not all keys are currently proxied over properly such as special characters typed with the option key.
33
37
34
-
### problems
35
-
due to the keyboard proxying that is necessary due to the cocoa window never being focused, the normal command+c/v keys do not work since they are captured by the currently-focused cocoa app, which is X11.app. shadowebkit's X11 window does not see them, so it cannot proxy them over to the cocoa window.
38
+
Also because of the focus issue (or maybe some other issue), mouse cursor changes are not done by WebKit so hovering over links does not change the cursor to a pointer, for example. The browser will mostly be controlled through keyboard shortcuts anyway, so this is not of major concern.
36
39
37
-
since the keycode conversion is done manually, not all keys are currently proxied over properly such as special characters typed with the option key.
38
40
39
-
also because of the focus issues, mouse cursor changes are not done properly, so hovering over links does not change the cursor to a pointer, for example. the browser will mostly be controlled through keyboard shortcuts anyway, so this is not a major concern.
41
+
### TODO
42
+
The browser is currently just a basic shell; a WebKit frame and a URL bar that are tied together. Typing a URL and pressing return will load it, and when the WebKit frame's URL changes, the URL bar is updated.
40
43
44
+
The Cocoa interface should be expanded to include small stop/reload/back buttons, a status bar, and a progress indicator.
41
45
42
-
### todo
43
-
the browser is currently just a basic shell; a webkit frame and a url bar that are tied together. typing a url and pressing return will load it, and when the url changes, the url bar is updated.
46
+
Keyboard shortcuts should be added to focus the URL bar, search, etc.
44
47
45
-
the cocoa interface should be expanded to include small stop/reload/back buttons, a status bar, and a progress indicator.
48
+
Implement tabs or something to deal with multiple windows.
46
49
47
-
keyboard shortcuts should be added to focus the url bar, search, etc.
50
+
Check how JavaScript popups and browser resizes affect shadowebkit.