Mercurial > libervia-backend

comparison libervia/frontends/quick_frontend/quick_menus.py @ 4074:26b7ed2817da

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
refactoring: rename `sat_frontends` to `libervia.frontends`
author Goffi <goffi@goffi.org>
date Fri, 02 Jun 2023 14:12:38 +0200
parents sat_frontends/quick_frontend/quick_menus.py@4b842c1fb686
children
comparison
equal deleted inserted replaced
4073:7c5654c54fed 4074:26b7ed2817da
1 #!/usr/bin/env python3
2
3
4 # helper class for making a SAT frontend
5 # Copyright (C) 2009-2021 Jérôme Poisson (goffi@goffi.org)
6
7 # This program is free software: you can redistribute it and/or modify
8 # it under the terms of the GNU Affero General Public License as published by
9 # the Free Software Foundation, either version 3 of the License, or
10 # (at your option) any later version.
11
12 # This program is distributed in the hope that it will be useful,
13 # but WITHOUT ANY WARRANTY; without even the implied warranty of
14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 # GNU Affero General Public License for more details.
16
17 # You should have received a copy of the GNU Affero General Public License
18 # along with this program. If not, see <http://www.gnu.org/licenses/>.
19
20 try:
21 # FIXME: to be removed when an acceptable solution is here
22 str("") # XXX: unicode doesn't exist in pyjamas
23 except (
24 TypeError,
25 AttributeError,
26 ): # Error raised is not the same depending on pyjsbuild options
27 str = str
28
29 from libervia.backend.core.log import getLogger
30 from libervia.backend.core.i18n import _, language_switch
31
32 log = getLogger(__name__)
33 from libervia.frontends.quick_frontend.constants import Const as C
34 from collections import OrderedDict
35
36
37 ## items ##
38
39
40 class MenuBase(object):
41 ACTIVE = True
42
43 def __init__(self, name, extra=None):
44 """
45 @param name(unicode): canonical name of the item
46 @param extra(dict[unicode, unicode], None): same as in [add_menus]
47 """
48 self._name = name
49 self.set_extra(extra)
50
51 @property
52 def canonical(self):
53 """Return the canonical name of the container, used to identify it"""
54 return self._name
55
56 @property
57 def name(self):
58 """Return the name of the container, can be translated"""
59 return self._name
60
61 def set_extra(self, extra):
62 if extra is None:
63 extra = {}
64 self.icon = extra.get("icon")
65
66
67 class MenuItem(MenuBase):
68 """A callable item in the menu"""
69
70 CALLABLE = False
71
72 def __init__(self, name, name_i18n, extra=None, type_=None):
73 """
74 @param name(unicode): canonical name of the item
75 @param name_i18n(unicode): translated name of the item
76 @param extra(dict[unicode, unicode], None): same as in [add_menus]
77 @param type_(unicode): same as in [sat.core.sat_main.SAT.import_menu]
78 """
79 MenuBase.__init__(self, name, extra)
80 self._name_i18n = name_i18n if name_i18n else name
81 self.type = type_
82
83 @property
84 def name(self):
85 return self._name_i18n
86
87 def collect_data(self, caller):
88 """Get data according to data_collector
89
90 @param caller: Menu caller
91 """
92 assert self.type is not None # if data collector are used, type must be set
93 data_collector = QuickMenusManager.get_data_collector(self.type)
94
95 if data_collector is None:
96 return {}
97
98 elif callable(data_collector):
99 return data_collector(caller, self.name)
100
101 else:
102 if caller is None:
103 log.error("Caller can't be None with a dictionary as data_collector")
104 return {}
105 data = {}
106 for data_key, caller_attr in data_collector.items():
107 data[data_key] = str(getattr(caller, caller_attr))
108 return data
109
110 def call(self, caller, profile=C.PROF_KEY_NONE):
111 """Execute the menu item
112
113 @param caller: instance linked to the menu
114 @param profile: %(doc_profile)s
115 """
116 raise NotImplementedError
117
118
119 class MenuItemDistant(MenuItem):
120 """A MenuItem with a distant callback"""
121
122 CALLABLE = True
123
124 def __init__(self, host, type_, name, name_i18n, id_, extra=None):
125 """
126 @param host: %(doc_host)s
127 @param type_(unicode): same as in [sat.core.sat_main.SAT.import_menu]
128 @param name(unicode): canonical name of the item
129 @param name_i18n(unicode): translated name of the item
130 @param id_(unicode): id of the distant callback
131 @param extra(dict[unicode, unicode], None): same as in [add_menus]
132 """
133 MenuItem.__init__(self, name, name_i18n, extra, type_)
134 self.host = host
135 self.id = id_
136
137 def call(self, caller, profile=C.PROF_KEY_NONE):
138 data = self.collect_data(caller)
139 log.debug("data collected: %s" % data)
140 self.host.action_launch(self.id, data, profile=profile)
141
142
143 class MenuItemLocal(MenuItem):
144 """A MenuItem with a local callback"""
145
146 CALLABLE = True
147
148 def __init__(self, type_, name, name_i18n, callback, extra=None):
149 """
150 @param type_(unicode): same as in [sat.core.sat_main.SAT.import_menu]
151 @param name(unicode): canonical name of the item
152 @param name_i18n(unicode): translated name of the item
153 @param callback(callable): local callback.
154 Will be called with no argument if data_collector is None
155 and with caller, profile, and requested data otherwise
156 @param extra(dict[unicode, unicode], None): same as in [add_menus]
157 """
158 MenuItem.__init__(self, name, name_i18n, extra, type_)
159 self.callback = callback
160
161 def call(self, caller, profile=C.PROF_KEY_NONE):
162 data_collector = QuickMenusManager.get_data_collector(self.type)
163 if data_collector is None:
164 # FIXME: would not it be better if caller and profile where used as arguments?
165 self.callback()
166 else:
167 self.callback(caller, self.collect_data(caller), profile)
168
169
170 class MenuHook(MenuItemLocal):
171 """A MenuItem which replace an expected item from backend"""
172
173 pass
174
175
176 class MenuPlaceHolder(MenuItem):
177 """A non existant menu which is used to keep a position"""
178
179 ACTIVE = False
180
181 def __init__(self, name):
182 MenuItem.__init__(self, name, name)
183
184
185 class MenuSeparator(MenuItem):
186 """A separation between items/categories"""
187
188 SEP_IDX = 0
189
190 def __init__(self):
191 MenuSeparator.SEP_IDX += 1
192 name = "___separator_{}".format(MenuSeparator.SEP_IDX)
193 MenuItem.__init__(self, name, name)
194
195
196 ## containers ##
197
198
199 class MenuContainer(MenuBase):
200 def __init__(self, name, extra=None):
201 MenuBase.__init__(self, name, extra)
202 self._items = OrderedDict()
203
204 def __len__(self):
205 return len(self._items)
206
207 def __contains__(self, item):
208 return item.canonical in self._items
209
210 def __iter__(self):
211 return iter(self._items.values())
212
213 def __getitem__(self, item):
214 try:
215 return self._items[item.canonical]
216 except KeyError:
217 raise KeyError(item)
218
219 def get_or_create(self, item):
220 log.debug(
221 "MenuContainer get_or_create: item=%s name=%s\nlist=%s"
222 % (item, item.canonical, list(self._items.keys()))
223 )
224 try:
225 return self[item]
226 except KeyError:
227 self.append(item)
228 return item
229
230 def get_active_menus(self):
231 """Return an iterator on active children"""
232 for child in self._items.values():
233 if child.ACTIVE:
234 yield child
235
236 def append(self, item):
237 """add an item at the end of current ones
238
239 @param item: instance of MenuBase (must be unique in container)
240 """
241 assert isinstance(item, MenuItem) or isinstance(item, MenuContainer)
242 assert item.canonical not in self._items
243 self._items[item.canonical] = item
244
245 def replace(self, item):
246 """add an item at the end of current ones or replace an existing one"""
247 self._items[item.canonical] = item
248
249
250 class MenuCategory(MenuContainer):
251 """A category which can hold other menus or categories"""
252
253 def __init__(self, name, name_i18n=None, extra=None):
254 """
255 @param name(unicode): canonical name
256 @param name_i18n(unicode, None): translated name
257 @param icon(unicode, None): same as in MenuBase.__init__
258 """
259 log.debug("creating menuCategory %s with extra %s" % (name, extra))
260 MenuContainer.__init__(self, name, extra)
261 self._name_i18n = name_i18n or name
262
263 @property
264 def name(self):
265 return self._name_i18n
266
267
268 class MenuType(MenuContainer):
269 """A type which can hold other menus or categories"""
270
271 pass
272
273
274 ## manager ##
275
276
277 class QuickMenusManager(object):
278 """Manage all the menus"""
279
280 _data_collectors = {
281 C.MENU_GLOBAL: None
282 } # No data is associated with C.MENU_GLOBAL items
283
284 def __init__(self, host, menus=None, language=None):
285 """
286 @param host: %(doc_host)s
287 @param menus(iterable): menus as in [add_menus]
288 @param language: same as in [i18n.language_switch]
289 """
290 self.host = host
291 MenuBase.host = host
292 self.language = language
293 self.menus = {}
294 if menus is not None:
295 self.add_menus(menus)
296
297 def _get_path_i_1_8_n(self, path):
298 """Return translated version of path"""
299 language_switch(self.language)
300 path_i18n = [_(elt) for elt in path]
301 language_switch()
302 return path_i18n
303
304 def _create_categories(self, type_, path, path_i18n=None, top_extra=None):
305 """Create catogories of the path
306
307 @param type_(unicode): same as in [sat.core.sat_main.SAT.import_menu]
308 @param path(list[unicode]): same as in [sat.core.sat_main.SAT.import_menu]
309 @param path_i18n(list[unicode], None): translated menu path (same lenght as path) or None to get deferred translation of path
310 @param top_extra: extra data to use on the first element of path only. If the first element already exists and is reused, top_extra will be ignored (you'll have to manually change it if you really want to).
311 @return (MenuContainer): last category created, or MenuType if path is empty
312 """
313 if path_i18n is None:
314 path_i18n = self._get_path_i_1_8_n(path)
315 assert len(path) == len(path_i18n)
316 menu_container = self.menus.setdefault(type_, MenuType(type_))
317
318 for idx, category in enumerate(path):
319 menu_category = MenuCategory(category, path_i18n[idx], extra=top_extra)
320 menu_container = menu_container.get_or_create(menu_category)
321 top_extra = None
322
323 return menu_container
324
325 @staticmethod
326 def add_data_collector(type_, data_collector):
327 """Associate a data collector to a menu type
328
329 A data collector is a method or a map which allow to collect context data to construct the dictionnary which will be sent to the bridge method managing the menu item.
330 @param type_(unicode): same as in [sat.core.sat_main.SAT.import_menu]
331 @param data_collector(dict[unicode,unicode], callable, None): can be:
332 - a dict which map data name to local name.
333 The attribute named after the dict values will be getted from caller, and put in data.
334 e.g.: if data_collector={'room_jid':'target'}, then the "room_jid" data will be the value of the "target" attribute of the caller.
335 - a callable which must return the data dictionnary. callable will have caller and item name as argument
336 - None: an empty dict will be used
337 """
338 QuickMenusManager._data_collectors[type_] = data_collector
339
340 @staticmethod
341 def get_data_collector(type_):
342 """Get data_collector associated to type_
343
344 @param type_(unicode): same as in [sat.core.sat_main.SAT.import_menu]
345 @return (callable, dict, None): data_collector
346 """
347 try:
348 return QuickMenusManager._data_collectors[type_]
349 except KeyError:
350 log.error("No data collector registered for {}".format(type_))
351 return None
352
353 def add_menu_item(self, type_, path, item, path_i18n=None, top_extra=None):
354 """Add a MenuItemBase instance
355
356 @param type_(unicode): same as in [sat.core.sat_main.SAT.import_menu]
357 @param path(list[unicode]): same as in [sat.core.sat_main.SAT.import_menu], stop at the last parent category
358 @param item(MenuItem): a instancied item
359 @param path_i18n(list[unicode],None): translated menu path (same lenght as path) or None to use deferred translation of path
360 @param top_extra: same as in [_create_categories]
361 """
362 if path_i18n is None:
363 path_i18n = self._get_path_i_1_8_n(path)
364 assert path and len(path) == len(path_i18n)
365
366 menu_container = self._create_categories(type_, path, path_i18n, top_extra)
367
368 if item in menu_container:
369 if isinstance(item, MenuHook):
370 menu_container.replace(item)
371 else:
372 container_item = menu_container[item]
373 if isinstance(container_item, MenuPlaceHolder):
374 menu_container.replace(item)
375 elif isinstance(container_item, MenuHook):
376 # MenuHook must not be replaced
377 log.debug(
378 "ignoring menu at path [{}] because a hook is already in place".format(
379 path
380 )
381 )
382 else:
383 log.error("Conflicting menus at path [{}]".format(path))
384 else:
385 log.debug("Adding menu [{type_}] {path}".format(type_=type_, path=path))
386 menu_container.append(item)
387 self.host.call_listeners("menu", type_, path, path_i18n, item)
388
389 def add_menu(
390 self,
391 type_,
392 path,
393 path_i18n=None,
394 extra=None,
395 top_extra=None,
396 id_=None,
397 callback=None,
398 ):
399 """Add a menu item
400
401 @param type_(unicode): same as in [sat.core.sat_main.SAT.import_menu]
402 @param path(list[unicode]): same as in [sat.core.sat_main.SAT.import_menu]
403 @param path_i18n(list[unicode], None): translated menu path (same lenght as path), or None to get deferred translation
404 @param extra(dict[unicode, unicode], None): same as in [add_menus]
405 @param top_extra: same as in [_create_categories]
406 @param id_(unicode): callback id (mutually exclusive with callback)
407 @param callback(callable): local callback (mutually exclusive with id_)
408 """
409 if path_i18n is None:
410 path_i18n = self._get_path_i_1_8_n(path)
411 assert bool(id_) ^ bool(callback) # we must have id_ xor callback defined
412 if id_:
413 menu_item = MenuItemDistant(
414 self.host, type_, path[-1], path_i18n[-1], id_=id_, extra=extra
415 )
416 else:
417 menu_item = MenuItemLocal(
418 type_, path[-1], path_i18n[-1], callback=callback, extra=extra
419 )
420 self.add_menu_item(type_, path[:-1], menu_item, path_i18n[:-1], top_extra)
421
422 def add_menus(self, menus, top_extra=None):
423 """Add several menus at once
424
425 @param menus(iterable): iterable with:
426 id_(unicode,callable): id of distant callback or local callback
427 type_(unicode): same as in [sat.core.sat_main.SAT.import_menu]
428 path(iterable[unicode]): same as in [sat.core.sat_main.SAT.import_menu]
429 path_i18n(iterable[unicode]): translated menu path (same lenght as path)
430 extra(dict[unicode,unicode]): dictionary of extra data (used on the leaf menu), can be:
431 - "icon": icon name
432 @param top_extra: same as in [_create_categories]
433 """
434 # TODO: manage icons
435 for id_, type_, path, path_i18n, extra in menus:
436 if callable(id_):
437 self.add_menu(
438 type_, path, path_i18n, callback=id_, extra=extra, top_extra=top_extra
439 )
440 else:
441 self.add_menu(
442 type_, path, path_i18n, id_=id_, extra=extra, top_extra=top_extra
443 )
444
445 def add_menu_hook(
446 self, type_, path, path_i18n=None, extra=None, top_extra=None, callback=None
447 ):
448 """Helper method to add a menu hook
449
450 Menu hooks are local menus which override menu given by backend
451 @param type_(unicode): same as in [sat.core.sat_main.SAT.import_menu]
452 @param path(list[unicode]): same as in [sat.core.sat_main.SAT.import_menu]
453 @param path_i18n(list[unicode], None): translated menu path (same lenght as path), or None to get deferred translation
454 @param extra(dict[unicode, unicode], None): same as in [add_menus]
455 @param top_extra: same as in [_create_categories]
456 @param callback(callable): local callback (mutually exclusive with id_)
457 """
458 if path_i18n is None:
459 path_i18n = self._get_path_i_1_8_n(path)
460 menu_item = MenuHook(
461 type_, path[-1], path_i18n[-1], callback=callback, extra=extra
462 )
463 self.add_menu_item(type_, path[:-1], menu_item, path_i18n[:-1], top_extra)
464 log.info("Menu hook set on {path} ({type_})".format(path=path, type_=type_))
465
466 def add_category(self, type_, path, path_i18n=None, extra=None, top_extra=None):
467 """Create a category with all parents, and set extra on the last one
468
469 @param type_(unicode): same as in [sat.core.sat_main.SAT.import_menu]
470 @param path(list[unicode]): same as in [sat.core.sat_main.SAT.import_menu]
471 @param path_i18n(list[unicode], None): translated menu path (same lenght as path), or None to get deferred translation of path
472 @param extra(dict[unicode, unicode], None): same as in [add_menus] (added on the leaf category only)
473 @param top_extra: same as in [_create_categories]
474 @return (MenuCategory): last category add
475 """
476 if path_i18n is None:
477 path_i18n = self._get_path_i_1_8_n(path)
478 last_container = self._create_categories(
479 type_, path, path_i18n, top_extra=top_extra
480 )
481 last_container.set_extra(extra)
482 return last_container
483
484 def get_main_container(self, type_):
485 """Get a main MenuType container
486
487 @param type_: a C.MENU_* constant
488 @return(MenuContainer): the main container
489 """
490 menu_container = self.menus.setdefault(type_, MenuType(type_))
491 return menu_container