acid-drop

- Hacking the planet from a LilyGo T-Deck using custom firmware
git clone git://git.acid.vegas/acid-drop.git
msg.md (2670B)
      1 ```eval_rst
      2 .. include:: /header.rst
      3 :github_url: |github_link_base|/others/msg.md
      4 ```
      5 # Messaging
      6 
      7 Messaging (`lv_msg`) is a classic []publisher subscriber](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern) implementation for LVGL.
      8 
      9 ## IDs
     10 Both the publishers and the subscribers needs to know the message identifiers.
     11 In `lv_msg` these are simple `uint32_t` integers. For example:
     12 ```c
     13 #define MSG_DOOR_OPENED             1
     14 #define MSG_DOOR_CLOSED             2
     15 #define MSG_USER_NAME_CHANGED       100
     16 #define MSG_USER_AVATAR_CHANGED     101
     17 ```
     18 
     19 You can orgnaize the message IDs as you wish.
     20 
     21 Both parties also need to know about the format of teh payload. E.g. in the above example
     22 `MSG_DOOR_OPENED` and `MSG_DOOR_CLOSED` has no payload but `MSG_USER_NAME_CHANGED` can have a `const char *` payload containing the user name, and `MSG_USER_AVATAR_CHANGED` a `const void *` image source with the new avatar image.
     23 
     24 
     25 ## Send message
     26 
     27 Messages can be sent with `lv_msg_send(msg_id, payload)`. E.g.
     28 ```c
     29 lv_msg_send(MSG_USER_DOOR_OPENED, NULL);
     30 lv_msg_send(MSG_USER_NAME_CHANGED, "John Smith");
     31 ```
     32 
     33 ## Subscribe to a message
     34 
     35 `lv_msg_subscribe(msg_id, callback, user_data)` can be used to subscribe to message.
     36 
     37 The callback should look like this:
     38 ```c
     39 
     40 static void user_name_subscriber_cb(void * s, lv_msg_t * m)
     41 {
     42     /*s: a subscriber obeject, can be used to unscubscribe*/
     43     /*m: a message object with the msg_id, payload, and user_data (set durung subscription)*/
     44 
     45     ...do something...
     46 }
     47 ```
     48 
     49 From `lv_msg_t` the followings can be used to get some data:
     50 - `lv_msg_get_id(m)`
     51 - `lv_msg_get_payload(m)`
     52 - `lv_msg_get_user_data(m)`
     53 
     54 ## Subscribe with an lv_obj
     55 It's quite typical that an LVGL widget is interested in some messages.
     56 To make it simpler `lv_msg_subsribe_obj(msg_id, obj, user_data)` can be used.
     57 If a new message is published with `msg_id` an `LV_EVENT_MSG_RECEIVED` event will be sent to the object.
     58 
     59 For example:
     60 ```c
     61 lv_obj_add_event_cb(user_name_label, user_name_label_event_cb, LV_EVENT_MSG_RECEIVED, NULL);
     62 lv_msg_subsribe_obj(MSG_USER_NAME_CHANGED, user_name_label, NULL);
     63 
     64 ...
     65 
     66 void user_name_label_event_cb(lv_event_t * e)
     67 {
     68     lv_obj_t * label = lv_event_get_target(e);
     69     lv_msg_t * m = lv_event_get_msg(e);
     70     lv_label_set_text(label, lv_msg_get_payload(m));
     71 }
     72 
     73 ```
     74 
     75 ### Unsubscribe
     76 `lv_msg_subscribe` returns a pointer which can be used to unsubscribe:
     77 ```c
     78 void * s1;
     79 s1 = lv_msg_subscribe(MSG_USER_DOOR_OPENED, some_callback, NULL);
     80 
     81 ...
     82 
     83 lv_msg_unsubscribe(s1);
     84 ```
     85 
     86 ## Example
     87 
     88 ```eval_rst
     89 
     90 .. include:: ../../examples/others/msg/index.rst
     91 
     92 ```
     93 ## API
     94 
     95 
     96 ```eval_rst
     97 
     98 .. doxygenfile:: lv_msg.h
     99   :project: lvgl
    100 
    101 ```