PM_AbortHook()
Synopsis
BOOL PM_AbortHook(
APTR handle)
Function
Check whether the pointer has left the item whose submenu is being
constructed. An existing child window may also be refreshed.
Result
TRUE if the pointer is outside the selected item; FALSE otherwise.
Notes
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.
PM_AlterState()
Synopsis
void PM_AlterState(
struct PopupMenu *pm, struct PM_IDLst *l, UWORD action)
Function
Apply each ID-list operation to the first matching menu item. Update
its checked and selected flags and any attached AutoStore value.
Notes
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.
PM_ExLstA()
Synopsis
struct PM_IDLst * PM_ExLstA(
ULONG *id)
Function
Create an exclusion list from an array of item IDs.
Result
The new list, or NULL for an empty array or any allocation failure.
On failure, all nodes allocated by this call are freed.
Notes
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().
PM_FilterIMsgA()
Synopsis
APTR PM_FilterIMsgA(
struct Window *w, struct PopupMenu *pm, struct IntuiMessage *im, struct TagItem *tags)
Function
Handle right-command shortcuts or forward menu-button events to
PM_OpenPopupMenuA().
Result
Selected UserData, or NULL when no item is selected. NULL UserData
also returns NULL, so this result is not a message-consumed flag.
Notes
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.
Bugs
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.
PM_FindItem()
Synopsis
struct PopupMenu * PM_FindItem(
struct PopupMenu *menu, ULONG id)
Function
Find the first item with the specified ID. Search each item before
its descendants, then continue with its next sibling.
Result
A borrowed pointer to the first match, or NULL if absent.
Notes
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.
PM_FreeIDList()
Synopsis
void PM_FreeIDList(
struct PM_IDLst *list)
Function
Free every node of an ID list allocated by popupmenu.library.
Notes
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.
PM_GetItemAttrsA()
Synopsis
LONG PM_GetItemAttrsA(
struct PopupMenu *p, struct TagItem *tags)
Function
Copy supported item attributes into caller-provided storage.
Result
Number of attributes written. Zero for NULL p. Unsupported tags and
title queries for an inactive title mode leave storage unchanged.
Notes
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.
Bugs
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.
PM_GetVersion()
Synopsis
STRPTR PM_GetVersion(
)
Function
Build a descriptive library-version string, including detected
graphics-environment information.
Result
Pointer to a library-owned shared buffer containing a terminated
string. Do not modify or free it.
Notes
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.
PM_ItemChecked()
Synopsis
BOOL PM_ItemChecked(
struct PopupMenu *p, ULONG id)
Function
Read the checked state of the first item with the specified ID.
Result
TRUE if checked, FALSE if unchecked, or PMERR (-5) if not found.
Notes
Test for PMERR before interpreting the result as a Boolean. A missing
item produces a nonzero result. PM_Checkit need not be enabled.
PM_MakeIDListA()
Synopsis
struct PM_IDLst * PM_MakeIDListA(
struct TagItem *tags)
Function
Allocate an ordered list of item IDs and state operations.
Result
The new list, or NULL if empty or if any allocation fails. On failure,
all nodes allocated by this call are freed.
Notes
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().
PM_MakeItemA()
Synopsis
struct PopupMenu * PM_MakeItemA(
struct TagItem *tags)
Function
Allocate a cleared menu item and apply its attributes in tag order.
Result
The new item, or NULL if the item allocation fails.
Notes
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.
Bugs
Attribute allocation failures do not make this function return NULL.
A returned item can have an unset title or copied user-data string.
PM_OBSOLETEFilterIMsgA()
Synopsis
APTR PM_OBSOLETEFilterIMsgA(
struct Window *window, struct PopupMenu *pm, struct IntuiMessage *im, struct TagItem *tags)
Function
Compatibility stub. No message processing is performed.
Notes
The caller remains responsible for replying to im.
PM_SetItemAttrsA()
Synopsis
LONG PM_SetItemAttrsA(
struct PopupMenu *p, struct TagItem *tags)
Function
Apply item attributes in tag order. Changes take effect immediately;
allocation failures do not roll back earlier changes.
Result
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.
Notes
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.
Bugs
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.