Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 378 lines (288 sloc) 15.118 kB
acbc942 @mdamt New: Design document
mdamt authored
1 # Design of Manokwari
2
3 Manokwari is a desktop shell for GNOME 3. It features combined Gtk+ and HTML5 frontend (Gtk+ is legacy here and would be replaced totally with HTML5
4 in the future). It is an evolution from a shell called blankon-panel.
5
6 ## Administrativia
7 This document includes few marks for developers and readers use.
8 * [NOT YET IMPLEMENTED] marks the not yet implemented part of the system
9 * [TODO] marks changes planned in the future
10 * [FIXME] marks doubts arosed when writing this document.
11 * [JSCORE] marks interfaces exposed to JSCore
12 * [SIGNAL] marks signals
13 * [PROPERTY] marks properties of an object
14
15 ## Architecture
16
17 Manokwari uses front-end and back-end architecture. The front-end is done mainly with HTML5, JavaScript, and Gtk+ while the back-end is done with Vala.
18 Communication between front-end and back-end is achieved by exposing back-end as functions accessible through JavaScript via Webkit's JSCore library.
19
20 ## Goals
21 Manokwari has a set of goals:
22 * Implements a lightweight yet beautiful GNOME desktop shell
23 * Provides an easy entry point for newbie developers to contribute
24
25 ## Non-goals
26 Manokwari at its currrent state considers as non-goals:
27 * Window manager
28 * Compositing manager
6f9c8ad @mdamt Changes: Trivial markdown fix
mdamt authored
29
30
acbc942 @mdamt New: Design document
mdamt authored
31 However this may change in the future
32
33 ### Logical view
34
35 #### Front-end
36 ##### PanelCalendar
37 PanelCalendar is a calendar widget displayed in a window. It contains:
38 * A month view calendar (Gtk+ stock widget)
39 * List of calendar activity [NOT YET IMPLEMENTED]
40 * A button, which when pressed will invoke GNOME's date/time control panel applet
41
6f9c8ad @mdamt Changes: Trivial markdown fix
mdamt authored
42
acbc942 @mdamt New: Design document
mdamt authored
43 PanelCalendar
44
45 ##### PanelClock
46 PanelClock is a widget displaying a clock. It inherits GtkLabel and draws the text manually.
47
48 PanelClock
49
50 ##### PanelAbstractWindow
51 PanelAbstractWindow is a base class for all windows used in Manokwari.
52 It sets several window management hints including:
53 * Non-decorated window
54 * Non-resizable window
55 * Focus on map window
56 * Accept on focus
57 * Sticky on all workspaces
58 * Non-visible in task switcher
59
6f9c8ad @mdamt Changes: Trivial markdown fix
mdamt authored
60
61
acbc942 @mdamt New: Design document
mdamt authored
62 PanelAbstractWindow
63
64 [SIGNAL] screen_size_changed()
65 // Emitted when either monitor or screen size is changed
66 Protected:
67 void set_struts()
68 // Reserve part of the screen according to window size and position to be
69 // always visible and not overlapped by any windows.
70 // [TODO] This would be moved to PanelWindowHost which is the only place that uses this function
71
72 ##### PanelDesktop
73 PanelDesktop is a top level window which hosts the desktop area. It has DESKTOP window manager hint.
74
75 The size is the whole size of the primary monitor resolution. This may not be expected in multi-head setup. [FIXME]
76
77 PanelDesktop
78
79 [SIGNAL] desktop_clicked()
80 // Emitted when the desktop area (effectively the Web view) is clicked
81
82 ##### PanelDesktopHTML
83 PanelDesktopHTML is a web view embedded in PanelDesktop object. More description about the view
84 is described in the "Desktop front end" section.
85
86 PanelDesktopHTML
87
88 ##### PanelMenuBox
89 PanelMenuBox is a top level window which hosts the menu. It is hard placed to NORTH-WEST area of the screen.
90 It has name "_manokwari_menu_" for tracing purposes. The window is invisible (transparent). The visible area
91 will come from the web view it hosts.
92
93 PanelMenuBox listens to the following keys:
94 * Escape to close menu
95 * PrintScreen to take screen shot [FIXME/TODO] Not working?
96
6f9c8ad @mdamt Changes: Trivial markdown fix
mdamt authored
97
98
acbc942 @mdamt New: Design document
mdamt authored
99 PanelMenuBox
100
101 [SIGNAL] void dismissed()
102 // Emitted when menu is dismissed
103 [SIGNAL] void shown()
104 // Emitted when menu is shown
105 [SIGNAL] void about_to_show_content()
106 // [TODO] To be removed, not used anymore
107 void try_hide()
108 // Asks menu to close
109
110 ##### PanelMenuHTML
111 PanelMenuHTML is a web view embedded in the PanelMenuBox object. More description about the view
112 is described in the "Menu front end" section.
113
114 PanelMenuHTML
115
116 void start()
117 // Starts menu population
118 void triggerShowAnimation()
119 // Starts show animation in JavaScript part
120 void triggerHideAnimation()
121 // Starts hide animation in JavaScript part
122 bool handleEsc()
123 // Asks JavaScript to handle Escape key
124 // Returns false when JavaScript side doesn't handle (which in turns will make PanelMenuBox to close itself)
125
126 ##### PanelSessionManager
127 PanelSessionManager is a singleton object to communicate with GNOME session manager.
128 It registers manokwari to GNOME in order to established a full desktop shell, otherwise it will be killed by GNOME session manager.
129
130 PanelSessionManager
131
132 void logout()
133 // Logouts from the session. [TODO] Will be put as private in the future.
134 void shutdown()
135 // Shutsdowns the desktop. [TODO] Will be put as private in the future.
136 bool can_shutdown()
137 // Returns whether the desktop can be shutted down. [TODO] Will be put as private in the future.
138 [JSCORE] bool SessionManager.canShutdown()
139 // Wrapper to can_shutdown() function above
140 [JSCORE] void SessionManager.logout()
141 // Wrapper to logout() function above
142 [JSCORE] void SessionManager.shutown()
143 // Wrapper to shutdown() function above
144
145 ##### PanelTray
146 PanelTray is a Gtk+ widget, subclassed from GtkHBox, to display system tray items.
147 It performs X11 event filtering to implement Freedesktop system tray on it's window which _NET_WM_SYSTEM_TRAY_Sx is associated with it (x being the screen number). The current UI uses horizontal system tray orientation. Whenever a system tray item is added, a GtkSocket is created to host the item and packed to the widget. And when the item is destroyed or removed, the associated socket is also removed from the widget. The widget draws it's own background.
148
149 PanelTray
150
151 [SIGNAL] new_item_added()
152 // Emitted when a system tray is added
153
154 ##### PanelWindowPager
155 PanelWindowPager is a widget which displays the desktop pager and the "Show desktop" button.
156 Whenever any of the pager is chosen then the workspace is set to the associated pager.
157 Whenever the "Show desktop" button is pressed, all visible windows will be minimized showing the desktop uncluttered.
158 [TODO] This object could be refactored/renamed and moved to separate file.
159
160 PanelWindowPager
161
162 [SIGNAL] void hidden()
163 // Emitted when pager is hidden
164 void reset_show_desktop()
165 // Resets the "show desktop" button, which basically returns the visibility of unchanged windows
166
167 ##### PanelWindowPagerEntry
168 PanelWindowPagerEntry hosts PanelWindowPager. This widget handles a mouse press which will toggles the visibility of the pager.
169 [TODO] This object could be refactored/renamed and moved to separate file.
170
171 PanelWindowPagerEntry
172
173 void reset_show_desktop()
174 // Ask the pager with the same function name
175
176 ##### PanelWindowEntry
177 PanelWindowEntry is a widget showing the icon of the associated window. It acts as proxy to the window. It can maximize, minimize,
178 and other windowing functions with a menu, accessible with right click on the area. If left-click is given, it toggles between activate and minimize functions.
179 [TODO] This object could be refactored to separate file.
180
181 PanelWindowEntry
182
183 void show_popup()
184 // Shows context menu of common active windowing functions, such as minimize, move, and maximize.
185
186 ##### PanelWindowEntryDescription
187 PanelWindowEntryDescription is a window showing the currently hovered icon along with nearby icons of the windows in the window list provided by the window manager. This window shows sliding animation when the mouse is moving in the PanelWindowEntry area.
188 [TODO] This object could be refactored/renamed and moved to separate file.
189 [TODO] This object needs to be tested in RTL environment.
190
191 PanelWindowEntryDescription
192
193 void clear_entry()
194 // Clears the list which should be drawn
195 void activate()
196 // Activates the window and showing the list
197 void deactivate()
198 // Hides the window
199 void update_position()
200 // Update the position of the window [FIXME] Should be removed?
201
202 ##### PanelWindowHost
203 PanelWindowHost is a top level window which shows the horizontal panel on the top of the screen.
204 This window hosts following objects:
205 * An icon showing distributor logo, which when clicked shows the PanelMenuBox
206 * PanelWindowPagerEntry
207 * PanelWindowEntryDescription
208 * PanelTray
209 * PanelClock
210 * PanelCalendar
211
6f9c8ad @mdamt Changes: Trivial markdown fix
mdamt authored
212
213
acbc942 @mdamt New: Design document
mdamt authored
214 [TODO] This object could be refactored/renamed and moved to separate file.
215
216 PanelWindowHost
217
218 [SIGNAL] windows_gone();
219 // Emitted when all windows have gone, either closed or minimized
220 [SIGNAL] windows_visible()
221 // Emitted when there is at least one window visible
222 [SIGNAL] all_windows_visible()
223 // Emitted when all normal windows visible
224 [SIGNAL] dialog_opened()
225 // Emitted when a dialog is opened
226 [SIGNAL] menu_clicked()
227 // Emitted when the menu is clicked
228 void no_windows_around()
229 // Returns whether no visible windows is visible
230 void update()
231 // Update the state of the objects associated with window list provided by window manager
232 void reposition()
233 // Update the position of the window when screen size is changed
234
235 ##### Menu front-end (menu.js)
236
237 [TODO] To be written
238
239 ##### Desktop front-end (desktop.js)
240
241 [TODO] To be written
242
243 #### Back-Ends
244 ##### PanelDesktopData
245 PanelDesktopData is a back-end object providing interface to manage the content of the desktop.
246 This basically provides interfaces to remove and provide list of application launcher.
247 It monitors the Freedesktop desktop directory (~/Desktop in English locale) for changes concerning .desktop files.
248 The interface is exposed to JSCore.
249
250 PanelDesktopData
251
252 [JSCore] DesktopData()
253 [JSCore] list update()
254 // Returns list of launchers as JavaScript object with following fields:
255 // * icon: Full path to icon depending on current theme
256 // * name: Name of launcher
257 // * desktop: Desktop file name
258 [JSCore] DesktopData.updateCallback(function)
259 // sets the function to call when changes happens in Desktop directory
260 [JSCORE] DesktopData.removeFromDesktop(string) static
261
262
263 ##### PanelPlaces
264 PanelPlaces is a back-end object handling GNOME's Places objects. PanelPlaces handles localized Places.
265
266 PanelPlaces
267
268 [JSCORE] void Places.updateCallback(function)
269 // Sets function to be called when any of the Places is changed
270 [JSCORE] list Places.update()
271 // Returns the list of the Places as a JavaScript array with following fields:
272 // * Home, which is an object of following fields:
273 // * icon: Full path of "gtk-home" in current theme
274 // * name: Localized string of "Home"
275 // * uri: Uri to the home
276 // * Special directories, which is prepended with following object:
277 // * name: Localized string of "Bookmarks"
278 // * isHeader: true
279 // Then followed with following directories as object:
280 // * icon: Full path of the directory icon in current theme
281 // * name: The name of the directory
282 // * uri: The uri of the directory
283 // * Mounts, which is prepended with following object:
284 // * name: Localized string of "Mounts"
285 // * isHeader: true
286 // Then followed with following directories as object:
287 // * icon: Full path of the mount icon in current theme
288 // * name: The name of the mount
289 // * uri: The uri of the mount
290 // * Network, which contains following objects:
291 // * Networks, which is of object:
292 // * icon: Full path of the "gtk-network" icon in current theme
293 // * name: Localized string of "My network"
294 // * uri: Uri of "network:///"
295 // * Connect to server, which is of object:
296 // * icon: Full path of the "gtk-fs-network" icon in current theme
297 // * name: Localized string of "Connect to server..."
298 // * command: String of "nautilus-connect-server"
299
300
301 ##### PanelUser
302 PanelUser is a back-end object which provides information about the user which owns the session.
303
304 PanelUser
305
306 [PROPERTY] string icon_file read-only
307 [PROPERTY] string real_name read-only
308 [PROPERTY] string host_name read-only
309 [JSCORE] string UserAccount.getIconFile()
310 [JSCORE] string UserAccount.getRealName()
311 [JSCORE] string UserAccount.getHostName()
312
313
314 ##### PanelXdgData
315 PanelXdgData is a back-end object providing the Freedesktop menu system. It opens the whole sequence of the menu according to the catalog name passed in the constructor. It monitors the Freedesktop data directory as well as the applications desktop directory.
316
317 PanelXdgData
318
319 [JSCORE] XdgData.updateCallback(function)
320 // Sets function to be called when any of the XdgData is changed
321 [JSCORE] XdgData.put_to_desktop(filename)
322 // Prepares the .desktop file for filename [TODO] Rename to putToDesktop
323 [JSCore] list update()
324 // Returns list of menu structure as a JavaScript array of:
325 // * Directory, prepended with header object:
326 // * icon: Full path to the directory icon in the current theme
327 // * name: Name of the directory
328 // * children: An array of Entry below
329 // * Entry, an object of:
330 // * icon: Full path to the entry icon in the current theme
331 // * name: The name of the entry
332 // * desktop: Full path to the .desktop file of the entry
333
334 #### Helpers
335 ##### PanelUtils
336 PanelUtils is a set of helper functions
337
338 ##### PanelScreen
339 PanelScreen is a utility static functions for handling screen.
340
341 ### Development View
342
343 #### Dependencies
344
345 ##### X11
346 Manokwari uses explicit X11 functions, hence may not be easily modified for used with other windowing system.
347
348 ##### D-Bus
349 Manokwari uses session D-Bus to perform IPC to following parts of the system:
350 * GNOME session manager
351 * Freedesktop account manager
352
353 #### Source code structure
354
355 The structure of source code is partitioned as follows:
356 * src/: Contains the source code written in Vala
357 * system/: Contains the JavaScript, CSS, and HTML5 files accessible from the webviews
358 * vapi/: Contains custom vapi files
359 * po/: Contains translations files
360 * data/: Contains distribution files
361
362 ### Physical View
363
364 #### File distributions
365 Files in system/ directory is installed in a directory (set to /usr/share/manokwari/system) which would be available for the webviews. Other than that, usual autotools based installation files are deployed in the system such as:
366 * manokwari binary is installed in /usr/bin
367 * manokwari.desktop is installed in /usr/share/applications
368 * manokwari.mo is installed in translation directory
369
370 ### Scenarios
371 The lifecycle of Manokwari is of as follows:
372 * Started by gnome-session
373 * Run indefinitely until any of the following occurs:
374 * User chose shutdown or login menu
375 * Manokwari is unable to respond gnome-session when asked for something via D-Bus
376 * Internal error which causes Manokwari to crash
377
Something went wrong with that request. Please try again.