---

PDFAnnotationButtonWidget Class Reference

Overview

A PDFAnnotationButtonWidget object provides user interactivity on a page of a PDF document. There are three types of buttons available: push button, radio button, and checkbox.

PDFAnnotationButtonWidget inherits general annotation behavior from the PDFAnnotation class. If you use a PDFAnnotationButtonWidget object, your application must handle hit testing, unless you are simply using PDFView to display content. This is because PDFView automatically handles hit testing for you.

Tasks

Getting and Setting the Control Type

• – controlType
• – setControlType
• – parentID

Getting and Setting the Control’s State

• – state
• – setState:

Getting and Setting the Control’s Appearance

• – isHighlighted
• – setHighlighted:
• – backgroundColor
• – setBackgroundColor:

Getting and Setting the Control Label Font Attributes

• – font
• – setFont:
• – fontColor
• – setFontColor:

Getting and Setting the Control Label Text

• – caption
• – setCaption:

Managing Radio Button Behavior

• – allowsToggleToOff

Managing Control State Values and Form Fields

• – onStateValue
• – setOnStateValue
• – fieldName
• – setFieldName

Instance Methods

allowsToggleToOff

Returns a Boolean value indicating whether a radio button behaves in a toggling manner.

- (BOOL)allowsToggleToOff

Return Value

YES if clicking a radio button control that is already in the on state toggles it to the off state; otherwise NO.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

PDFAnnotationButtonWidget.h

backgroundColor

Returns the background color of the control.

- (NSColor *)backgroundColor

Return Value

The color drawn in the background of the control.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setBackgroundColor:

Declared In

PDFAnnotationButtonWidget.h

caption

Returns the text of the label on a push button control.

- (NSString *)caption

Return Value

The label drawn on a push button control.

Discussion

This method applies only to the label drawn on a control of type kPDFWidgetPushButtonControl.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setCaption:

Declared In

PDFAnnotationButtonWidget.h

controlType

Returns the type of the control.

- (PDFWidgetControlType)controlType

Return Value

The type of control the button represents. See “Constants” for the various control types.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setControlType

Declared In

PDFAnnotationButtonWidget.h

fieldName

Returns the internal name of a field (used for reset-form actions).

- (NSString *)fieldName

Return Value

The internal name of a field.

Discussion

The internal name of a field is an optional value.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setFieldName

Declared In

PDFAnnotationButtonWidget.h

font

Returns the font used in the control’s label.

- (NSFont *)font

Return Value

The font used in the control’s label.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setFont:

Declared In

PDFAnnotationButtonWidget.h

fontColor

Returns the font color used in the control’s label.

- (NSColor *)fontColor

Return Value

The font color used in the control’s label.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setFontColor:

Declared In

PDFAnnotationButtonWidget.h

isHighlighted

Returns a Boolean value that indicates whether the control is highlighted when it is drawn.

- (BOOL)isHighlighted

Return Value

YES if the control is highlighted when it is drawn; otherwise NO.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setHighlighted:

Declared In

PDFAnnotationButtonWidget.h

onStateValue

Returns the string associated with the on state of a radio button or checkbox control.

- (NSString *)onStateValue

Return Value

The string associated with the on state of a radio button or checkbox control.

Discussion

This is a required string for controls of types kPDFWidgetRadioButtonControl and kPDFWidgetCheckBoxControl. The off state is always labeled “Off”.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setOnStateValue

Declared In

PDFAnnotationButtonWidget.h

parentID

Gets the ID of the parent object. (Deprecated. If you need to find other buttons in the same group, such as a group of radio buttons, you do not need information about the parent object. Instead, look for button widget objects that return the same value in fieldName.)

- (unsigned)parentID

Discussion

For more information about the field names of annotations, see the Adobe PDF specification.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

PDFAnnotationButtonWidget.h

setBackgroundColor:

Sets the control’s background color.

- (void)setBackgroundColor:(NSColor *)color

Parameters

color

The color to be drawn in the control’s background.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – backgroundColor

Declared In

PDFAnnotationButtonWidget.h

setCaption:

Sets the text of the label on a push button control.

- (void)setCaption:(NSString *)name

Parameters

name

The text to be used as the label on a push button control.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – caption

Declared In

PDFAnnotationButtonWidget.h

setControlType

Sets the type of the control.

- (void)setControlType:(PDFWidgetControlType)type

Parameters

type

The type of control for the button. “Constants” lists the various control types you can send for this value.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – controlType

setFieldName

Sets the internal name of a field (used for reset-form actions).

- (void)setFieldName:(NSString *)name

Parameters

name

The internal name of a field. This is an optional value.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – fieldName

setFont:

Sets the font of the control’s label.

- (void)setFont:(NSFont *)font

Parameters

font

The desired font for the control’s label.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – font

Declared In

PDFAnnotationButtonWidget.h

setFontColor:

Sets the font color used in the control’s label.

- (void)setFontColor:(NSColor *)color

Parameters

color

The desired font color of the control’s label.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – fontColor

Declared In

PDFAnnotationButtonWidget.h

setHighlighted:

Sets the control’s highlighting when it is drawn.

- (void)setHighlighted:(BOOL)flag

Parameters

flag

Set this value to YES to cause the control to be highlighted when it is drawn or NO otherwise.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – isHighlighted

Declared In

PDFAnnotationButtonWidget.h

setOnStateValue

Sets the string that is associated with the on state of a radio button or checkbox control.

- (void)setOnStateValue:(NSString *)name

Discussion

Required for controls of types kPDFWidgetRadioButtonControl and kPDFWidgetCheckBoxControl, the value of name describes the on state of the control (the off state is always labeled “Off”). Although “On” is an acceptable string for the on state of a single checkbox, a group of two or more radio buttons should have a unique string associated with each control.

For example, a form might display a group of 3 radio buttons that allow users to indicate an account type, such as savings, checking, or investment. The strings associated with the on states of these buttons could be “Savings,“ “Checking,“ and “Investment.“ In this example, these 3 radio buttons also would share a field name string, such as “AccountType.“

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – onStateValue
• – fieldName

setState:

Sets the state of the control.

- (void)setState:(int)value

Parameters

value

The state the control should be in.

Discussion

A control’s state (for example, checked or unchecked) affects how it is drawn. Note that push buttons are always in the on state.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – state

Declared In

PDFAnnotationButtonWidget.h

state

Returns the state of the control.

- (int)state

Return Value

NSOnState if the control is on; NSOffState otherwise.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setState:

Declared In

PDFAnnotationButtonWidget.h

Constants

The types of annotation buttons are:

---