AV_Layer.AVMenu (Acrobat)

	Define
	kAVMenuKeyEnabled
	kAVMenuKeyHelpText
	kAVMenuKeyIcon
	kAVMenuKeyMarked
	kAVMenuKeyName
	kAVMenuKeyShortcut
	kAVMenuKeyShortcutFlags
	kAVMenuKeyTitle
	kAVMenuKeyTitleChanges
	kAVMenuKeyVisible

	Typedef
	AVMenu A menu in the Acrobat viewer's menu bar. Plug-ins can create new menus, add menu items at any location in any menu, and remove menu items. Deleting an AVMenu removes it from the menu bar (if it was attached) and deletes all the menu items it contains.
	AVMenuIndex A menu index value that indicates a user's choice in a popup menu. It uses negative indices for errors.

	Callback
	AVMenuPredicate A callback that is called for each menu enumerated by AVMenubarAcquireMenuByPredicate(). The first menu for which this callback returns true is acquired.

	Method
	AVMenu AVMenuAcquire(AVMenu menu) Acquires the specified menu. It increments the menu's reference count. When you are done using the menu item, release it using AVMenuRelease().
	AVMenuItem AVMenuAcquireMenuItemByIndex(AVMenu menu, AVMenuIndex menuItemIndex) Acquires the menu item at the specified location in the specified menu. When you are done using the menu item, release it using AVMenuItemRelease(). Menu item indices are generally not reliable: they change as clients add, remove, or rearrange menu items, and may differ in different versions of the Acrobat viewer (if menu items are rearranged, removed, or added). Menu items should generally be acquired using AVMenubarAcquireMenuItemByName(), which is generally reliable.
	void AVMenuAddMenuItem(AVMenu menu, AVMenuItem menuItem, AVMenuIndex menuItemIndex) Inserts a menu item in a specified location in a menu, and acquires the item. It does nothing if the menu or menu item is NULL, or the menu item is already in a menu.
	AVMenu AVMenuClone(AVMenu menu) (New in Acrobat 5.0.5)
	AVMenuItem AVMenuDoPopUp(AVMenu menu, ASInt16 x, ASInt16 y, ASBool rightButton, ASInt32 choice) Pops up a submenu.
	AVMenuIndex AVMenuGetMenuItemIndex(AVMenu menu, AVMenuItem menuItem) Gets the index of the specified menu item in the specified menu.
	ASAtom AVMenuGetName(AVMenu menu) Gets the ASAtom for the menu's language-independent name.
	AVTArraySize AVMenuGetNumMenuItems(AVMenu menu) Gets the number of menu items in a menu, including those that are visible only in long-menus mode.
	AVMenubar AVMenuGetParentMenubar(AVMenu menu) Gets the parent menu bar for the specified menu.
	AVMenuItem AVMenuGetParentMenuItem(AVMenu menu) Gets the parent menu item for the specified menu.
	AVTArraySize AVMenuGetTitle(AVMenu menu, char* buffer, AVTArraySize bufferSize) Gets the menu's title as it appears in the user interface. The length of the title remains 0 if menu is NULL.
	void AVMenuGetTitleAsASText(AVMenu menu, ASText title) Gets the menu's title as it appears in the user interface, as an ASText object.
	ASBool AVMenuIsHiddenOnMenubar(AVMenu menu) Tests whether a menu is hidden on the menu bar.
	AVMenu AVMenuNew(const char* title, const char* name, ASExtension owner) Creates and acquires a new menu with the given title and language-independent name. The menu can be added to the menu bar using AVMenubarAddMenu(). When you are done using the menu, release it using AVMenuRelease().
	AVMenu AVMenuNewWithASText(ASConstText title, const char* name, ASExtension owner) Creates and acquires a new menu with the given title and language-independent name. The menu can be added to the menu bar using AVMenubarAddMenu(). When you are done using the menu, release it using AVMenuRelease().
	void AVMenuRelease(AVMenu menu) Releases the specified menu. It decrements the reference count and automatically destroys the menu when its reference count is zero.
	void AVMenuRemove(AVMenu menu) Removes a menu from the menu bar and releases it. If the menu is a submenu, this method does nothing.

Defines Detail

kAVMenuKeyEnabled

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax


#define kAVMenuKeyEnabled Enabled"

File: AVExpT.h

Line: 9909

kAVMenuKeyHelpText

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax


#define kAVMenuKeyHelpText HelpText"

File: AVExpT.h

Line: 9914

