From 2ffd83eee229bf3fef2227a34ea33ebd905f016d Mon Sep 17 00:00:00 2001 From: Adam Dobrowolski Date: Fri, 9 Oct 2020 10:53:44 +0200 Subject: [PATCH] Doc updated for UI and removed some doc for bluetooth * removed taglib doc build, main readme shown by default on start * made better diagrams for UI shown in doxygen * removed old docs for bluetooth --- doc/Doxyfile.in | 5 ++- module-gui/README.md | 24 ++---------- module-gui/doc/how_app_start_work.puml | 29 ++++++++++++++ module-gui/doc/how_app_start_work.svg | 41 ++++++++++++++++++++ module-gui/doc/how_keypress_work.puml | 41 ++++++++++++++++++++ module-gui/doc/how_keypress_work.svg | 53 ++++++++++++++++++++++++++ module-gui/doc/how_ui_work.puml | 17 +++++++++ module-gui/doc/how_ui_work.svg | 29 ++++++++++++++ 8 files changed, 216 insertions(+), 23 deletions(-) create mode 100644 module-gui/doc/how_app_start_work.puml create mode 100644 module-gui/doc/how_app_start_work.svg create mode 100644 module-gui/doc/how_keypress_work.puml create mode 100644 module-gui/doc/how_keypress_work.svg create mode 100644 module-gui/doc/how_ui_work.puml create mode 100644 module-gui/doc/how_ui_work.svg diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 4b181ee59..f91647cb0 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -905,7 +905,8 @@ EXCLUDE = @PROJECT_SOURCE_DIR@/module-bluetooth/lib \ @PROJECT_SOURCE_DIR@/module-audio/tests \ @PROJECT_SOURCE_DIR@/module-vfs/tests \ @PROJECT_SOURCE_DIR@/module-vfs/board \ - @PROJECT_SOURCE_DIR@/module-bsp/board/rt1051/common + @PROJECT_SOURCE_DIR@/module-bsp/board/rt1051/common \ + @PROJECT_SOURCE_DIR@/module-audio/Audio/decoder/taglib # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded @@ -958,7 +959,7 @@ EXAMPLE_RECURSIVE = NO # that contain images that are to be included in the documentation (see the # \image command). -IMAGE_PATH = +IMAGE_PATH = @PROJECT_SOURCE_DIR@/module-gui/doc/ # The INPUT_FILTER tag can be used to specify a program that doxygen should # invoke to filter for each input file. Doxygen will invoke the filter program diff --git a/module-gui/README.md b/module-gui/README.md index b7961d1b7..9640d4786 100644 --- a/module-gui/README.md +++ b/module-gui/README.md @@ -2,20 +2,11 @@ This article includes details on how MuditaOS widgets are rendered and how the GUI handles key pressing. -Schematics parts used: -- `[name : part]` - [name of module : part of code responsible] -- `=> / <=>` - direction of communication -- `<>` event on diagrams, name placeholder of element in text - ## Introduction ### How widgets are rendered -Our UI is split into: - -``` -[bsp] <=> [renderer] <=> [application : widgets] -``` +![Simplified UI](how_ui_work.svg "Simplified UI flow") * All widgets are children of `gui::Item` * There are two major commands to trigger screen redraw: @@ -31,14 +22,7 @@ Our UI is split into: Please see `app::Application`, `sapm::ApplicationManager` for detailed information on how messages are handled between both. This is just general documentation. -``` -[ApplicationManager] [Application] - <=> START <=> - <=> Set focus <=> - <=> Set keyboard <=> - <=> Put background <=> - <=> kill <=> -``` +![Simplified app start diagram](how_app_start_work.svg "Simplified hi level app start") These actions are done on a chained bus request between: `app::Application`, `sapm::ApplicationManager` and `sapm::EventWorker` @@ -64,9 +48,7 @@ All of these are asynchronous and there is little state machine maintenance. ## What happens when you press a key? -``` -[bsp] => [EventWorker : basic key translation] < key press event> => [Application with focus] -``` +![Key Handling Diagram](how_keypress_work.svg "High level perspective of the key handling") * `bsp` handles key press on I2C IRQ and sends Event to event worker on naked FreeRTOS pipe (on target RT1051, on Linux `gtk` does that) * `EventWorker` worker of `EventService`: diff --git a/module-gui/doc/how_app_start_work.puml b/module-gui/doc/how_app_start_work.puml new file mode 100644 index 000000000..8a8ebf774 --- /dev/null +++ b/module-gui/doc/how_app_start_work.puml @@ -0,0 +1,29 @@ +@startuml + +== ApplicationManager aplication start == + +APM -> Application: Message start +APM <- Application: Application started confirmation +APM -> Application: Init +APM <- Application: Initialized +APM -> Application: You have focus +APM -> EVM: Application NAME has focus +... ~~ Lots of action ~~ ... + + +== ApplicationManager aplication start == + +Application <- APM: EOL request + +hnote over APM + Get previous application or ignore +endhnote + +== Service manager - power off == + +loop each application +SVM -> Application: EOL request +SVM <-- Application: OK +end + +@enduml diff --git a/module-gui/doc/how_app_start_work.svg b/module-gui/doc/how_app_start_work.svg new file mode 100644 index 000000000..0aaf82c6f --- /dev/null +++ b/module-gui/doc/how_app_start_work.svg @@ -0,0 +1,41 @@ +APMAPMApplicationApplicationEVMEVMSVMSVMApplicationManager aplication startMessage startApplication started confirmationInitInitializedYou have focusApplication NAME has focusLots of actionApplicationManager aplication startEOL requestGet previous application or ignoreService manager - power offloop[each application]EOL requestOK \ No newline at end of file diff --git a/module-gui/doc/how_keypress_work.puml b/module-gui/doc/how_keypress_work.puml new file mode 100644 index 000000000..a66034643 --- /dev/null +++ b/module-gui/doc/how_keypress_work.puml @@ -0,0 +1,41 @@ +@startuml + +actor User + +== Simple fast key press == + +User -> EVM : KeyPress +EVM->Apps: KeyPress +User-> EVM: KeyRelease +EVM->Apps: KeyReleased + +== Long Press == + +User -> EVM : KeyPress +EVM->Apps: KeyPress +... Some ~~long delay~~ ... +EVM->Apps: KeyLongPress +User-> EVM: KeyRelease +EVM -x Apps: No KeyRelease now! + +== Long Press - with continous action == + +User -> EVM : KeyPress +EVM->Apps: KeyPress +... Some ~~long delay~~ ... +EVM->Apps: KeyLongPress + hnote over Apps + App TIMER process things: + each 100ms: + do_something + endhnote +... Some ~~long delay~~ ... +User->EVM: KeyReleased +EVM-> Apps: KeyLongRelease + hnote over Apps + App end TIMER processing + endhnote +EVM -x Apps: No KeyRelease now! + +@enduml + diff --git a/module-gui/doc/how_keypress_work.svg b/module-gui/doc/how_keypress_work.svg new file mode 100644 index 000000000..765047f7c --- /dev/null +++ b/module-gui/doc/how_keypress_work.svg @@ -0,0 +1,53 @@ +UserUserEVMEVMAppsAppsSimple fast key pressKeyPressKeyPressKeyReleaseKeyReleasedLong PressKeyPressKeyPressSomelong delayKeyLongPressKeyReleaseKeyReleasedNo KeyRelease now!Long Press - with continous actionKeyPressKeyPressSomelong delayKeyLongPressApp TIMER process things:each 100ms:do_somethingKeyReleasedKeyLongReleaseApp end TIMER processing \ No newline at end of file diff --git a/module-gui/doc/how_ui_work.puml b/module-gui/doc/how_ui_work.puml new file mode 100644 index 000000000..e4881ee00 --- /dev/null +++ b/module-gui/doc/how_ui_work.puml @@ -0,0 +1,17 @@ +@startuml + +Application -> Application : Prepare DOM for render +Application -> ServiceGUI : Process DOM to render + +hnote over ServiceGUI + Draws DOM on canvas +endhnote + +ServiceGUI -> ServiceEink: Process DOM render +ServiceGUI <- ServiceEink: Request done (blocking) + +hnote over ServiceEink + Sends data to display +endhnote + +@enduml diff --git a/module-gui/doc/how_ui_work.svg b/module-gui/doc/how_ui_work.svg new file mode 100644 index 000000000..35d0a8676 --- /dev/null +++ b/module-gui/doc/how_ui_work.svg @@ -0,0 +1,29 @@ +ApplicationApplicationServiceGUIServiceGUIServiceEinkServiceEinkPrepare DOM for renderProcess DOM to renderDraws DOM on canvasProcess DOM renderRequest done (blocking)Sends data to display \ No newline at end of file