Debian Codegraph @

liblomiri-app-launch/application.h

raw
1 /*
2 * Copyright © 2016 Canonical Ltd.
3 *
4 * This program is free software: you can redistribute it and/or modify it
5 * under the terms of the GNU General Public License version 3, as published
6 * by the Free Software Foundation.
7 *
8 * This program is distributed in the hope that it will be useful, but
9 * WITHOUT ANY WARRANTY; without even the implied warranties of
10 * MERCHANTABILITY, SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR
11 * PURPOSE. See the GNU General Public License for more details.
12 *
13 * You should have received a copy of the GNU General Public License along
14 * with this program. If not, see <http://www.gnu.org/licenses/>.
15 *
16 * Authors:
17 * Ted Gould <[email protected]>
18 */
19
20 #include <list>
21 #include <memory>
22 #include <sys/types.h>
23 #include <vector>
24
25 #include "appid.h"
26 #include "oom.h"
27 #include "type-tagger.h"
28
29 #pragma once
30 #pragma GCC visibility push(default)
31
32 namespace lomiri
33 {
34 namespace app_launch
35 {
36
37 class Registry;
38
39 /** \brief Class to represent an application, whether running or not, and
40 query more information about it.
41
42 Generally the Application object represents an Application in the system. It
43 hooks up all of it's signals, finds out information about it and controls
44 whether it is running or not. This class is what most users of Lomiri App
45 Launch will do the majority of their work.
46 */
47 class Application
48 {
49 public:
50 /** \private */
51 struct URLTag;
52 /** \private */
53 typedef TypeTagger<URLTag, std::string> URL;
54
55 /** Function to create an Application object. It determines the type of application
56 and returns a pointer to that application object. It uses the registry for
57 shared connections and is given an AppID. To find the AppID for a given
58 application use the AppID::discover() functions.
59
60 \param appid Application ID for the application
61 \param registry Shared registry to use
62 */
63 static std::shared_ptr<Application> create(const AppID& appid, const std::shared_ptr<Registry>& registry);
64
65 virtual ~Application() = default;
66
67 /* System level info */
68 /** Get the Application ID of this Application */
69 virtual AppID appId() const = 0;
70
71 /** \brief Information and metadata about the application for programs that
72 are displaying the application to users
73
74 The Info class has all the metadata including user visible strings
75 and other nicities that users expect to see about applications. For
76 most formats this is gotten from the Desktop file, but those may
77 be in different locations depending on the packaging format.
78 */
79 class Info
80 {
81 public:
82 /* Basic information */
83 /** \private */
84 struct NameTag;
85 /** \private */
86 struct DescriptionTag;
87 /** \private */
88 struct IconPathTag;
89 /** \private */
90 struct DefaultDepartmentTag;
91 /** \private */
92 struct KeywordsTag;
93 /** \private */
94 struct PopularityTag;
95
96 /** \private */
97 typedef TypeTagger<NameTag, std::string> Name;
98 /** \private */
99 typedef TypeTagger<DescriptionTag, std::string> Description;
100 /** \private */
101 typedef TypeTagger<IconPathTag, std::string> IconPath;
102 /** \private */
103 typedef TypeTagger<DefaultDepartmentTag, std::string> DefaultDepartment;
104 /** \private */
105 typedef TypeTagger<KeywordsTag, std::vector<std::string>> Keywords;
106 /** \private */
107 typedef TypeTagger<PopularityTag, unsigned int> Popularity;
108
109 virtual ~Info() = default;
110
111 /** Name of the application */
112 virtual const Name& name() = 0;
113 /** Textual description of the application */
114 virtual const Description& description() = 0;
115 /** Path to the icon that represents the application */
116 virtual const IconPath& iconPath() = 0;
117 /** Default department of the application */
118 virtual const DefaultDepartment& defaultDepartment() = 0;
119 /** Path to the screenshot of the application */
120 virtual const IconPath& screenshotPath() = 0;
121 /** List of keywords for the application */
122 virtual const Keywords& keywords() = 0;
123 /** Get the relative popularity of the application, 0 is not popular */
124 virtual const Popularity& popularity() = 0;
125
126 /** Information to be shown on the app splash screen */
127 struct Splash
128 {
129 /** \private */
130 struct TitleTag;
131 /** \private */
132 struct ImageTag;
133 /** \private */
134 struct ColorTag;
135 /** \private */
136 struct ShowHeaderTag;
137 /** \private */
138 struct ShowTag;
139
140 /** \private */
141 typedef TypeTagger<TitleTag, std::string> Title;
142 /** \private */
143 typedef TypeTagger<ImageTag, std::string> Image;
144 /** \private */
145 typedef TypeTagger<ColorTag, std::string> Color;
146 /** \private */
147 typedef TypeTagger<ShowHeaderTag, bool> ShowHeader;
148 /** \private */
149 typedef TypeTagger<ShowTag, bool> Show;
150
151 /** Title text on the screen */
152 Title title;
153 /** Image to put on the screen */
154 Image image;
155 /** Color of the background */
156 Color backgroundColor;
157 /** Color of the header (if shown) */
158 Color headerColor;
159 /** Color of the footer */
160 Color footerColor;
161 /** Whether the standard UI Toolkit header should be shown */
162 ShowHeader showHeader;
163 /** If the splash should be shown**/
164 Show show;
165 };
166
167 /** Get information for the splash screen */
168 virtual Splash splash() = 0;
169
170 /** Orientation and placement */
171 struct Orientations
172 {
173 /** Can support portrait */
174 bool portrait;
175 /** Can support landscape */
176 bool landscape;
177 /** Can support inverted portrait */
178 bool invertedPortrait;
179 /** Can support inverted landscape */
180 bool invertedLandscape;
181
182 /** Check to see if two Orientations are the same */
183 bool operator==(const Orientations& b) const
184 {
185 return portrait == b.portrait && landscape == b.landscape && invertedPortrait == b.invertedPortrait &&
186 invertedLandscape == b.invertedLandscape;
187 }
188 };
189
190 /** \private */
191 struct RotatesWindowTag;
192
193 /** \private */
194 typedef TypeTagger<RotatesWindowTag, bool> RotatesWindow;
195
196 /** Return which orientations are supported */
197 virtual Orientations supportedOrientations() = 0;
198 /** Return whether the window contents can be rotated or not */
199 virtual RotatesWindow rotatesWindowContents() = 0;
200
201 /* Lifecycle */
202 /** \private */
203 struct LomiriLifecycleTag;
204
205 /** \private */
206 typedef TypeTagger<LomiriLifecycleTag, bool> LomiriLifecycle;
207
208 /* Return whether the Lomiri Lifecycle is supported by this application */
209 virtual LomiriLifecycle supportsLomiriLifecycle() = 0;
210 };
211
212 /** Get a Application::Info object to describe the metadata for this
213 application */
214 virtual std::shared_ptr<Info> info() = 0;
215
216 /** Interface representing the information about a specific application
217 running instance. This includes information on the PIDs that make
218 up the Application::Instance. */
219 class Instance
220 {
221 public:
222 virtual ~Instance() = default;
223
224 /* Query lifecycle */
225 /** Check to see if the instance is currently running. The object can
226 exist even after the instance has stopped running. */
227 virtual bool isRunning() = 0;
228
229 /* Instance Info */
230 /* PIDs */
231 /** Get the primary PID for this Application::Instance, this will return
232 zero when it is not running. The primary PID is the PID keeping the
233 instance alive, when it exists the others get reaped. */
234 virtual pid_t primaryPid() = 0;
235 /** Check to see if a PID is in the cgroup for this application instance.
236 Each application instance tracks all the PIDs that are currently being
237 used */
238 virtual bool hasPid(pid_t pid) = 0;
239 /** Check to see if a specific PID is part of this Application::Instance */
240 virtual std::vector<pid_t> pids() = 0;
241
242 /* OOM Adjustment */
243 /** Sets the value of the OOM Adjust kernel property for the all of
244 the processes this instance. */
245 virtual void setOomAdjustment(const oom::Score score) = 0;
246 /** Gets the value of the OOM Adjust kernel property for the primary process
247 of this instance.
248
249 \note This function does not check all the processes and ensure they are
250 consistent, it just checks the primary and assumes that.
251 */
252 virtual oom::Score getOomAdjustment() = 0;
253
254 /* Manage lifecycle */
255 /** Pause, or send SIGSTOP, to the PIDs in this Application::Instance */
256 virtual void pause() = 0;
257 /** Resume, or send SIGCONT, to the PIDs in this Application::Instance */
258 virtual void resume() = 0;
259 /** Stop, or send SIGTERM, to the PIDs in this Application::Instance, if
260 the PIDs do not respond to the SIGTERM they will be SIGKILL'd */
261 virtual void stop() = 0;
262 /** Signal the shell to focus the Application::Instance */
263 virtual void focus() = 0;
264
265 bool operator==(const Instance& b) const;
266 bool operator!=(const Instance& b) const;
267 };
268
269 /** A quick check to see if this application has any running instances */
270 virtual bool hasInstances() = 0;
271 /** Get a vector of the running instances of this application */
272 virtual std::vector<std::shared_ptr<Instance>> instances() = 0;
273
274 /** Start an application, optionally with URLs to pass to it.
275
276 \param urls A list of URLs to pass to the application command line
277 */
278 virtual std::shared_ptr<Instance> launch(const std::vector<URL>& urls = {}) = 0;
279 /** Start an application with text flags, optionally with URLs to
280 pass to it.
281
282 \param urls A list of URLs to pass to the application command line
283 */
284 virtual std::shared_ptr<Instance> launchTest(const std::vector<URL>& urls = {}) = 0;
285
286 /** Get a a pointer to the running instances of this application based on the pid
287
288 \param pid The pid to find the instance of
289 */
290 virtual std::shared_ptr<Instance> findInstance(const pid_t& pid) = 0;
291
292 bool operator==(const Application& b) const;
293 bool operator!=(const Application& b) const;
294 };
295
296 } // namespace app_launch
297 } // namespace lomiri
298
299 #pragma GCC visibility pop