BOOL PM_AbortHook( APTR handle)
Check whether the pointer has left the item whose submenu is being constructed. An existing child window may also be refreshed.
handle - Opaque parent handle supplied to the active SubConstruct
hook. Extract the IPTR value from the hook message and cast that
value to APTR; do not pass the message pointer itself.
TRUE if the pointer is outside the selected item; FALSE otherwise.
Use only during the constructor callback that supplied the handle. NULL, expired handles and calls without an active selected item are invalid. A TRUE result does not stop the constructor automatically; the hook must decide whether to abandon its work and return NULL. The refresh side effect can perform window operations and must run in task context.
void PM_AlterState( struct PopupMenu *pm, struct PM_IDLst *l, UWORD action)
Apply each ID-list operation to the first matching menu item. Update its checked and selected flags and any attached AutoStore value.
pm - First menu item, or NULL. l - ID list, or NULL. action - 3 for selection; 2 for deselection. Other values do nothing.
None.
For selection, Include and Reflect check the item; Exclude and Inverse clear it. For deselection, Reflect clears the item and Inverse checks it; Include and Exclude leave it unchanged. Missing IDs are skipped. Operations run in list order without checking Hidden, Disabled, Checkit or Toggle attributes. This call does not redraw a displayed menu or invoke a menu handler. The menu and list remain owned by their callers.
struct PM_IDLst * PM_ExLstA( ULONG *id)
Create an exclusion list from an array of item IDs.
id - Non-NULL readable ULONG array terminated by zero.
The new list, or NULL for an empty array or any allocation failure. On failure, all nodes allocated by this call are freed.
IDs are copied in order; the array is not retained. Zero cannot be represented in this form. Use PM_MakeIDListA() for ID zero or other operation kinds. Ownership follows PM_MakeIDListA().
APTR PM_FilterIMsgA( struct Window *w, struct PopupMenu *pm, struct IntuiMessage *im, struct TagItem *tags)
Handle right-command shortcuts or forward menu-button events to PM_OpenPopupMenuA().
w - Parent window for popup display, or NULL for the active screen. pm - Menu tree, or NULL. im - Caller-owned IntuiMessage, or NULL. tags - Terminated option list, or NULL.
PM_MenuHandler (struct Hook *) - Optional synchronous selection hook.
For a shortcut, the object is the item and the message is NULL.
PM_AutoPullDown - Presence enables handling MENUDOWN and MENUUP,
even if ti_Data is FALSE.
PM_RawKey (BOOL) - Handle IDCMP_RAWKEY when TRUE; otherwise handle
IDCMP_VANILLAKEY. Default FALSE.
Other tags are forwarded unchanged when a popup is opened.
Selected UserData, or NULL when no item is selected. NULL UserData also returns NULL, so this result is not a message-consumed flag.
The caller must reply to the original message; this function neither replies nor takes ownership. NULL pm or im returns immediately. Shortcuts require IEQUALIFIER_RCOMMAND and match the first command key case-insensitively. Disabled items are ignored. Checkable items toggle, update AutoStore and apply their ID list before the hook. Keep the tree and callback data valid for the whole call. Popup handling can block; call from task context.
Shortcut handling ignores Hidden, NoSelect and Toggle restrictions. Raw key codes are compared directly with command-key bytes without keymap translation. Popup forwarding inherits PM_OpenPopupMenuA() limitations, including ambiguous zero results.
struct PopupMenu * PM_FindItem( struct PopupMenu *menu, ULONG id)
Find the first item with the specified ID. Search each item before its descendants, then continue with its next sibling.
menu - First item of an acyclic menu tree, or NULL. id - Item ID, including zero.
A borrowed pointer to the first match, or NULL if absent.
Hidden, disabled and unselectable items are included. Duplicate IDs are not rejected. The result remains valid only while its item exists; this function neither detaches nor retains it.
void PM_FreeIDList( struct PM_IDLst *list)
Free every node of an ID list allocated by popupmenu.library.
list - First node, or NULL.
None.
Do not free a list still owned by an item. A shared list must remain valid until every referring item has released it; its owner then frees it once. Keep popupmenu.library open until disposal completes.
void PM_FreePopupMenu( struct PopupMenu *p)
Free an item, all following siblings and every descendant. Free copied titles, copied user-data strings and owned ID lists.
p - First item to free, or NULL.
None.
Detach an item before freeing it if following siblings must survive. Do not free a menu while it is displayed or used by a callback. Objects, images, hooks, AutoStore targets, ordinary UserData and shared exclusion lists remain caller-owned. SubDestruct hooks are not called. All pointers to freed items and their owned data become invalid. Keep popupmenu.library open until disposal completes.
LONG PM_GetItemAttrsA( struct PopupMenu *p, struct TagItem *tags)
Copy supported item attributes into caller-provided storage.
p - Item to query, or NULL.
tags - Terminated tag list, or NULL. Each ti_Data is the address
of writable storage of the type stated below.
PM_Title (STRPTR *) - Borrowed copied title, in text mode only. PM_TitleID (ULONG *) - Locale ID, in locale mode only. PM_Object (Object **) - Borrowed object, in object mode only. PM_UserData (APTR *) - Stored user data, including a copied string. PM_ID (ULONG *) - Item ID. PM_Sub, PM_Members (struct PopupMenu **) - Borrowed child list. PM_LayoutMode, PM_Flags (ULONG *) - Layout value or flags. PM_Exclude (struct PM_IDLst **) - Borrowed ID list. PM_ImageSelected, PM_IconSelected (struct Image **) - Selected image. PM_ImageUnselected, PM_IconUnselected (struct Image **) - Normal image. PM_AutoStore (BOOL **) - Borrowed Boolean storage pointer. PM_TextPen (ULONG *) - Stored pen number. PM_CommKey (char *) - One command-key byte; no terminator is written. PM_NoSelect, PM_FillPen, PM_ShadowPen, PM_ShinePen, PM_Checkit, PM_Checked, PM_Italic, PM_Bold, PM_Underlined, PM_TitleBar, PM_WideTitleBar, PM_ExcludeShared, PM_Disabled, PM_Shadowed, PM_Center, PM_Hidden, PM_Toggle (BOOL *) - Corresponding state.
Number of attributes written. Zero for NULL p. Unsupported tags and title queries for an inactive title mode leave storage unchanged.
Tags are processed in order, including repeats. Returned pointers are not copied or retained. Item-owned values become invalid when replaced or when the item is freed. Keep the item stable during the query; the function does not lock it.
PM_TitleBar and PM_WideTitleBar test masks that include the no-selection flag. An unselectable item can therefore report TRUE without having the requested separator style.
STRPTR PM_GetVersion( )
Build a descriptive library-version string, including detected graphics-environment information.
None.
Pointer to a library-owned shared buffer containing a terminated string. Do not modify or free it.
Each call overwrites the buffer. Copy the string before another call or before closing the library. This text is not a numeric version interface; use OpenLibrary() version requirements for compatibility.
LONG PM_InsertMenuItemA( struct PopupMenu *menu, struct TagItem *tags)
Process insertion-method tags and link each subsequent item using the selected method. No item is allocated or copied.
menu - First menu item, or NULL. tags - Terminated tag list, or NULL. Set a method before its items.
PM_Insert_After (struct PopupMenu *) - Insert after this item.
PM_Insert_AfterID (ULONG) - Insert after the first matching ID.
PM_Insert_Before (struct PopupMenu *) - Insert before this item;
the item must have a preceding sibling. See BUGS.
PM_Insert_BeforeID (ULONG) - Find the preceding sibling of the first
matching ID and insert after it. See BUGS for a list head.
PM_Insert_First (BOOL) - TRUE inserts after menu, preserving a header.
PM_Insert_Last (BOOL) - TRUE appends to menu's sibling list.
PM_InsertSub_First (struct PopupMenu *) - Prepend to this item's
children and update its child-list pointer.
PM_InsertSub_Last (struct PopupMenu *) - Append to the sibling chain
starting at this pointer, not to its child list.
PM_InsertSub_Sorted (struct PopupMenu *) - Broken; see BUGS.
PM_Insert_Item (struct PopupMenu *) - Distinct unlinked item to insert.
May repeat. Unknown tags are ignored.
Number of PM_Insert_Item tags with a non-NULL item and a non-NULL selected target. This can exceed the number of successful insertions. Zero for NULL menu.
The target remains unchanged between item tags. Repeated insertion after one target or at the first position reverses item order. A linked item's ownership passes to the menu. Keep an item unowned elsewhere and keep the tree acyclic. Do not alter an active popup.
Sorted insertion never finds an insertion point because the string comparison result is unsigned and tested for less than zero; the item tag can still count. Pointer-based insertion before a list head can create a cycle. BeforeID at a list head inserts after that head. Use a persistent header and avoid these unsupported cases.
BOOL PM_ItemChecked( struct PopupMenu *p, ULONG id)
Read the checked state of the first item with the specified ID.
p - First item of an acyclic menu tree, or NULL. id - Item ID.
TRUE if checked, FALSE if unchecked, or PMERR (-5) if not found.
Test for PMERR before interpreting the result as a Boolean. A missing item produces a nonzero result. PM_Checkit need not be enabled.
LONG PM_LayoutMenuA( struct Window *window, struct PopupMenu *pm, struct TagItem *tags)
Layout is not implemented by this entry point. No menu or window state is changed.
window, pm, tags - Ignored.
Always zero.
struct PM_IDLst * PM_MakeIDListA( struct TagItem *tags)
Allocate an ordered list of item IDs and state operations.
tags - Terminated tag list, or NULL.
PM_ExcludeID (ULONG) - Clear this ID when the source is selected. PM_IncludeID (ULONG) - Check this ID when the source is selected. PM_ReflectID (ULONG) - Check on selection; clear on deselection. PM_InverseID (ULONG) - Clear on selection; check on deselection. Each tag may repeat. Zero is a valid ID. Other tags are ignored.
The new list, or NULL if empty or if any allocation fails. On failure, all nodes allocated by this call are freed.
The list contains IDs, not references to menu items. Missing IDs are skipped when the list is applied. The caller owns the list until it is assigned as an owned PM_Exclude attribute. Otherwise release it with PM_FreeIDList().
struct PopupMenu * PM_MakeItemA( struct TagItem *tags)
Allocate a cleared menu item and apply its attributes in tag order.
tags - Tag list accepted by PM_SetItemAttrsA(), or NULL.
The new item, or NULL if the item allocation fails.
The caller owns the item until it is linked into an owning menu. Release an unlinked item with PM_FreePopupMenu(). Attribute data ownership follows PM_SetItemAttrsA(). Keep popupmenu.library open until its items and ID lists have been released.
Attribute allocation failures do not make this function return NULL. A returned item can have an unset title or copied user-data string.
struct PopupMenu * PM_MakeMenuA( struct TagItem *tags)
Link existing items into a sibling list in tag order. No container item is allocated.
tags - Terminated tag list, or NULL.
PM_Item (struct PopupMenu *) - Item to append. May be repeated.
Supply distinct, unlinked items. Existing child lists remain
attached. Other application tags are ignored.
The first item, or NULL for an empty list or a NULL PM_Item.
Ownership of the supplied items passes to the resulting menu. If any PM_Item is NULL, the scan continues and the entire linked result is freed, including items supplied after the NULL tag. Do not free those items again. Dispose of a successful result with PM_FreePopupMenu(). A menu must be acyclic and must not share owned items with another menu.
APTR PM_OBSOLETEFilterIMsgA( struct Window *window, struct PopupMenu *pm, struct IntuiMessage *im, struct TagItem *tags)
Compatibility stub. No message processing is performed.
window, pm, im, tags - Ignored.
Always NULL.
The caller remains responsible for replying to im.
IPTR PM_OpenPopupMenuA( struct Window *prevwnd, struct TagItem *tags)
Display a popup and process input synchronously until it closes. Update item selection state and invoke the optional menu handler before returning.
prevwnd - Live parent window. NULL uses the active screen, which
must exist and remain available throughout the call.
tags - Terminated option list, or NULL.
PM_Menu (struct PopupMenu *) - Borrow the menu tree for this call.
PM_Left, PM_Top (LONG) - Position relative to the parent window.
Odd left coordinates are increased by one before adding the
parent offset. Defaults use the screen mouse position.
PM_MinWidth, PM_MinHeight (LONG) - Minimum menu dimensions.
PM_Right, PM_Bottom (LONG), PM_CenterScreen (BOOL) - Unsafe positioning
options in this implementation; see BUGS.
PM_ForceFont (struct TextFont *) - Borrow a font for the call.
PM_PullDown (BOOL) - Request a horizontal pulldown. Its effect depends
on the pulldown-position preference; when enabled it moves the
root menu to the screen's top-left corner.
PM_MenuHandler (struct Hook *) - Enable multiple selection. Supply a
valid hook; it receives each selected item after display closes.
Its message points to a temporary IPTR containing zero.
PM_LocaleHook (struct Hook *) - Resolve locale title IDs to readable
strings for measurement and drawing. The item is the hook object.
Returned strings remain caller-owned. See BUGS for message layout.
PM_Code (UWORD) - Input-event code. The release prefix cancels display
and stops processing further tags.
PM_UseLMB (BOOL) - Set button flags; see BUGS.
PM_HintBox - Presence selects hint display, even with FALSE data.
A non-timer input event closes the hint.
Unknown tags, including PM_DRIPensOnly, are ignored.
UserData from the last selected item, represented as IPTR, or zero if no selection was recorded. Selecting an item with NULL UserData also returns zero. There is no separate error result.
Call from task context. The function waits for input and timer messages; there is no caller-selected timeout. It reloads shared preferences and uses temporary windows and an input handler. The menu is borrowed, not freed. Keep its items, images, AutoStore storage, font, hooks and parent screen alive through all callbacks. Do not concurrently modify or free the tree or reenter popup display from a callback. Selection can change checked and AutoStore values. A returned pointer to item-owned UserData remains valid only until that data is replaced or the item is freed.
PM_Right, PM_Bottom and PM_CenterScreen can dereference the root window before it opens. Root-menu and timer allocation failures are not handled safely on all paths; zero is not a reliable failure notification. PM_UseLMB flags are not consulted by selection. The locale hook receives an IPTR array during measurement but a pointer to ULONG during drawing. Do not assume a consistent payload layout on targets where those types differ in size.
void PM_ReloadPrefs( )
Reload shared popup-menu preferences from ENV:sys/PopupMenu.prefs. Use built-in defaults if the preference file cannot be loaded.
None.
None. File and format failures are not reported to the caller.
This operation can perform DOS I/O; call from task context. The settings are shared by library users. Serialize reloads with menu display. PM_OpenPopupMenuA() reloads preferences on each invocation.
struct PopupMenu * PM_RemoveMenuItem( struct PopupMenu *menu, struct PopupMenu *item)
Detach an item from one sibling list without freeing it or its children. The first item in the list cannot be removed.
menu - First item of the sibling list, or NULL. item - Item to detach.
The detached item with its next-sibling link cleared, or NULL if absent or equal to menu.
Descendants are not searched. Pass their own sibling-list head to operate on them. The caller owns a detached item and may reinsert it or free it with PM_FreePopupMenu(). Do not modify an active popup.
LONG PM_SetItemAttrsA( struct PopupMenu *p, struct TagItem *tags)
Apply item attributes in tag order. Changes take effect immediately; allocation failures do not roll back earlier changes.
p - Item to change, or NULL. tags - Terminated tag list, or NULL. ti_Data contains the value.
PM_Title (STRPTR) - Copy a terminated string; NULL clears the title.
PM_TitleID (ULONG) - Store a locale string ID instead of a title.
PM_Object (Object *) - Borrow an object instead of a title.
PM_UserData (APTR) - Borrow arbitrary data returned on selection.
PM_UserDataString (STRPTR) - Copy a non-NULL terminated string.
PM_ID (ULONG) - Set the item ID.
PM_Sub (struct PopupMenu *) - Replace and own the child list, or
clear it with NULL. Free the old children and select normal
submenu mode. Do not pass the current list or its descendants.
PM_Members (struct PopupMenu *) - Replace and own group children.
Free the old list; use horizontal layout if layout was zero.
PM_LayoutMode (ULONG) - Set layout; nonzero enables group mode.
PML_Horizontal and PML_Vertical select the respective directions.
PM_Flags (ULONG) - Replace all flags, including ownership flags.
Reserved for callers that preserve the item's ownership state.
PM_NoSelect (BOOL) - Set or clear the no-selection flag.
PM_Disabled (BOOL) - Set or clear disabled and no-selection flags.
PM_FillPen, PM_ShadowPen, PM_ShinePen (BOOL) - Enable the respective
DrawInfo text-pen flag independently.
PM_Italic, PM_Bold, PM_Underlined (BOOL) - Set text-style flags.
PM_Shadowed, PM_Center (BOOL) - Enable shadowed or centered text.
PM_TextPen (ULONG) - Set a custom text pen, stored as an unsigned byte.
PM_TitleBar, PM_WideTitleBar (BOOL) - Set or clear separator masks,
which also include the no-selection flag.
PM_Checkit (BOOL) - Enable checkmark space.
PM_Checked (BOOL) - Set checked and initial-checked flags. Does not
write through an existing AutoStore pointer.
PM_Toggle (BOOL) - Allow a checked item to be toggled off by popup
selection; initially TRUE.
PM_AutoStore (BOOL *) - Borrow writable Boolean storage, or detach
with NULL. Read its current value into the checked flag now.
PM_Exclude (struct PM_IDLst *) - Attach an ID list. Free the old list
unless the current ExcludeShared flag is set. See BUGS for NULL.
PM_ExcludeShared (BOOL) - Suppress freeing the attached ID list when
TRUE. The caller owns a shared list and must keep it alive.
PM_ImageSelected, PM_ImageUnselected (struct Image *) - Borrow the
selected or normal image and enable image mode. If the opposite
slot is empty, assign the same pointer to it.
PM_IconSelected, PM_IconUnselected (struct Image *) - Assign the same
slots but select icon mode; fill an empty opposite slot as above.
PM_CommKey (char *) - Copy the first byte from a readable pointer.
NULL leaves the key unchanged. This is not a numeric character.
PM_ColourBox (ULONG) - Enable a colour box; store the pen as a byte.
PM_SubConstruct, PM_SubDestruct (struct Hook *) - Borrow submenu hooks.
Construction receives the parent item and an IPTR message holding
an opaque handle; return the child list or NULL to cancel.
Destruction receives the parent item and a NULL message.
PM_Hidden (BOOL) - Set or clear hidden state.
Number of processed attributes, excluding unsupported tags and failed string copies. PM_Title with NULL clears the title but does not count. Zero for NULL p. The count is not an all-or-nothing success result.
Replace title modes only with independent input: an owned old title is freed before the new title is copied. The same restriction applies to copied user data. Replaced children and owned ID lists are freed before assignment. Shared-list flags affect the old list at the time of replacement, so tag order changes ownership behaviour. Keep borrowed objects, images, hooks and AutoStore storage valid while the item uses them. Serialize menu changes with display, traversal and callbacks. This function performs no redraw. Dynamic submenu hooks run synchronously during popup use; the destructor is also called if construction returns NULL. PM_FreePopupMenu() does not invoke that destructor.
PM_Exclude with NULL can free the old list while leaving its address attached. Do not use it to detach an existing list. BOOPSI layout and rendering are incomplete; PM_Object does not provide a usable object-rendering contract. A constructor without an existing child list does not enter the submenu-opening path.