homescreen/docs/homescreen_api.md

   1 # HomeScreen API\r
   2 The HomeScreen app provides an own interface for some special use cases concerning the surfaces and user inputs.\r
   3 \r
   4 The interface is implemented as D-Bus interface.\r
   5 This is the introspection, describing the interface:\r
   6 \r
   7 ```\r
   8 <node>\r
   9         <interface name="org.agl.homescreen">\r
  10                 <method name="hardKeyPressed">\r
  11                         <arg name="key" type="i" direction="in"/>\r
  12                 </method>\r
  13                 <method name="getSurfaceStatus">\r
  14                         <arg name="surfaceId" type="i" direction="in"/>\r
  15                         <arg name="status" type="i" direction="out"/>\r
  16                 </method>\r
  17                 <method name="requestSurfaceIdToFullScreen">\r
  18                         <arg name="surfaceId" type="i" direction="in"/>\r
  19                 </method>\r
  20                 <method name="getAllSurfacesOfProcess">\r
  21                         <arg name="pid" type="i" direction="in"/>\r
  22                         <arg name="surfaceIds" type="ai" direction="out"/>\r
  23                         <annotation name="org.qtproject.QtDBus.QtTypeName.Out0" value="QList&lt;int&gt;"/>\r
  24                 </method>\r
  25                 <method name="getLayoutRenderAreaForSurfaceId">\r
  26                         <arg name="surfaceId" type="i" direction="in"/>\r
  27                         <arg name="renderArea" type="(iiii)" direction="out"/>\r
  28                         <annotation name="org.qtproject.QtDBus.QtTypeName.Out0" value="QRect"/>\r
  29                 </method>\r
  30                 <method name="renderSurfaceToAreaAllowed">\r
  31                         <arg name="surfaceId" type="i" direction="in"/>\r
  32                         <arg name="layoutArea" type="i" direction="in"/>\r
  33                         <arg name="allowed" type="b" direction="out"/>\r
  34                 </method>\r
  35                 <method name="renderSurfaceToArea">\r
  36                         <arg name="surfaceId" type="i" direction="in"/>\r
  37                         <arg name="layoutArea" type="i" direction="in"/>\r
  38                 </method>\r
  39         </interface>\r
  40 </node>\r
  41 ```\r
  42 \r
  43 These interface will change during further development, so check back frequently.\r
  44 \r
  45 ## User Input Events API calls\r
  46 \r
  47 ### hardKeyPressed\r
  48 \r
  49 Use hardKeyPressed to inject hard key press events into the HomeScreen app.\r
  50 This Interface call can be used by applications like the InputEventManager to inject hard keys into the HomeScreen application.\r
  51 \r
  52 #### Example\r
  53 \r
  54 if someone presses the Hard Key “NAV” on the target, this key may be injected using this interface to make the HomeScreen launch the navigation application.\r
  55 Right now, only a few keys are defined (in inputevent.hpp):\r
  56 \r
  57 ```\r
  58 namespace InputEvent {\r
  59     typedef enum HardKey\r
  60     {\r
  61         HARDKEY_UNDEFINED,\r
  62         HARDKEY_NAV,\r
  63         HARDKEY_MEDIA\r
  64     } eHardKey;\r
  65 }\r
  66 ```\r
  67 \r
  68 This will change in the future.\r
  69  \r
  70 ![hardKeyPressed](pictures/api_hardKeyPressed.png)\r
  71  \r
  72 A “normal” application would not need to call this API.\r
  73 \r
  74 ## Surface control API calls\r
  75 \r
  76 The normal use case when starting an application is:\r
  77 The user presses a hard key or uses the app launcher to start an app. The app is then started and is shown full screen.\r
  78 The org.agl.homescreen API provides some methods to get information about some status and some methods to show surfaces on the screen.\r
  79 \r
  80 ### getSurfaceStatus\r
  81 \r
  82 A surface can be visible or invisible (please do not confuse “visible” and “visibility”). This function allows to request the current status.\r
  83 \r
  84 ```\r
  85 <method name="getSurfaceStatus">\r
  86         <arg name="surfaceId" type="i" direction="in"/>\r
  87         <arg name="status" type="i" direction="out"/>\r
  88 </method>\r
  89 ```\r
  90 \r
  91 Right now an application has to pull this information.\r
  92 This is not optimal and will change in the future. There are two options:\r
  93  - The homescreen API will provide a signal that is emitted every time the visible status of surfaces changes. This would be way more efficient, because it would save time and avoid a re-occurring API call. __UPDATE:__ There is a D-Bus signal implemented in this API\r
  94  - For Qt, there is already a patch available that provides this information as a base class property. See https://codereview.qt-project.org/#/c/176211/ This would be optimal for Qt widget applications. But not useful for other languages, e.g. Java. __UPDATE:__ This patch got reverted in AGL!\r
  95 \r
  96 #### Current implementation\r
  97  \r
  98 ![getSurfaceStatus](pictures/api_getSurfaceStatus_1.png)\r
  99  \r
 100 #### Option 1\r
 101 \r
 102 ![getSurfaceStatus](pictures/api_getSurfaceStatus_2.png)\r
 103 \r
 104 #### Option 2\r
 105 \r
 106 ![getSurfaceStatus](pictures/api_getSurfaceStatus_3.png)\r
 107 \r
 108 ### requestSurfaceIdToFullScreen\r
 109 \r
 110 This function will set the given surface to full screen.\r
 111 \r
 112 ```\r
 113 <method name="requestSurfaceIdToFullScreen">\r
 114         <arg name="surfaceId" type="i" direction="in"/>\r
 115 </method>\r
 116 ```\r
 117 \r
 118 It will hide all other surfaces.\r
 119 \r
 120 ![requestSurfaceIdToFullScreen](pictures/api_requestSurfaceIdToFullScreen.png)\r
 121  \r
 122 ### getAllSurfacesOfProcess\r
 123 \r
 124 This returns all surfaces that are created by the given process ID.\r
 125 \r
 126 ```\r
 127 <method name="getAllSurfacesOfProcess">\r
 128         <arg name="pid" type="i" direction="in"/>\r
 129         <arg name="surfaceIds" type="ai" direction="out"/>\r
 130         <annotation name="org.qtproject.QtDBus.QtTypeName.Out0" value="QList&lt;int&gt;"/>\r
 131 </method>\r
 132 ```\r
 133 \r
 134 A process can create more than one surface. By default, the surface with the lowest surface ID is shown on the screen. If an application wants to know all surfaces that were created by an application, this method will provide them.\r
 135 \r
 136 ![getAllSurfacesOfProcess](pictures/api_getAllSurfacesOfProcess.png)\r
 137 \r
 138 ### renderSurfaceToAreaAllowed\r
 139 \r
 140 Before calling renderSurfaceToArea, an application can request, if it is allowed to render the surface to this area. This makes sense for an application that would begin to allocate resources to render. But if it is not allowed to render the surface, the application could avoid allocating the resources.\r
 141 \r
 142 ```\r
 143 <method name="renderSurfaceToAreaAllowed">\r
 144         <arg name="surfaceId" type="i" direction="in"/>\r
 145         <arg name="layoutArea" type="i" direction="in"/>\r
 146         <arg name="allowed" type="b" direction="out"/>\r
 147 </method>\r
 148 ```\r
 149 \r
 150 The call will not affect the current setup, it will only request if it is allowed or not.\r
 151 \r
 152 ![renderSurfaceToAreaAllowed](pictures/api_renderSurfaceToAreaAllowed.png)\r
 153 \r
 154 ### renderSurfaceToArea\r
 155 \r
 156 By default, the HomeScreen application decides, where to render an applications surface. The concept of Layouts defines this. This API call can override the default behavior. An app can request to render a surface in a specific Layout Area.\r
 157 \r
 158 ```\r
 159 <method name="renderSurfaceToArea">\r
 160         <arg name="surfaceId" type="i" direction="in"/>\r
 161         <arg name="layoutArea" type="i" direction="in"/>\r
 162 </method>\r
 163 ```\r
 164 \r
 165 The surface that was previously rendered in this Layout are will be hidden.\r
 166 \r
 167 ![renderSurfaceToArea](pictures/api_renderSurfaceToArea.png)\r
 168 \r
 169 The homescreen interface functionality is not fully implemented, but the API is available. For example using the libhomescreen.so.\r
 170 \r
 171 ### surfaceVisibilityChanged\r
 172 \r
 173 Whenever the visibility property of a surface changes, this signal is emitted.\r
 174 \r
 175 ```\r
 176 <signal name="surfaceVisibilityChanged">\r
 177         <arg name="surfaceId" type="i"/>\r
 178         <arg name="visible" type="b"/>\r
 179 </signal>\r
 180 ```\r
 181 \r
 182 Visibility here means visible. The name of the signal is from the Weston surface property “visibility”.\r
 183 See here for reference: https://github.com/ntanibata/wayland-ivi-extension/blob/master/ivi-layermanagement-api/ilmCommon/include/ilm_types.h\r
 184  \r
 185 ![surfaceVisibilityChanged](pictures/api_surfaceVisibilityChanged.png)\r