From a982b77bbb2a1a7ccf8f161311dc133265bb2610 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonatan=20P=C3=A5lsson?= Date: Wed, 12 Mar 2014 14:14:37 +0100 Subject: Added initial version of design document --- .gitmodules | 9 + documentation/designdocument/Makefile | 2 + documentation/designdocument/README | 11 + documentation/designdocument/browser.tex | 423 ++++++++++++++++++++++++++ documentation/designdocument/cls | 1 + documentation/designdocument/genivi.png | Bin 0 -> 261894 bytes documentation/designdocument/genivi_small.eps | Bin 0 -> 569186 bytes 7 files changed, 446 insertions(+) create mode 100644 .gitmodules create mode 100644 documentation/designdocument/Makefile create mode 100644 documentation/designdocument/README create mode 100644 documentation/designdocument/browser.tex create mode 160000 documentation/designdocument/cls create mode 100644 documentation/designdocument/genivi.png create mode 100644 documentation/designdocument/genivi_small.eps diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..91c7f45 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,9 @@ +[submodule "documentation/designdocument/Pelagicore-LaTeX-Class"] + path = documentation/designdocument/Pelagicore-LaTeX-Class + url = git@github.com:Pelagicore/Pelagicore-LaTeX-Class.git +[submodule "documentation/designdocument/--name"] + path = documentation/designdocument/--name + url = git@github.com:Pelagicore/Pelagicore-LaTeX-Class.git +[submodule "documentation/designdocument/cls"] + path = documentation/designdocument/cls + url = git@github.com:Pelagicore/Pelagicore-LaTeX-Class.git diff --git a/documentation/designdocument/Makefile b/documentation/designdocument/Makefile new file mode 100644 index 0000000..5536410 --- /dev/null +++ b/documentation/designdocument/Makefile @@ -0,0 +1,2 @@ +document: + TEXINPUTS=cls/:${TEXINPUTS} pdflatex browser.tex diff --git a/documentation/designdocument/README b/documentation/designdocument/README new file mode 100644 index 0000000..04754d6 --- /dev/null +++ b/documentation/designdocument/README @@ -0,0 +1,11 @@ +In order to build this documentation, the Pelagicore LaTeX class is expected to +be provided in the cls/ subdirectory. An easy way to obtain and install this +class is to initialize it as a git submodule: + +git submodule add git@github.com:Pelagicore/Pelagicore-LaTeX-Class.git cls + +The document should then build with: + +make + +All GENIVI logos are owned and copyrighted by GENIVI diff --git a/documentation/designdocument/browser.tex b/documentation/designdocument/browser.tex new file mode 100644 index 0000000..b61f6a3 --- /dev/null +++ b/documentation/designdocument/browser.tex @@ -0,0 +1,423 @@ +\documentclass{pelagicore} + +\begin{document} +\title {GENIVI Browser} +\subtitle {Proof of Concept} +\revision{0.4} +\revisiondate{\today} +\author{Marcel Schuette, Pelagicore} +\lang{EN} +\approvedby{Marcel Schuette} +\location{Munich, Germany} +\filename{\jobname} +\docnumber{1} +\frontlogofile{genivi.png} +\bannerlogofile{genivi_small.eps} +\bannerlogoheight{0.5in} +\usefrontmetadatatrue +\company{GENIVI} + +\maketitle +\tableofcontents \clearpage + +\section{Introduction and project background} +The GENIVI Networking Expert Group (NW-EG) would like to exercise a D-Bus-based +software component to test the usability and quality of a web browser that uses +the D-Bus interface. Therefore the expert group instructed a browser +Proof-of-Concept (PoC) to be executed to evaluate existing APIs and concepts. + +\section{Scope of this document} + +This document should give an overview about the architecture of the GENIVI +Browser PoC and details about the various components and their implementation. +With that document, it should be possible to understand the source code more +easily and get a better understanding of the used concept. Nevertheless the +document doesn’t replace reading the source code. + +\section{Requirements} + +The NW-EG defined a set of D-Bus APIs between the browser application and the +HMI. These D-Bus APIs were provided as XML files. In addition, a header with +definitions of specific types and structures were provided prior to project +start. +\\\\ +The NW-EG defined the following requirements: + +\subsection{General Requirements} +\begin{tabularx}{\textwidth}{| p{4em} | p{6.5em} | X |} + \hline + \rowcolor{blue} + \bf ID & \bf Requirement & \bf Description \\ + \hline + SW-BRW-POC-001 & Environment & The proof of concept must run under Ubuntu + Linux 12.04 in a Virtual Box virtual + machine installed on a desktop PC. \\ + \hline + SW-BRW-POC-002 & Environment & The implementation of the browser PoC will + be done using the Qt 5 package which is + under the LGPL v2.1 license. \\ + \hline + SW-BRW-POC-003 & Documentation & Documentation describing how to install + the software and run a set of acceptance + tests shall be provided \\ + \hline +\end{tabularx} + +\subsection{Architecture} +\begin{tabularx}{\textwidth}{|p{4em} | p{6.5em} | X |} + \hline + \rowcolor{blue} + \bf ID & \bf Requirement & \bf Description \\ + \hline + SW-BRW-POC-004 & Separation of Browser HMI and Browser-Core & + The Browser shall be separated in HMI and Browser Core. + A provided Qt-based test-HMI will control the Browser Core. \\ + \hline + SW-BRW-POC-005 & Test-HMI as Separate Process & + The provided test-HMI application will run as an independent process.\\ + \hline + SW-BRW-POC-006 & Qt Webkit 1 implementation & + The Browser PoC application must use the Qt5 Webkit1 implementation.\\ + \hline +\end{tabularx} + +\subsection{Browser Interfaces} +\begin{tabularx}{\textwidth}{|p{4em} | p{6.5em} | X |} + \hline + \rowcolor{blue} + \bf ID & \bf Requirement & \bf Description \\ + \hline + SW-BRW-POC-007 & D-Bus API & The Browser PoC shall implement the specified + APIs as handed over in xml-form (see + interfaces section)\\ + \hline +\end{tabularx} + +\subsection{Interfaces} +The following D-Bus interfaces files were provided as input to the project: + +\begin{enumerate} + \item IBrowser.xml + \item IWebPageWindow.xml + \item IUserInput.xml + \item IBookmarkManager.xml +\end{enumerate} + +These interfaces represent a subset of the GENIVI APIs defined by NW-EG and +contains only methods and signals, which has to be supported by the PoC. The +XML files can be found in the repository +(\url{http://git.projects.genivi.org/browser-poc.git/}) in the folder {\tt +/common}. For detailed information about the methods and signals for D-Bus +interfaces were defined, you can have a look at the files in the repository. + +\section{Overview} +Following the requirements, the GENIVI Browser PoC is implemented with Qt 5 and +Qt Webkit 1. Although existing projects like the snowshoe browser were taken +into account, a `from scratch' approach was chosen. The specific requirements +of the project made a re-use of an existing project not appropriate, as a +reduction of efforts was not expected. +\\\\ +The GENIVI Browser PoC consists of following components, which are also represented in +separate folders in the repository: + +\begin{itemize} + \item A browser application + \item A test user-interface application (testUI) + \item A demo user-interface application (demoUI) + \item A folder with common components +\end{itemize} + +According to the defined architecture the browser application, which is +responsible for web page rendering and bookmark management, is separated from +the HMI (represented by the demoUI application and the testUI application). For +more detailed information about the architecture defined by NW-EG, you can have +a look at the group's wiki page +(\url{https://collab.genivi.org/wiki/display/genivi/Networking+Expert+Group}). + +For instructions, how to build all applications or only a single application, +refer to the file {\tt BUILDINSTRUCTIONS} in the repository. + +\section {Common part} +here is a common part in the project, which contains files, which are shared by +all applications. This common part is represented in the repository in the +folder {\tt /common}: + +\begin{itemize} + \item The XML files describing the interfaces + \item A class defining a bookmark object (bookmark.h|cpp) + \item A class defining the D-Bus interfaces on client side (demoUI and test + application) (browserdbus.h|cpp) + \item A header file defining common types and structures (browserdefs.h) +\end{itemize} + +The XML files are used to automatically generate the interface classes for +client and server. Via the generated interfaces of these classes, the clients +can call remote objects in the server via D-Bus. + +\section{Browser Application} +\subsection{Introduction} +The Browser application is the core part of the PoC. It is responsible for +rendering and displaying a webpage with the qml webview element. It also +implements the defined server side interfaces for {\tt IBrowser, IUserInput, +IWebPageWindow} and {\tt IBookmarkManager}. The bookmark manager includes also +logic for persistent bookmark storage in the system. + +\subsection{Usage} +The browser application always needs to be started before the user-interface +application (demoUI or testUI) is started, because it creates the D-Bus +connection. As the window will be created by the user-interface application, no +window is shown at application start. You can add an instance id as parameter +to the application start, e.g. {\tt ./browser 23}. The instance id will be +added to D-Bus service name, e.g. {\tt genivi.poc.browser23}. If no parameter +is given, a default instance id 1 is used. + +\subsection{Structure} +The source code of the browser application can to be found in the {\tt +/browser} folder in the repository: +\\\\ +\begin{tabular}{l l} + *.cpp, *.h & source and header files \\ + browser.pro & Qt project file \\ + {\tt qml/browser/} & main.qml file +\end{tabular} + +\subsection{Implementation} +The browser application is implemented using Qt Quick 1 and Qt Webkit 1. Qt +Quick 1 needed to be used, because of the requirement to use Qt Webkit 1. + +The main.qml file provides a Qt Webkit 1 webview element (wrapped in a +Flickable to be able to scroll a page). The main task is the definition of +interfaces (functions, properties, signals) to communicate with the C++ part of +the application. From a UI perspective, the main.qml doesn’t provide a lot of +UI features, except for the webview itself. + +There is one class available for each defined interface group (XML file) +implementing the functions for the defined interfaces on server side. These +functions interact with the interfaces provided by the qml file. + +As a central class the browserhelper class creates the connection to D-Bus on +the session bus and registers a service name on the D-Bus server. The default +service name for the GENIVI browser PoC is genivi.poc.browser + instance id, +e.g. genivi.poc.browser23. The default instance id is 1, if no parameter is +given, or the parameter given at application start. + +The class also creates all interface objects and D-Bus interface adaptors, +registers needed types with the D-Bus system and registers the browser and +bookmark interface class with the D-Bus connection under an object path +(/Browser/IBrowser and /Browser/IBookmarkManager). The interface for +webpagewindow and userinput will be registered, when a new page is actually +created. + +Bookmarkmanager.h|cpp implements the IBookmarkManager interfaces and manages +persistent storage of bookmarks. + +Userinput.h|cpp implements the IUserInput interfaces. + +Browser.h|cpp implements the IBrowser interfaces, creates and set up a +declarative view with the main qml file (the webview) and registers +webpagewindow and userinput objects under a unique object path +(/Browser/IWebPageWindow + window handle resp. + +/Browser/IWebPageWindow + window handle/IUserInput). This is needed to control +different webpages or tabs (created by the createPageWindow interface) with the +testUI application. That means e.g. routing a reload command to the right +webpage window. + +\section{Test Application} +\subsection{Introduction} +With the test user-interface application, you are able to test all implemented +interfaces with all defined parameters. For this purpose, not the UI design of +the application was the key requirement, but the possibility to test the +functionality. This test application was also used to do manual tests, which +resulted in a test report +(\url{https://collab.genivi.org/wiki/display/genivi/Browser+Proof-Of-Concept+- ++Web+content#BrowserProof-Of-Concept-Webcontent-Testreport}). + +\begin{figure}[!ht] + \center + \includegraphics[width=0.8\textwidth]{testui.png} + \caption{The picture above shows the testUI application with the bookmark + manager tab visible.} +\end{figure} + +\subsection{Usage} +Before the testUI application is started, the browser application must be +started. At startup only the bar on the top is visible, not the tabs or +buttons. First the testUI must connect to the D-Bus service. Therefore add the +correct instance id and press the connect button. The instance id is defined +with the browser application start, either 1 as default or the number given as +parameter at browser start. + +The testUI application shows four tabs, representing the four interface groups +({\tt IBook\-mark\-Manager}, {\tt IBrowser}, {\tt IUserInput}, {\tt +IWebPageWindow}). To navigate between the groups, just press on the tab +header. + +On each page (or tab) each defined interface with its parameter is visually +grouped within a small frame. Each group consists of a button and optional +input fields, spin boxes or combo boxes, depending on the definition of the +parameters. By pressing the button of a group, the client calls a D-Bus +interface with given parameters, which calls a remote object on the server +side. + +To be able to handle more than one opened window (e.g. redirect a press on the +reload button to the right window) with the testUI application, four buttons +(numbered from 1 to 4) were added to the bar on the top. For simplicity reasons +the buttons are limited to four, means only four windows can be managed with +the testUI application. The numbers on the buttons refer to the sequence the +windows were opened. E.g., if you want to reload the third opened window, first +press button 3 and then the reload button on the IWebPageWindow tab. + +\subsection{Structure} +The source code of the test user-interface application can to be found in the +{\tt /testapp} folder in the repository: +\\\\ +\begin{tabularx}{0.9\textwidth}{l X} + main.cpp & mainsource file \\ + testapp.pro & Qt project file \\ + {\tt qml/testapp/*} & QML files for user interface \\ + {\tt images/*} & Images used in implementation (icons taken from KDE + oxygen theme 4.10.3) +\end{tabularx} +\\\\ + +\subsection{Implementation} +The testUI application supports all interfaces described in the XML files. + +The testUI application is implemented as a Qt Quick 2 application. The +user-interface is described with qml using Qt Quick Controls (reusable UI +controls provided by Qt 5.1). Besides the main.qml file, which describes the +main view with all tabs, each interface group is described in a separate qml +file. The backend logic of the testUI application is written in C++. The main +task of the C++ part is to set up the view for qml, load the qml file and +register custom C++ type in the qml system (bookmark and browserdbus classes). +The browserdbus class represents the D-Bus interface for the client. It creates +the D-Bus channel connections, registers custom types with the QtDBustype system +and defines and calls all D-Bus interfaces and handles the return values. The +output of all return values, resulting from D-Bus remote object calls, is logged +onto the console. + +A new D-Bus interface method {\tt getCurrentUrlAndTitle} was added to the +IWebPageWindow group. This method returns the current url and title of a web +page to the calling client. That was needed to store the url and title for a +bookmark and show the correct url in the input field of a user-interface +application. According to the NW-EG that interface is already defined, but was +stripped out of the delivered XML files for this Browser PoC project. + +\section{Demo User-Interface} +\subsection {Introduction} +The idea of the demo user-interface application is to have a user-interface, +which looks more like a possible real browser user-interface (other than the +testUI application) and can be used to demonstrate the GENIVI Browser PoC at +shows and events. The demoUI application doesn’t support the full set of +defined interfaces, but only a subset needed to demonstrate the used features. +The chosen features were selected to be the main features known from common web +browsers. + +\begin{figure}[!ht] + \center + \includegraphics[width=0.8\textwidth]{demoui.png} + \caption{The picture above shows the demo user-interface application with + open bookmarks pane. The website shown in the background is part + of the browser application.} +\end{figure} + +The demoUI supports the following features: +\begin{itemize} + \item loading a web page defined by a URL + \item bookmark management (add, select, delete and delete all bookmarks) + \item navigation back and forward in the browser history + \item reload and stop loading a web page + \item display a progress bar representing the loading progress of a web page + (displayed below the URL in the input field) + \item keypad navigation on web page with keyboard navigation keys +\end{itemize} + +\subsection{Usage} +Before the demoUI application is started, the browser application must be +started. With the start of the demoUI application, also the browser application +becomes visible. The two applications (browser and demoUI) are arranged in a +seamless way, to represent the look of only one application. + +he icons in the demoUI are hopefully self-explaining and known from other web +browser user-interfaces. To load an URL type the URL in the input field on the +top and press the enter key on an attached keyboard. The two top-right icons +represent `add bookmark to bookmark list' and `show bookmark list' +functionality. If the bookmark pane is open, you can select bookmarks to be +loaded in the webview, delete individual bookmarks by pressing the red `minus' +icon at the front of a bookmark or delete all bookmarks with the red button on +the bottom of the pane. For keypad navigation on webpages, the up-, down-, +right- or left-key (line mode) or the space bar (page down) and tab key (page +up) (page mode) can be pressed. It's important that the demoUI application has +the focus to receive the key presses. To activate a link on a web page or move +the web page, the browser application window can be directly accessed. These +actions are not handled over a D-Bus interface. + +\subsection{Structure} +The source code of the demo user-interface application can to be found in the +{\tt /demoui} folder in the repository: +\\\\ +\begin{tabularx}{0.9\textwidth}{l X} + main.cpp & mainsource file \\ + demoui.pro & Qt project file \\ + {\tt qml/demoui/*} & QML files for user interface \\ + {\tt qtquick2application/*} & Classes for displaying a QtQuick UI \\ + {\tt images/*} & Images used in implementation (icons taken + from KDE oxygen theme 4.10.3) +\end{tabularx} +\\\\ + +\subsection{Implementation} +The demoUI supports the following D-Bus interfaces: +\begin{itemize} + \item IBrowser + \begin{itemize} + \item createPageWindow (with fixed parameters) + \end{itemize} + \item IWebPageWindow + \begin{itemize} + \item load + \item reload + \item stop + \item back + \item forward + \item scroll (line or page scrolling) + \item onLoadStarted + \item onLoadProgress + \item onLoadFinished + \end{itemize} + \item IBookmarkManager + \begin{itemize} + \item addItem (with url and title, all other parameter fix) + \item getItems (with fixed parameters) + \item deleteItem + \item deleteAllItems (with fixed parameters) + \end{itemize} +\end{itemize} + +The demoUI is implemented as Qt Quick 2 application. The user-interface is +described with qml. The backend logic of the demoUI is done in C++. Main task +of the C++ part is to set up the view for qml, load the qml file, register +custom C++ type in the qml system (bookmark and browserdbus classes). The +browserdbus class represents the D-Bus interface for the client. It creates the +D-Bus channel connections, registers custom types with the QtDBustype system +and defines and calls all D-Bus interfaces and handles the return values. The +output of all return values, resulting from D-Bus remote object calls, is logged +onto the console. + +A new D-Bus interface method {\tt getCurrentUrlAndTitle} was added to the +IWebPageWindow group. This method returns the current url and title of a web +page to the calling client. That was needed to store the url and title for a +bookmark and show the correct url in the input field of a user-interface +application. According to the NW-EG that interface is already defined, but was +stripped out for this Browser PoC project. + +If the bookmark pane is open, the demoUI application (geometry) is resized. The +height of the application is changed. This resize is needed, to show the pane, +which has the height of the complete browser, and to allow (if closed) getting +access to the browser window (e.g. pressing on links on the browser window). +Otherwise the above lying application with the focus (even if parts of the +application are transparent) would get all mouse and key events and it wouldn’t +be possible to click on links on a web page. + +\end{document} diff --git a/documentation/designdocument/cls b/documentation/designdocument/cls new file mode 160000 index 0000000..6fd278a --- /dev/null +++ b/documentation/designdocument/cls @@ -0,0 +1 @@ +Subproject commit 6fd278af12477a1d3df4a06118a64163cc397f7f diff --git a/documentation/designdocument/genivi.png b/documentation/designdocument/genivi.png new file mode 100644 index 0000000..4594235 Binary files /dev/null and b/documentation/designdocument/genivi.png differ diff --git a/documentation/designdocument/genivi_small.eps b/documentation/designdocument/genivi_small.eps new file mode 100644 index 0000000..6225d21 Binary files /dev/null and b/documentation/designdocument/genivi_small.eps differ -- cgit v1.2.1