refs#147: add MenuItem.context for free use

Author: dk

Changes

@@ -3,6 +3,7 @@ Revision history for Perl module Prima
 1.77 2025-XX-XX
  - Hint colors can be set for each widget individually
  - Add JXL support
+ - Add MenuItem.context for generic use
 
 1.76 2025-03-12
  - Implement gt::Grid geometry emulating Tk::grid

class/AbstractMenu.c

@@ -979,6 +979,21 @@ AbstractMenu_checked( Handle self, Bool set, char * varName, Bool checked)
 	}
 	return checked;
 }
+SV*
+AbstractMenu_context( Handle self, Bool set, char * varName, SV* context)
+{
+	PMenuItemReg m;
+	if ( var-> stage > csFrozen) return 0;
+	m = find_menuitem( self, varName, true);
+	if ( m == NULL) return 0;
+	if ( !set) return m-> context ? newSVsv(m->context) : NULL_SV;
+	m-> context = (context && SvOK(context)) ? newSVsv(context) : NULL;
+	notify( self, "<ssUS", "Change", "context",
+		m->variable ? m-> variable      : varName,
+		m->variable ? m-> flags.utf8_variable : 0,
+		m->context ? m->context : NULL_SV);
+	return m->context;
+}
 
 int
 AbstractMenu_group( Handle self, Bool set, char * varName, int group)

class/AbstractMenu.cls

@@ -6,6 +6,7 @@ object Prima::AbstractMenu ( Prima::Component)
 	property SV   * action ( char * varName);
 	property Bool   autoToggle( char * varName);
 	property Bool   checked( char * varName);
+	property SV   * context( char * varName);
 	property Handle icon   ( char * varName);
 	property int    group  ( char * varName);
 	property SV   * hint   ( char * varName);

include/apricot.h

@@ -6,7 +6,7 @@
 #define POLLUTE_NAME_SPACE 1
 #endif
 
-#define PRIMA_CORE_VERSION 2025031501
+#define PRIMA_CORE_VERSION 2025051901
 
 #define PRIMA_VERSION_BOOTCHECK \
 	if(apc_get_core_version()!=PRIMA_CORE_VERSION) \
