AV_Layer.AVTool (Acrobat)

	Typedef
	AVTool A data structure for a tool. It contains callbacks that implement the tool's functions (for example, handling mouse clicks and controlling the cursor shape).
	AVTool
	AVToolRec

	Enumeration
	`AVToolMouseWheelDirection` (Acrobat 7.0 and later) Describes the direction of mouse wheel movement.
	`AVToolsMenuOrderNumbers` This enumerates the order of the toolbars listed in the Tools menu.

	Structure
	_t_AVTool A data structure for a tool. It contains callbacks that implement the tool's functions (for example, handling mouse clicks and controlling the cursor shape).

	Callback
	ActivateProcType A callback for AVTool. It is called when this tool has become the active tool. It is allowed to call AVAppGetActiveTool() from within this method or from DeactivateProcType(); it will return this tool object. Call AVAppGetLastActiveTool() to get the formerly active tool object (its DeactivateProcType() method will already have been called).
	AdjustCursorProcType (Optional) A callback for AVTool. This callback controls the cursor shape when the tool is the active tool.
	AVToolDestroyProc An AVToolRec callback. If provided, it is called at shutdown time to allow the tool to free dynamic memory.
	AVToolEnumProc A callback for AVAppEnumTools(). It is called once for each tool.
	AVToolGetLabelIconProc A callback for AVToolRec. If provided, it is called when a static tool icon is needed. This icon should be similar to, but not the same as the tool button icon for this tool.
	AVToolGetLabelProc A callback for AVToolRec. If provided, it is called when text describing the tool needs to be displayed.
	AVToolGetToolTipProc (Acrobat 10.0 and later) A callback for AVToolRec. If provided, it is called when a tooltip is needed.
	DeactivateProcType A callback for AVTool. It is called when the tool will no longer be the active tool.

	Method
	ASAtom AVToolGetType(AVTool tool) Gets the currently active tools's type. See Toolbar and Toolbar Button Names for a list of the built-in tool types.
	ASBool AVToolIsPersistent(AVTool tool) Tests whether the specified tool is in a state keeping it active through multiple operations rather than only once, then restoring the previous tool. This method is called by another one-shot tool's Activate procedure. Two one-shot tools cannot cycle, because if the previous tool was not persistent, the second non-persistent tool reverts to the default tool.

Typedefs Detail

AVTool

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

typedef _t_AVTool AVTool;

A data structure for a tool. It contains callbacks that implement the tool's functions (for example, handling mouse clicks and controlling the cursor shape).

It handles key presses and mouse clicks in the content region of an AVPageView. AVTool objects do not handle mouse clicks in other parts of the viewer's window, such as in the bookmark pane. At any time, there is one active tool.

File: AVExpT.h

Line: 4454

AVTool

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

typedef _t_AVTool AVTool;

File: AVExpTObsolete1.h

Line: 136

AVToolRec

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

typedef _t_AVTool AVToolRec;

File: AVExpT.h

Line: 4778

Enumeration Detail

AVToolMouseWheelDirection

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

enum AVToolMouseWheelDirection {

  AVToolMouseWheelUp,


 


  AVToolMouseWheelDown

}

See Also

HandleMouseWheelScroll

File: AVExpT.h

Line: 4622

AVToolsMenuOrderNumbers

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

enum AVToolsMenuOrderNumbers {

  kAVCommentingMenuOrder = 100,


 


  kAVAdvCommentingMenuOrder = 200,


 


  kAVSelectionMenuOrder = 300,


 


  kAVZoomMenuOrder = 400,


 


  kAVNavigationMenuOrder = 500,


 


  kAVAdvEditingMenuOrder = 600,


 


  kAVMeasuringMenuOrder = 700,


 


  kAVRotateViewMenuOrder = 800,


 


  kAVFindMenuOrder = 900,


 


  kAVEndMenuOrder = kASMAXEnum16

}

File: AVExpT.h

Line: 10039

Structure Detail

_t_AVTool

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

struct _t_AVTool {

  ASSize_t size;  


 


  ActivateProcType Activate;  


 


  DeactivateProcType Deactivate;  


 


  DoKeyDownProcType DoKeyDown;  


 


  GetTypeProcType GetType;  


 


  IsPersistentProcType IsPersistent;  


 


  AVCursorID cursorID;  


 


  AVComputeEnabledProc ComputeEnabled;  


 


  void* computeEnabledData;  


 


  DoLeaveProcType DoLeave;  


 


  GetSelectionServerProcType GetSelectionServer;  


 


  DoClickProcType DoClick;  


 


  AdjustCursorProcType AdjustCursor;  


 


  DoClickProcType DoRightClick;  


 


  void* clientData;  


 


  AVToolDestroyProc Destroy;  


 


  AVToolGetLabelIconProc GetLabelIcon;  


 


  HandleMouseWheelScrollProc HandleMouseWheel;  


 


  AVToolGetLabelProc GetLabel;  


 


  AVToolGetToolTipProc GetToolTip;  

}

A data structure for a tool. It contains callbacks that implement the tool's functions (for example, handling mouse clicks and controlling the cursor shape).

File: AVExpT.h

Line: 4673

Elements

	size	The size of the data structure. It must be set to `sizeof(AVToolRec)`.

	Activate	This method is called when this tool has become the active tool. It is allowed to call AVAppGetActiveTool() from within this method or from Deactivate(); it will return this tool object. Call AVAppGetLastActiveTool() to get the formerly active tool object (its Deactivate() method will already have been called). If `persistent` is `true` and has meaning for this tool, it means that the tool should remain active through an arbitrary number of operations (whatever that means for a particular tool), rather than performing a single action (as a one shot) and then restoring the previously active tool. If `persistent` is `false`, the opposite is implied.

	IsPersistent	Returns `true` if the tool is persistent at this time (this may be `false` even though Active was called with `persistent = true`, or vice-versa). If it is `NULL`, AVToolIsPersistent() will return `true`.

	cursorID	A default cursor, used if the tool does not have an AdjustCursorProcType() callback. It is ignored if AdjustCursor() is non-`NULL`; if AdjustCursor() is `NULL`, the default AdjustCursor() implementation will set the cursor to the result of calling `AVSysGetStandardCursor(cursorId)` unless a hit annotation sets the cursor. The default AdjustCursor() is appropriate for most tool implementations. See the ZoomTool implementation for an example of a private AdjustCursor() implementation.

	ComputeEnabled	Returns `true` if the tool is enabled (legal). It is legal if the front-most document permits the tool's operation. It will only be called if there is a front-most document. If it is `NULL`, the tool is always enabled.

	computeEnabledData	User-supplied data to pass to the tool's AVComputeEnabledProc() callback each time it is called.

	clientData	clientData - use to store pointer to private data or store your this pointer

	GetLabel	Return a label for use in buttons or menus

	GetToolTip	Return a tooltip for use in buttons or menus

Callbacks Detail

ActivateProcType

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

void (*ActivateProcType)(AVTool tool, ASBool persistent)

A callback for AVTool. It is called when this tool has become the active tool. It is allowed to call AVAppGetActiveTool() from within this method or from DeactivateProcType(); it will return this tool object. Call AVAppGetLastActiveTool() to get the formerly active tool object (its DeactivateProcType() method will already have been called).

See Also

DeactivateProcType

File: AVExpT.h

Line: 4513

AdjustCursorProcType

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool (*AdjustCursorProcType)(AVTool tool, AVPageView pageView, AVDevCoord x, AVDevCoord y)

(Optional) A callback for AVTool. This callback controls the cursor shape when the tool is the active tool.

If omitted, the cursor specified in the tool's cursorID field is used.

See Also

AVAppRegisterTool

File: AVExpT.h

Line: 4471

AVToolDestroyProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

void (*AVToolDestroyProc)(AVTool tool)

An AVToolRec callback. If provided, it is called at shutdown time to allow the tool to free dynamic memory.

File: AVExpT.h

Line: 4587

AVToolEnumProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool (*AVToolEnumProc)(AVTool tool, void *clientData)

A callback for AVAppEnumTools(). It is called once for each tool.

See Also

AVAppEnumTools

File: AVExpT.h

Line: 4791

AVToolGetLabelIconProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

AVIcon (*AVToolGetLabelIconProc)(AVTool tool)

A callback for AVToolRec. If provided, it is called when a static tool icon is needed. This icon should be similar to, but not the same as the tool button icon for this tool.

File: AVExpT.h

Line: 4604

AVToolGetLabelProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

void (*AVToolGetLabelProc)(AVTool tool, ASText label)

A callback for AVToolRec. If provided, it is called when text describing the tool needs to be displayed.

File: AVExpT.h

Line: 4595

AVToolGetToolTipProc

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

void (*AVToolGetToolTipProc)(AVTool tool, ASText tip)

(Acrobat 10.0 and later) A callback for AVToolRec. If provided, it is called when a tooltip is needed.

File: AVExpT.h

Line: 4613

DeactivateProcType

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax

void (*DeactivateProcType)(AVTool tool)

A callback for AVTool. It is called when the tool will no longer be the active tool.

See Also

ActivateProcType
AVAppSetActiveTool

File: AVExpT.h

Line: 4522

Method Detail

AVToolGetType

()

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax





ASAtom AVToolGetType(AVTool tool)

Gets the currently active tools's type. See Toolbar and Toolbar Button Names for a list of the built-in tool types.

Parameters

tool —

The tool whose type is obtained.

Returns

The ASAtom returned can be converted to a string using ASAtomGetString().

Since

PI_ACROVIEW_VERSION >= 0x00020000

File: AVProcs.h

Line: 2843

AVToolIsPersistent

()

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax





ASBool AVToolIsPersistent(AVTool tool)

Tests whether the specified tool is in a state keeping it active through multiple operations rather than only once, then restoring the previous tool. This method is called by another one-shot tool's Activate procedure. Two one-shot tools cannot cycle, because if the previous tool was not persistent, the second non-persistent tool reverts to the default tool.

Parameters

tool —

IN/OUT The tool whose persistence flag is tested.

Returns

true if the tool is persistent, false otherwise.

Since

PI_ACROVIEW_VERSION >= 0x00020000

File: AVProcs.h

Line: 2864

Acrobat API Reference	All Layers \| All Objects \| Index \| Samples \| Frames No Frames
AVTool	Typedefs \| Enumerations \| Structures \| Callbacks \| Methods

	kAVCommentingMenuOrder = 100,

	kAVAdvCommentingMenuOrder = 200,

	kAVSelectionMenuOrder = 300,

	kAVZoomMenuOrder = 400,

	kAVNavigationMenuOrder = 500,

	kAVAdvEditingMenuOrder = 600,

	kAVMeasuringMenuOrder = 700,

	kAVRotateViewMenuOrder = 800,

	kAVFindMenuOrder = 900,

	kAVEndMenuOrder = kASMAXEnum16

	ASSize_t size;

	ActivateProcType Activate;

	DeactivateProcType Deactivate;

	DoKeyDownProcType DoKeyDown;

	GetTypeProcType GetType;

	IsPersistentProcType IsPersistent;

	AVCursorID cursorID;

	AVComputeEnabledProc ComputeEnabled;

	void* computeEnabledData;

	DoLeaveProcType DoLeave;

	GetSelectionServerProcType GetSelectionServer;

	DoClickProcType DoClick;

	AdjustCursorProcType AdjustCursor;

	DoClickProcType DoRightClick;

	void* clientData;

	AVToolDestroyProc Destroy;

	AVToolGetLabelIconProc GetLabelIcon;

	HandleMouseWheelScrollProc HandleMouseWheel;

	AVToolGetLabelProc GetLabel;

	AVToolGetToolTipProc GetToolTip;

Layer	AV_Layer
Object	AVTool

	AVToolMouseWheelUp,

	AVToolMouseWheelDown