kAVMenuKeyIcon

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax


#define kAVMenuKeyIcon Icon"

File: AVExpT.h

Line: 9908

kAVMenuKeyMarked

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax


#define kAVMenuKeyMarked Marked"

File: AVExpT.h

Line: 9910

kAVMenuKeyName

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax


#define kAVMenuKeyName Name"

File: AVExpT.h

Line: 9905

kAVMenuKeyShortcut

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax


#define kAVMenuKeyShortcut Shortcut"

File: AVExpT.h

Line: 9912

kAVMenuKeyShortcutFlags

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax


#define kAVMenuKeyShortcutFlags ShortcutFlags"

File: AVExpT.h

Line: 9913

kAVMenuKeyTitle

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax


#define kAVMenuKeyTitle Title"

File: AVExpT.h

Line: 9906

kAVMenuKeyTitleChanges

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax


#define kAVMenuKeyTitleChanges TitleChanges"

File: AVExpT.h

Line: 9907

kAVMenuKeyVisible

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax


#define kAVMenuKeyVisible Visible"

File: AVExpT.h

Line: 9911

Typedefs Detail

AVMenu

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

typedef struct _t_AVMenu* AVMenu;

A menu in the Acrobat viewer's menu bar. Plug-ins can create new menus, add menu items at any location in any menu, and remove menu items. Deleting an AVMenu removes it from the menu bar (if it was attached) and deletes all the menu items it contains.

File: AVExpT.h

Line: 1279

AVMenuIndex

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

typedef ASInt32 AVMenuIndex;

A menu index value that indicates a user's choice in a popup menu. It uses negative indices for errors.

File: AVExpT.h

Line: 265

Callbacks Detail

AVMenuPredicate

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool (*AVMenuPredicate)(AVMenu menu, void *clientData)

A callback that is called for each menu enumerated by AVMenubarAcquireMenuByPredicate(). The first menu for which this callback returns true is acquired.

See Also

AVMenubarAcquireMenuByPredicate

File: AVExpT.h

Line: 1293

Method Detail

AVMenuAcquire

()

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax





AVMenu AVMenuAcquire(AVMenu menu)

Acquires the specified menu. It increments the menu's reference count. When you are done using the menu item, release it using AVMenuRelease().

Parameters

menu —

IN/OUT The menu to acquire.

Returns

The menu acquired.

Since

PI_ACROVIEW_VERSION >= 0x00020000

File: AVProcs.h

Line: 1515

AVMenuAcquireMenuItemByIndex

()

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax





AVMenuItem AVMenuAcquireMenuItemByIndex(AVMenu menu, AVMenuIndex menuItemIndex)

Acquires the menu item at the specified location in the specified menu. When you are done using the menu item, release it using AVMenuItemRelease(). Menu item indices are generally not reliable: they change as clients add, remove, or rearrange menu items, and may differ in different versions of the Acrobat viewer (if menu items are rearranged, removed, or added). Menu items should generally be acquired using AVMenubarAcquireMenuItemByName(), which is generally reliable.

Parameters

	`menu` —	The menu in which a menu item is acquired.

	`menuItemIndex` —	The index of the menu item in `menu` to acquire. The first item in a menu has an index of zero. Even if the Acrobat viewer is displaying short menus, the index includes any intervening long-mode-only menu items (irrelevant for Acrobat 3.0 or later since there are no short menus).

Returns

The menu item whose index is specified. It returns NULL if menu is NULL, if the index is less than zero, or the index is greater than the number of menu items in the menu.

Since

PI_ACROVIEW_VERSION >= 0x00020000

File: AVProcs.h

Line: 1622

AVMenuAddMenuItem

()

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax





void AVMenuAddMenuItem(AVMenu menu, AVMenuItem menuItem, AVMenuIndex menuItemIndex)

Inserts a menu item in a specified location in a menu, and acquires the item. It does nothing if the menu or menu item is NULL, or the menu item is already in a menu.

Parameters

	`menu` —	The menu to which a menu item is added.

	`menuItem` —	The menu item to add.

	`menuItemIndex` —	The location in `menu` to add `menuItem`. The first item in a menu has an index of zero. Even if the Acrobat viewer is displaying short menus, the index includes any intervening long-mode-only menu items (irrelevant for Acrobat 3.0 or later since there are no short menus). Pass APPEND_MENUITEM (see AVExpT.h) to append the menu item to the end of the menu.

See Also

AVMenuItemRemove

Exceptions

genErrNoMemory

Since

PI_ACROVIEW_VERSION >= 0x00020000

File: AVProcs.h

Line: 1704

AVMenuClone

()

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax





AVMenu AVMenuClone(AVMenu menu)

(New in Acrobat 5.0.5)

Clones a menu, creating a new menu which is an exact duplicate of the original, except that shortcuts are not created for the items.

Parameters

menu —

The menu that is cloned.

Returns

The new menu.

Since

PI_ACROVIEW_VERSION >= 0x00050001

File: AVProcs.h

Line: 6177

AVMenuDoPopUp

()

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax





AVMenuItem AVMenuDoPopUp(AVMenu menu, ASInt16 x, ASInt16 y, ASBool rightButton, ASInt32 choice)

Pops up a submenu.

Parameters

	`menu` —	The menu to be displayed.

	`x` —	The x-coordinate of the upper left corner of the menu.

	`y` —	The y-coordinate of the upper left corner of the menu.

	`rightButton` —	`true` if the right mouse button (where applicable) was used to invoke the popup, `false` otherwise.

	`choice` —	The index of the AVMenuItem that should appear under the mouse at popup time.

Returns

The menu item selected from menu.

See Also

AVPageViewDoPopupMenu

Since

PI_ACROVIEW_VERSION >= 0x00060000

File: AVProcs.h

Line: 7786

AVMenuGetMenuItemIndex

()

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax





AVMenuIndex AVMenuGetMenuItemIndex(AVMenu menu, AVMenuItem menuItem)

Gets the index of the specified menu item in the specified menu.

Indices must be used with caution, because they change as clients add, remove, or rearrange menu items.

Parameters

	`menu` —	The menu in which `menuItem` is located.

	`menuItem` —	The menu item whose index is obtained.

Returns

The index of menuItem in menu. The first item in a menu has an index of zero. Even if the Acrobat viewer is displaying short menus, the index includes any intervening long-mode-only menu items (irrelevant for Acrobat 3.0 or later since there are no short menus).

BAD_MENUITEM_INDEX (see AVExpT.h) if menuItem is not in menu, if menu is NULL, or menuItem is NULL.

See Also

AVMenuGetNumMenuItems

Since

PI_ACROVIEW_VERSION >= 0x00020000

File: AVProcs.h

Line: 1644

AVMenuGetName

()

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax





ASAtom AVMenuGetName(AVMenu menu)

Gets the ASAtom for the menu's language-independent name.

Parameters

menu —

IN/OUT The menu whose language-independent name is obtained.

Returns

The menu's name. The ASAtom can be converted to a string using ASAtomGetString(). It returns NULL if menu is NULL.

See Also

AVMenuAcquire
AVMenuGetTitle
AVMenuNew

Since

PI_ACROVIEW_VERSION >= 0x00020000

File: AVProcs.h

Line: 1562

AVMenuGetNumMenuItems

()

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax





AVTArraySize AVMenuGetNumMenuItems(AVMenu menu)

Gets the number of menu items in a menu, including those that are visible only in long-menus mode.

Parameters

menu —

IN/OUT The menu for which the number of menu items is obtained.

Returns

The number of menu items in the specified menu. It returns 0 if menu is NULL.

See Also

AVMenuAcquireMenuItemByIndex

Since

PI_ACROVIEW_VERSION >= 0x00020000

File: AVProcs.h

Line: 1593

AVMenuGetParentMenubar

()

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax





AVMenubar AVMenuGetParentMenubar(AVMenu menu)

Gets the parent menu bar for the specified menu.

Parameters

menu —

IN/OUT The menu whose parent menu bar is obtained.

Returns

The menu bar to which the menu is attached. It returns NULL if the menu has not yet been added to the menu bar, or if the menu is a submenu.

Since

PI_ACROVIEW_VERSION >= 0x00020000

File: AVProcs.h

Line: 1667

AVMenuGetParentMenuItem

()

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax





AVMenuItem AVMenuGetParentMenuItem(AVMenu menu)

Gets the parent menu item for the specified menu.

Parameters

menu —

IN/OUT The menu whose parent menu item is obtained.

Returns

The menu item for which the specified menu is a submenu. Returns NULL if the specified menu is not a submenu.

Since

PI_ACROVIEW_VERSION >= 0x00020000

File: AVProcs.h

Line: 1685

AVMenuGetTitle

()

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax





AVTArraySize AVMenuGetTitle(AVMenu menu, char* buffer, AVTArraySize bufferSize)

Gets the menu's title as it appears in the user interface. The length of the title remains 0 if menu is NULL.

Parameters

	`menu` —	The menu whose title is obtained.

	`buffer` —	(Filled by the method) A buffer into which the title is copied. If `buffer` is `NULL`, it is not filled; the length of the title is still returned.

	`bufferSize` —	The maximum number of characters the buffer can hold.

Returns

If menu is non-zero, the length of the title is returned. If menu is NULL and buffer is not, buffer is zeroed. It returns 0 if buffer is NULL.

Since

PI_ACROVIEW_VERSION >= 0x00020000

File: AVProcs.h

Line: 1581

AVMenuGetTitleAsASText

()

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax





void AVMenuGetTitleAsASText(AVMenu menu, ASText title)

Gets the menu's title as it appears in the user interface, as an ASText object.

Parameters

	`menu` —	The menu whose title is obtained.

	`title` —	(Filled by the method) The text object containing the title.

Since

PI_ACROVIEW_VERSION >= 0x00060000

File: AVProcs.h

Line: 8168

AVMenuIsHiddenOnMenubar

()

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax





ASBool AVMenuIsHiddenOnMenubar(AVMenu menu)

Tests whether a menu is hidden on the menu bar.

Parameters

menu —

IN/OUT The menu to test.

Returns

true if menu is hidden, false otherwise.

See Also

AVMenubarAddHiddenMenu

Since

PI_ACROVIEW_VERSION >= 0x00040000

File: AVProcs.h

Line: 4397

AVMenuNew

()

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax





AVMenu AVMenuNew(const char* title, const char* name, ASExtension owner)

Creates and acquires a new menu with the given title and language-independent name. The menu can be added to the menu bar using AVMenubarAddMenu(). When you are done using the menu, release it using AVMenuRelease().

Parameters

	`title` —	The string that appears in the user interface. On Windows, an ampersand (`&`) character in the string results in underlining the character after it on the menu.

	`name` —	The language-independent name of the menu to create: it is the value returned by AVMenuGetName(). It must not contain any spaces. Developers should prefix the names of menus they add with the name of their client and a colon, to avoid collisions in the menu name space. For example, a client named `myPlug` might add menus named `myPlug:DrawTools` and `myPlug:Checkout`.

	`owner` —	The `gExtensionID` extension registering the menu.

Returns

The newly created menu.

Exceptions

genErrNoMemory

Since

PI_ACROVIEW_VERSION >= 0x00020000

File: AVProcs.h

Line: 1500

AVMenuNewWithASText

()

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax





AVMenu AVMenuNewWithASText(ASConstText title, const char* name, ASExtension owner)

Parameters

	`title` —	A constant text object containing the string that appears in the user interface. On Windows, an ampersand (`&`) character in the string results in underlining the character after it on the menu.

	`name` —	A language-independent name of the menu to create: it is the value returned by AVMenuGetName(). It must not contain any spaces. Developers should prefix the names of menus they add with the name of their client and a colon, to avoid collisions in the menu name space. For example, a client named `myPlug` might add menus named `myPlug:DrawTools` and `myPlug:Checkout`.

	`owner` —	The gExtensionID extension registering the menu.

Returns

The newly created menu.

Exceptions

genErrNoMemory

Since

PI_ACROVIEW_VERSION >= 0x00060000

File: AVProcs.h

Line: 8154

AVMenuRelease

()

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax





void AVMenuRelease(AVMenu menu)

Releases the specified menu. It decrements the reference count and automatically destroys the menu when its reference count is zero.

Parameters

menu —

The menu to release.

See Also

AVMenuAcquire
AVMenuNew

Since

PI_ACROVIEW_VERSION >= 0x00020000

File: AVProcs.h

Line: 1526

AVMenuRemove

()

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax





void AVMenuRemove(AVMenu menu)

Removes a menu from the menu bar and releases it. If the menu is a submenu, this method does nothing.

Parameters

menu —

IN/OUT The menu to remove.

See Also

AVMenuItemRemove
AVMenuRelease

Since

PI_ACROVIEW_VERSION >= 0x00020000

File: AVProcs.h

Line: 1543

Acrobat API Reference	All Layers \| All Objects \| Index \| Samples \| Frames No Frames
AVMenu	Defines \| Typedefs \| Callbacks \| Methods

Layer	AV_Layer
Object	AVMenu