diff --git a/docs/cookbook/carousel.md b/docs/cookbook/carousel.md index 260023b30b..c7c41f2226 100644 --- a/docs/cookbook/carousel.md +++ b/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: diff --git a/docs/events/carousel/index.md b/docs/events/carousel/index.md new file mode 100644 index 0000000000..290891ece7 --- /dev/null +++ b/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) diff --git a/docs/events/carousel_item_highlighted.md b/docs/events/carousel_item_highlighted.md new file mode 100644 index 0000000000..4653c8ae63 --- /dev/null +++ b/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. diff --git a/docs/events/carousel_item_selected.md b/docs/events/carousel_item_selected.md new file mode 100644 index 0000000000..6d892d1f8c --- /dev/null +++ b/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. diff --git a/docs/events/carousel_items_empty.md b/docs/events/carousel_items_empty.md new file mode 100644 index 0000000000..6ca9679085 --- /dev/null +++ b/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. diff --git a/docs/events/index.md b/docs/events/index.md index c7f5d6a3ce..0c0dd85f20 100644 --- a/docs/events/index.md +++ b/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) diff --git a/docs/gmc/reference/mpf-gmc.md b/docs/gmc/reference/mpf-gmc.md index c939a86969..34f62209cc 100644 --- a/docs/gmc/reference/mpf-gmc.md +++ b/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. diff --git a/docs/install/0.80.md b/docs/install/0.80.md index 8cb3a07561..314cf5073e 100644 --- a/docs/install/0.80.md +++ b/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 diff --git a/mkdocs.yml b/mkdocs.yml index 76143be39d..7d8d1f53b0 100644 --- a/mkdocs.yml +++ b/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: