Context Menu

= Context Menu =

== Español ==

'''Context Menu''' es una extensión que permite crear y mostrar un menú contextual personalizado dentro de BloKes. Este menú puede aparecer al hacer clic derecho y puede contener opciones propias del proyecto, además de separadores visuales entre ellas.

=== Funciones principales ===

Esta extensión permite:

• crear un menú contextual personalizado
• añadir opciones con texto visible e identificador interno
• añadir separadores entre opciones
• mostrar el menú en una posición concreta
• mostrar el menú en la última posición de clic derecho
• ocultar el menú contextual
• activar o desactivar la captura del clic derecho
• activar o desactivar el bloqueo del menú contextual nativo del navegador
• limitar la captura del clic derecho a la escena, a los objetos o a un sprite concreto
• detectar qué opción del menú fue pulsada
• obtener información sobre el último clic derecho realizado
• reaccionar mediante eventos cuando se hace clic derecho o cuando se pulsa una opción

=== Funcionamiento ===

La extensión mantiene una lista interna de elementos del menú. Cada opción tiene un texto visible y un ID que sirve para identificarla después desde el proyecto.

Cuando se muestra el menú, este aparece como una capa visual encima de la página. Si está activada la captura del clic derecho, el proyecto puede abrir el menú automáticamente al hacer clic derecho.

La extensión también guarda información del último clic derecho detectado, incluyendo:

• la posición X
• la posición Y
• la etiqueta HTML del elemento pulsado
• el ID del elemento pulsado
• la clase del elemento pulsado
• el nombre del sprite bajo el clic, si lo hay
• si el clic se hizo sobre la escena

=== Bloques principales ===

• '''vaciar menú contextual''': elimina todas las opciones y separadores actuales
• '''añadir opción [LABEL] con id [ID]''': añade una nueva opción al menú
• '''añadir separador al menú contextual''': inserta una línea separadora
• '''mostrar menú contextual en x [X] y [Y]''': abre el menú en unas coordenadas concretas
• '''mostrar menú contextual en la última posición de clic derecho''': abre el menú donde ocurrió el último clic derecho
• '''ocultar menú contextual''': cierra el menú
• '''[STATE] captura clic derecho''': activa o desactiva la captura del clic derecho
• '''[STATE] bloquear menú contextual nativo''': activa o desactiva el bloqueo del menú del navegador
• '''activar captura clic derecho en [SCOPE]''': limita la captura a todos, solo la escena o solo objetos
• '''activar captura clic derecho solo en objeto [SPRITE]''': limita la captura a un sprite concreto

=== Reporteros y comprobaciones ===

La extensión incluye bloques para consultar el estado actual y los datos del último clic derecho:

• '''última opción pulsada del menú contextual'''
• '''menú contextual visible?'''
• '''captura clic derecho activada?'''
• '''bloqueo menú contextual nativo activado?'''
• '''última x de clic derecho'''
• '''última y de clic derecho'''
• '''última etiqueta del objetivo de clic derecho'''
• '''último id del objetivo de clic derecho'''
• '''última clase del objetivo de clic derecho'''
• '''objeto bajo el último clic derecho'''
• '''el último clic derecho fue en la escena?'''

=== Eventos ===

La extensión incluye varios bloques de evento:

• '''cuando se pulse opción [ID] del menú contextual'''
• '''cuando se haga clic derecho'''
• '''cuando se haga clic derecho en objeto [SPRITE]'''
• '''cuando se haga clic derecho en la escena'''

Estos bloques permiten ejecutar código cuando el usuario abre el menú o selecciona una opción concreta.

=== Usos habituales ===

Context Menu resulta útil para:

• crear menús de acciones al hacer clic derecho
• mostrar opciones distintas según el lugar pulsado
• añadir interacciones avanzadas sobre sprites o sobre la escena
• construir editores, herramientas o interfaces dentro del proyecto
• sustituir el menú contextual del navegador por uno propio del proyecto

=== Ejemplo ===

Un proyecto puede:

• vaciar el menú contextual
• añadir una opción llamada ''Duplicar'' con ID ''duplicar''
• añadir una opción llamada ''Eliminar'' con ID ''eliminar''
• activar la captura del clic derecho
• activar la captura solo en objetos

Después, al hacer clic derecho sobre un sprite, el menú puede aparecer automáticamente. Si el usuario pulsa ''Eliminar'', el proyecto puede detectar que la última opción seleccionada fue ''eliminar'' y ejecutar la acción correspondiente.

=== Notas ===

• Cada opción del menú debe tener un ID reconocible para poder detectar qué acción se ha elegido.
• El menú puede mostrarse manualmente desde bloques o automáticamente al capturar el clic derecho.
• El proyecto puede limitar la captura del clic derecho a toda la escena, solo a objetos o incluso a un sprite concreto.
• La extensión recuerda la información del último clic derecho para que pueda usarse más tarde desde otros bloques.
• Esta extensión es especialmente útil para proyectos con interfaces avanzadas, editores visuales o menús de acciones contextuales.

---

== English ==

'''Context Menu''' is an extension that allows you to create and display a custom context menu inside BloKes. This menu can appear when the user right-clicks and can contain project-defined options as well as visual separators between them.

=== Main features ===

This extension allows you to:

• create a custom context menu
• add options with visible labels and internal identifiers
• add separators between options
• show the menu at a specific position
• show the menu at the last right-click position
• hide the context menu
• enable or disable right-click capture
• enable or disable blocking of the browser's native context menu
• limit right-click capture to the stage, to sprites, or to a specific sprite
• detect which menu option was clicked
• get information about the last right-click
• react through events when a right-click happens or when an option is selected

=== How it works ===

The extension keeps an internal list of menu elements. Each option has a visible label and an ID that can later be used by the project to identify it.

When the menu is shown, it appears as a visual layer on top of the page. If right-click capture is enabled, the project can automatically open the menu when the user right-clicks.

The extension also stores information about the last detected right-click, including:

• the X position
• the Y position
• the HTML tag of the clicked element
• the ID of the clicked element
• the class of the clicked element
• the name of the sprite under the click, if any
• whether the click happened on the stage

=== Main blocks ===

• '''clear context menu''': removes all current options and separators
• '''add option [LABEL] with id [ID]''': adds a new option to the menu
• '''add separator to context menu''': inserts a dividing line
• '''show context menu at x [X] y [Y]''': opens the menu at specific coordinates
• '''show context menu at the last right-click position''': opens the menu where the last right-click happened
• '''hide context menu''': closes the menu
• '''[STATE] capture right click''': enables or disables right-click capture
• '''[STATE] block native context menu''': enables or disables blocking the browser menu
• '''enable right-click capture on [SCOPE]''': limits capture to all, stage only, or sprites only
• '''enable right-click capture only on sprite [SPRITE]''': limits capture to a specific sprite

=== Reporters and checks ===

The extension includes blocks to query the current state and the data from the last right-click:

• '''last clicked context menu option'''
• '''context menu visible?'''
• '''right-click capture enabled?'''
• '''native context menu blocking enabled?'''
• '''last right-click x'''
• '''last right-click y'''
• '''last right-click target tag'''
• '''last right-click target id'''
• '''last right-click target class'''
• '''sprite under the last right click'''
• '''was the last right click on the stage?'''

=== Events ===

The extension includes several event blocks:

• '''when context menu option [ID] is clicked'''
• '''when right click happens'''
• '''when right click happens on sprite [SPRITE]'''
• '''when right click happens on the stage'''

These blocks allow the project to run code when the user opens the menu or selects a specific option.

=== Common uses ===

Context Menu is useful for:

• creating action menus on right-click
• showing different options depending on where the user clicked
• adding advanced interactions on sprites or on the stage
• building editors, tools, or interfaces inside the project
• replacing the browser's native context menu with a project-defined one

=== Example ===

A project can:

• clear the context menu
• add an option called ''Duplicate'' with the ID ''duplicate''
• add an option called ''Delete'' with the ID ''delete''
• enable right-click capture
• enable capture only on sprites

Then, when the user right-clicks on a sprite, the menu can appear automatically. If the user clicks ''Delete'', the project can detect that the last selected option was ''delete'' and perform the corresponding action.

=== Notes ===

• Each menu option should have a recognizable ID so the project can detect which action was selected.
• The menu can be shown manually from blocks or automatically by capturing right-clicks.
• The project can limit right-click capture to the whole stage, only sprites, or even a specific sprite.
• The extension remembers information about the last right-click so it can be used later from other blocks.
• This extension is especially useful for projects with advanced interfaces, visual editors, or contextual action menus.