Design of Manokwari
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 in the future). It is an evolution from a shell called blankon-panel.
This document includes few marks for developers and readers use.
- [NOT YET IMPLEMENTED] marks the not yet implemented part of the system
- [TODO] marks changes planned in the future
- [FIXME] marks doubts arosed when writing this document.
- [JSCORE] marks interfaces exposed to JSCore
- [SIGNAL] marks signals
- [PROPERTY] marks properties of an object
Manokwari has a set of goals:
- Implements a lightweight yet beautiful GNOME desktop shell
- Provides an easy entry point for newbie developers to contribute
Manokwari at its currrent state considers as non-goals:
- Window manager
- Compositing manager
However this may change in the future
PanelCalendar is a calendar widget displayed in a window. It contains:
A month view calendar (Gtk+ stock widget)
List of calendar activity [NOT YET IMPLEMENTED]
A button, which when pressed will invoke GNOME's date/time control panel applet
PanelClock is a widget displaying a clock. It inherits GtkLabel and draws the text manually.
PanelAbstractWindow is a base class for all windows used in Manokwari. It sets several window management hints including:
Focus on map window
Accept on focus
Sticky on all workspaces
Non-visible in task switcher
[SIGNAL] screen_size_changed() // Emitted when either monitor or screen size is changed Protected: void set_struts() // Reserve part of the screen according to window size and position to be // always visible and not overlapped by any windows. // [TODO] This would be moved to PanelWindowHost which is the only place that uses this function
PanelDesktop is a top level window which hosts the desktop area. It has DESKTOP window manager hint.
The size is the whole size of the primary monitor resolution. This may not be expected in multi-head setup. [FIXME]
PanelDesktop [SIGNAL] desktop_clicked() // Emitted when the desktop area (effectively the Web view) is clicked
PanelDesktopHTML is a web view embedded in PanelDesktop object. More description about the view is described in the "Desktop front end" section.
PanelMenuBox is a top level window which hosts the menu. It is hard placed to NORTH-WEST area of the screen. It has name "manokwari_menu" for tracing purposes. The window is invisible (transparent). The visible area will come from the web view it hosts.
PanelMenuBox listens to the following keys:
Escape to close menu
PrintScreen to take screen shot [FIXME/TODO] Not working?
[SIGNAL] void dismissed() // Emitted when menu is dismissed [SIGNAL] void shown() // Emitted when menu is shown [SIGNAL] void about_to_show_content() // [TODO] To be removed, not used anymore void try_hide() // Asks menu to close
PanelMenuHTML is a web view embedded in the PanelMenuBox object. More description about the view is described in the "Menu front end" section.
PanelSessionManager is a singleton object to communicate with GNOME session manager. It registers manokwari to GNOME in order to established a full desktop shell, otherwise it will be killed by GNOME session manager.
PanelSessionManager void logout() // Logouts from the session. [TODO] Will be put as private in the future. void shutdown() // Shutsdowns the desktop. [TODO] Will be put as private in the future. bool can_shutdown() // Returns whether the desktop can be shutted down. [TODO] Will be put as private in the future. [JSCORE] bool SessionManager.canShutdown() // Wrapper to can_shutdown() function above [JSCORE] void SessionManager.logout() // Wrapper to logout() function above [JSCORE] void SessionManager.shutown() // Wrapper to shutdown() function above
PanelTray is a Gtk+ widget, subclassed from GtkHBox, to display system tray items. 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.
PanelTray [SIGNAL] new_item_added() // Emitted when a system tray is added
PanelWindowPager is a widget which displays the desktop pager and the "Show desktop" button. Whenever any of the pager is chosen then the workspace is set to the associated pager. Whenever the "Show desktop" button is pressed, all visible windows will be minimized showing the desktop uncluttered. [TODO] This object could be refactored/renamed and moved to separate file.
PanelWindowPager [SIGNAL] void hidden() // Emitted when pager is hidden void reset_show_desktop() // Resets the "show desktop" button, which basically returns the visibility of unchanged windows
PanelWindowPagerEntry hosts PanelWindowPager. This widget handles a mouse press which will toggles the visibility of the pager. [TODO] This object could be refactored/renamed and moved to separate file.
PanelWindowPagerEntry void reset_show_desktop() // Ask the pager with the same function name
PanelWindowEntry is a widget showing the icon of the associated window. It acts as proxy to the window. It can maximize, minimize, 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. [TODO] This object could be refactored to separate file.
PanelWindowEntry void show_popup() // Shows context menu of common active windowing functions, such as minimize, move, and maximize.
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. [TODO] This object could be refactored/renamed and moved to separate file. [TODO] This object needs to be tested in RTL environment.
PanelWindowEntryDescription void clear_entry() // Clears the list which should be drawn void activate() // Activates the window and showing the list void deactivate() // Hides the window void update_position() // Update the position of the window [FIXME] Should be removed?
PanelWindowHost is a top level window which shows the horizontal panel on the top of the screen. This window hosts following objects:
- An icon showing distributor logo, which when clicked shows the PanelMenuBox
[TODO] This object could be refactored/renamed and moved to separate file.
PanelWindowHost [SIGNAL] windows_gone(); // Emitted when all windows have gone, either closed or minimized [SIGNAL] windows_visible() // Emitted when there is at least one window visible [SIGNAL] all_windows_visible() // Emitted when all normal windows visible [SIGNAL] dialog_opened() // Emitted when a dialog is opened [SIGNAL] menu_clicked() // Emitted when the menu is clicked void no_windows_around() // Returns whether no visible windows is visible void update() // Update the state of the objects associated with window list provided by window manager void reposition() // Update the position of the window when screen size is changed
Menu front-end (menu.js)
[TODO] To be written
Desktop front-end (desktop.js)
[TODO] To be written
PanelDesktopData is a back-end object providing interface to manage the content of the desktop. This basically provides interfaces to remove and provide list of application launcher. It monitors the Freedesktop desktop directory (~/Desktop in English locale) for changes concerning .desktop files. The interface is exposed to JSCore.
PanelPlaces is a back-end object handling GNOME's Places objects. PanelPlaces handles localized Places.
PanelUser is a back-end object which provides information about the user which owns the session.
PanelUser [PROPERTY] string icon_file read-only [PROPERTY] string real_name read-only [PROPERTY] string host_name read-only [JSCORE] string UserAccount.getIconFile() [JSCORE] string UserAccount.getRealName() [JSCORE] string UserAccount.getHostName()
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.
PanelUtils is a set of helper functions
PanelScreen is a utility static functions for handling screen.
Manokwari uses explicit X11 functions, hence may not be easily modified for used with other windowing system.
Manokwari uses session D-Bus to perform IPC to following parts of the system:
- GNOME session manager
- Freedesktop account manager
Source code structure
The structure of source code is partitioned as follows:
- src/: Contains the source code written in Vala
- vapi/: Contains custom vapi files
- po/: Contains translations files
- data/: Contains distribution files
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:
- manokwari binary is installed in /usr/bin
- manokwari.desktop is installed in /usr/share/applications
- manokwari.mo is installed in translation directory
The lifecycle of Manokwari is of as follows:
- Started by gnome-session
- Run indefinitely until any of the following occurs:
- User chose shutdown or login menu
- Manokwari is unable to respond gnome-session when asked for something via D-Bus
- Internal error which causes Manokwari to crash