@@ -2876,6 +2876,7 @@ typedef struct _MenuItemReg {   /* Menu item registration record */
 	SV *   hint;                 /* hint if not NULL */
 	Handle icon;                 /* custom checked bitmap */
 	int    group;                /* radio group */
+	SV *   context;              /* custom scalar */
 	SV *   onPaint;              /* callbacks */
 	SV *   onMeasure;
 	struct _MenuItemReg* down;   /* pointer to submenu */

pod/Prima/Menu.pod

@@ -235,6 +235,21 @@ The toolkit reserves the following keys for internal use:
 
 =over
 
+=item context SCALAR
+
+A single scalar for free generic use, f ex like this:
+
+    [
+        menu
+        ...
+        sub {
+           my ( $self, $item ) = @_;
+           my $my_scalar = $self->menu->context($item);
+        }
+        ...
+        { context => $my_scalar },
+    ]
+
 =item group INTEGER
 
 Same as the C<group> property.
@@ -312,27 +327,27 @@ combination is treated differently:
 
 =over
 
-=item six - [ NAME, TEXT/IMAGE, ACCEL, KEY, ACTION/SUBMENU, DATA ]
+=item six - [ NAME, TEXT/IMAGE, ACCEL, KEY, ACTION/SUBMENU, OPTIONS ]
 
 A six-scalar array is a fully qualified text-item description.
 All fields correspond to the described above scalars.
 
 =item five [ NAME, TEXT/IMAGE, ACCEL, KEY, ACTION/SUBMENU ]
 
-Same as the six-scalar syntax, but without the DATA field.
-If DATA is skipped then it is set to C<undef>.
+Same as the six-scalar syntax, but without the OPTIONS field.
+If OPTIONS is skipped then it is set to C<undef>.
 
-=item four [ TEXT/IMAGE, ACCEL, KEY, ACTION/SUBMENU ] or [ NAME, TEXT/IMAGE, ACTION/SUBMENU, DATA ]
+=item four [ TEXT/IMAGE, ACCEL, KEY, ACTION/SUBMENU ] or [ NAME, TEXT/IMAGE, ACTION/SUBMENU, OPTIONS ]
 
 One of the two definitions, depending on whether the last item is a hashref or not.
 
 If the last item is not a hashref, then treated the same as the five-scalar
 syntax, but without the NAME field.  When NAME is skipped it is assigned to a
 unique string within the menu object.
 
-Otherwise same as the three-scalar syntax plus the DATA hashref.
+Otherwise same as the three-scalar syntax plus the OPTIONS hashref.
 
-=item three [ NAME, TEXT/IMAGE, ACTION/SUBMENU ] or [ TEXT/IMAGE, ACTION/SUBMENU, DATA ]
+=item three [ NAME, TEXT/IMAGE, ACTION/SUBMENU ] or [ TEXT/IMAGE, ACTION/SUBMENU, OPTIONS ]
 
 One of the two definitions, depending on whether the last item is a hashref or not.
 
@@ -341,16 +356,16 @@ syntax, but without the ACCEL and the KEY fields.  KEY is C<kb::NoKey> by
 default, so no keyboard combination is bound to the item. The default ACCEL value
 is an empty string.
 
-Otherwise the same as the two-scalar syntax plus DATA hashref.
+Otherwise the same as the two-scalar syntax plus OPTIONS hashref.
 
-=item two [ TEXT/IMAGE, ACTION/SUBMENU ] or [ NAME, DATA ]
+=item two [ TEXT/IMAGE, ACTION/SUBMENU ] or [ NAME, OPTIONS ]
 
 One of the two definitions, depending on whether the last item is a hashref or not.
 
 If the last item is not a hashref, then treated the same as the three-scalar
 syntax, but without the NAME field.
 
-Otherwise treated as the menu items with the data reference. Useful for custom
+Otherwise treated as the menu items with the options reference. Useful for custom
 menu items that need at least the C<'?'> flag in the NAME.
 
 =item one and zero [ NAME ]
@@ -399,7 +414,7 @@ reader is advised to run the example and learn the menu mechanics.
 
 As briefly mentioned above, all menu items can be accessed using the following
 properties:  C<::accel>, C<::text>, C<::image>, C<::checked>, C<::enabled>,
-C<::action>, C<::data>.  These, plus some other methods can be also called in an
+C<::action>, C<::options>.  These, plus some other methods can be also called in an
 alternative way, resembling name-based component calls of L<Prima::Object>. For
 example, the call
 
@@ -516,9 +531,9 @@ usage with the sub-menu items is possible, although discouraged.
 
 NAME is the name of the menu item.
 
-=item data NAME, HASH / Prima::MenuItem::data HASH
+=item context NAME, SCALAR / Prima::MenuItem::context SCALAR
 
-Manages the user data hash.  NAME is the name of the menu item.
+Manages the user context scalar.  NAME is the name of the menu item.
 
 =item enabled NAME, BOOLEAN / Prima::MenuItem::enabled BOOLEAN
 
@@ -557,7 +572,7 @@ structure, with the syntax described in L<Menu items>.
 The C<::items> property is an ultimate tool for reading and writing the menu
 items tree, but often it is too powerful, so there exist several easier-to-use
 properties C<::accel>, C<::text>, C<::image>, C<::checked>, C<::enabled>,
-C<::action>, C<::data>, that can access menu items individually.
+C<::action>, C<::options> that can access menu items individually.
 
 =item key NAME, KEY / Prima::MenuItem::key KEY
 
@@ -568,6 +583,10 @@ the literal key format - strings such as '^C' or 'F5'.
 
 NAME is the name of the menu item; KEY is an integer value.
 
+=item options NAME, HASH / Prima::MenuItem::options HASH
+
+Manages the options hash.  NAME is the name of the menu item.
+
 =item selected BOOLEAN
 
 If set to 1, the menu object is granted extra functionality from a window or

pod/Prima/tutorial.pod

@@ -318,8 +318,7 @@ three to six items in the array. One can set the left-aligned text string for
 the item, the right-aligned text string for the display of the hotkey, if any,
 the definition of the hotkey itself, and the action to be taken if the user has
 pressed either the menu item or the hotkey combination. Also, as in the
-previous cases, an explicit menu item ID can be set, and also an arbitrary data scalar,
-for the generic needs of the programmer.
+previous cases, an explicit menu item ID can be set, along with extra options
 
 Here are the combinations of scalars in an array that are allowed for defining
 a text menu item:
@@ -330,7 +329,7 @@ Four items - [ text, hotkey text, hotkey, action ]
 
 Five items - [ ID, text, hotkey text, hotkey, action ]
 
-Six items - [ ID, text, hotkey text, hotkey, action, data ]
+Six items - [ ID, text, hotkey text, hotkey, action, options ]
 
 The image menu items are fully analogous to the text items, except that instead
 of the text string, an image object is supplied: