document carousel events per 0.80.0.dev9

docs/cookbook/carousel.md

@@ -74,7 +74,7 @@ start the mode that was selected by the player.
 #config_version=5
 mode:
   start_events: ball_starting
-  stop_events: my_carousel_item_selected
+  stop_events: carousel_item_selected{carousel=my_carousel}
   code: mpf.modes.carousel.code.carousel.Carousel
   use_wait_queue: true
 mode_settings:

docs/events/carousel/index.md

@@ -0,0 +1,18 @@
+---
+title: Carousel event index
+---
+
+# Carousel Events
+
+These events are posted by the built-in Carousel mode.
+
+See: [Carousel Mode Selection](../../cookbook/carousel.md) for pre-0.80 carousel configuration.
+
+See: [MPFCarousel](../../gmc/reference/mpf-carousel.md) for 0.80+ carousel configuration.
+
+The following events are as of MPF `0.80.0.dev10`.
+Previously, the word "carousel" was replaced with the actual carousel name, along with other differences.
+
+* [carousel_item_highlighted](../carousel_item_highlighted.md)
+* [carousel\_items_empty](../carousel_items_empty.md)
+* [carousel\_item_selected](../carousel_item_selected.md)

docs/events/carousel_item_highlighted.md

@@ -0,0 +1,32 @@
+---
+title: carousel_item_highlighted
+---
+
+# carousel_item_highlighted
+
+
+--8<-- "event.md"
+
+An item was highlighted in a carousel. This event is posted
+when the carousel initially displays and highlights its initial item
+and also when moving the carousel to the next or previous item.
+
+## Keyword arguments
+
+(See the [Conditional Events](overview/conditional.md)
+guide for details for how to create entries in your config file that
+only respond to certain combinations of the arguments below.)
+
+#### `carousel`:
+
+The name of the carousel that had an item selected.
+
+#### `direction`:
+
+The direction that the highlight change was performed in. Can be any of:
+
+"forwards", "backwards", or `None`. Note that `None` is the Python keyword, not the string "None".
+
+#### `item`:
+
+The string name of the newly-highlighted item.

docs/events/carousel_item_selected.md

@@ -0,0 +1,26 @@
+---
+title: carousel_item_selected
+---
+
+# carousel_item_selected
+
+
+--8<-- "event.md"
+
+A carousel has just had an item selected. Use the carousel and item
+keyword arguments to filter this event in your config players and handle
+the different item selection behaviors.
+
+## Keyword arguments
+
+(See the [Conditional Events](overview/conditional.md)
+guide for details for how to create entries in your config file that
+only respond to certain combinations of the arguments below.)
+
+#### `carousel`:
+
+The name of the carousel that had an item selected.
+
+#### `item`:
+
+The string name of the selected item.

docs/events/carousel_items_empty.md

@@ -0,0 +1,26 @@
+---
+title: carousel_items_empty
+---
+
+# carousel_items_empty
+
+
+--8<-- "event.md"
+
+A carousel determined that it has
+no selectable_items that are valid for display. This can be because
+the `mode_settings` for the carousel mode still needs to be set,
+or because all of the `selectable_items` were dynamically evaluated
+and removed from the valid option set. Use the `carousel` keyword
+argument to filter on the correct carousel if have any config player
+behaviors that need to happen in response.
+
+## Keyword arguments
+
+(See the [Conditional Events](overview/conditional.md)
+guide for details for how to create entries in your config file that
+only respond to certain combinations of the arguments below.)
+
+#### `carousel`:
+
+The name of the carousel that had an item selected.

docs/events/index.md

@@ -288,6 +288,11 @@ will posted an event called *switch_s_left_slingshot_active*.
     * [bonus_start](bonus_start.md)
     * [bonus_subtotal](bonus_subtotal.md)
 
+* [Carousel Events](carousel/index.md)
+    * [carousel_item_highlighted](carousel_item_highlighted.md)
+    * [carousel\_items_empty](carousel_items_empty.md)
+    * [carousel\_item_selected](carousel_item_selected.md)
+
 * Config Player Events
     * [clear](clear.md)
 

docs/gmc/reference/mpf-gmc.md

@@ -115,7 +115,7 @@ Emitted during the Bonus mode. See [bonus mode settings](bonus.md) for details.
 
 Emitted when a mode ends.
 
-#### `item_highlighted(payload)`
+#### `carousel_item_highlighted(payload)`
 
 Emitted during a carousel event.
 

docs/install/0.80.md

@@ -35,7 +35,7 @@ bonus_entry{entry="completed_ramps", hits=3, score=3000}
 
 ### Carousel
 
-Carousel events have changed to use a consolidated *item_highlighted* event instead of unique events for each item.
+Carousel events have changed to use a consolidated *carousel_item_highlighted* and *carousel_item_selected* event instead of unique events for each item.
 
 Given a carousel mode "missionselect" and an item "garrus":
 
@@ -46,10 +46,10 @@ missionselect_garrus_highlighted{direction="forwards"}
 
 **MPF 0.80 Event:**
 ``` console
-item_highlighted{carousel="missionselect", item="garrus", direction="forwards"}
+carousel_item_highlighted{carousel="missionselect", item="garrus", direction="forwards"}
 ```
 
-The new *item_highlighted* event is incorporated into GMC, but if you have other custom event handlers for carousel item selection those will need to be updated.
+The new *carousel_item_highlighted* event is incorporated into GMC, but if you have other custom event handlers for carousel item selection those will need to be updated.
 
 ### Slides and Widgets
 

mkdocs.yml

@@ -1209,6 +1209,11 @@ nav:
       - bonus_multiplier: events/bonus_multiplier.md
       - bonus_start: events/bonus_start.md
       - bonus_subtotal: events/bonus_subtotal.md
+    - Carousel Events:
+      - events/carousel/index.md
+      - carousel_name_items_empty: events/carousel_items_empty.md
+      - carousel_name_item_selected: events/carousel_item_selected.md
+      - carousel_item_highlighted: events/carousel_item_highlighted.md
     - Config Player Events:
       - clear: events/clear.md
     - Credit Events: