54 * <p>
55 * <img src="doc-files/Checkbox-1.gif" alt="The following context describes the graphic."
56 * style="float:center; margin: 7px 10px;">
57 * <p>
58 * The button labeled <code>one</code> is in the "on" state, and the
59 * other two are in the "off" state. In this example, which uses the
60 * <code>GridLayout</code> class, the states of the three check
61 * boxes are set independently.
62 * <p>
63 * Alternatively, several check boxes can be grouped together under
64 * the control of a single object, using the
65 * <code>CheckboxGroup</code> class.
66 * In a check box group, at most one button can be in the "on"
67 * state at any given time. Clicking on a check box to turn it on
68 * forces any other check box in the same group that is on
69 * into the "off" state.
70 *
71 * @author Sami Shaio
72 * @see java.awt.GridLayout
73 * @see java.awt.CheckboxGroup
74 * @since JDK1.0
75 */
76 public class Checkbox extends Component implements ItemSelectable, Accessible {
77
78 static {
79 /* ensure that the necessary native libraries are loaded */
80 Toolkit.loadLibraries();
81 if (!GraphicsEnvironment.isHeadless()) {
82 initIDs();
83 }
84 }
85
86 /**
87 * The label of the Checkbox.
88 * This field can be null.
89 * @serial
90 * @see #getLabel()
91 * @see #setLabel(String)
92 */
93 String label;
94
173 * returns <code>true</code>
174 * @see java.awt.GraphicsEnvironment#isHeadless
175 */
176 public Checkbox(String label, boolean state) throws HeadlessException {
177 this(label, state, null);
178 }
179
180 /**
181 * Constructs a Checkbox with the specified label, set to the
182 * specified state, and in the specified check box group.
183 *
184 * @param label a string label for this check box,
185 * or <code>null</code> for no label.
186 * @param state the initial state of this check box.
187 * @param group a check box group for this check box,
188 * or <code>null</code> for no group.
189 * @exception HeadlessException if
190 * <code>GraphicsEnvironment.isHeadless</code>
191 * returns <code>true</code>
192 * @see java.awt.GraphicsEnvironment#isHeadless
193 * @since JDK1.1
194 */
195 public Checkbox(String label, boolean state, CheckboxGroup group)
196 throws HeadlessException {
197 GraphicsEnvironment.checkHeadless();
198 this.label = label;
199 this.state = state;
200 this.group = group;
201 if (state && (group != null)) {
202 group.setSelectedCheckbox(this);
203 }
204 }
205
206 /**
207 * Creates a check box with the specified label, in the specified
208 * check box group, and set to the specified state.
209 *
210 * @param label a string label for this check box,
211 * or <code>null</code> for no label.
212 * @param group a check box group for this check box,
213 * or <code>null</code> for no group.
214 * @param state the initial state of this check box.
215 * @exception HeadlessException if
216 * <code>GraphicsEnvironment.isHeadless</code>
217 * returns <code>true</code>
218 * @see java.awt.GraphicsEnvironment#isHeadless
219 * @since JDK1.1
220 */
221 public Checkbox(String label, CheckboxGroup group, boolean state)
222 throws HeadlessException {
223 this(label, state, group);
224 }
225
226 /**
227 * Constructs a name for this component. Called by
228 * <code>getName</code> when the name is <code>null</code>.
229 *
230 * @return a name for this component
231 */
232 String constructComponentName() {
233 synchronized (Checkbox.class) {
234 return base + nameCounter++;
235 }
236 }
237
238 /**
239 * Creates the peer of the Checkbox. The peer allows you to change the
407 */
408 if (oldGroup != null && oldState) {
409 oldGroup.setSelectedCheckbox(null);
410 }
411 }
412
413 /**
414 * Adds the specified item listener to receive item events from
415 * this check box. Item events are sent to listeners in response
416 * to user input, but not in response to calls to setState().
417 * If l is null, no exception is thrown and no action is performed.
418 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
419 * >AWT Threading Issues</a> for details on AWT's threading model.
420 *
421 * @param l the item listener
422 * @see #removeItemListener
423 * @see #getItemListeners
424 * @see #setState
425 * @see java.awt.event.ItemEvent
426 * @see java.awt.event.ItemListener
427 * @since JDK1.1
428 */
429 public synchronized void addItemListener(ItemListener l) {
430 if (l == null) {
431 return;
432 }
433 itemListener = AWTEventMulticaster.add(itemListener, l);
434 newEventsOnly = true;
435 }
436
437 /**
438 * Removes the specified item listener so that the item listener
439 * no longer receives item events from this check box.
440 * If l is null, no exception is thrown and no action is performed.
441 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
442 * >AWT Threading Issues</a> for details on AWT's threading model.
443 *
444 * @param l the item listener
445 * @see #addItemListener
446 * @see #getItemListeners
447 * @see java.awt.event.ItemEvent
448 * @see java.awt.event.ItemListener
449 * @since JDK1.1
450 */
451 public synchronized void removeItemListener(ItemListener l) {
452 if (l == null) {
453 return;
454 }
455 itemListener = AWTEventMulticaster.remove(itemListener, l);
456 }
457
458 /**
459 * Returns an array of all the item listeners
460 * registered on this checkbox.
461 *
462 * @return all of this checkbox's <code>ItemListener</code>s
463 * or an empty array if no item
464 * listeners are currently registered
465 *
466 * @see #addItemListener
467 * @see #removeItemListener
468 * @see java.awt.event.ItemEvent
469 * @see java.awt.event.ItemListener
523 itemListener != null) {
524 return true;
525 }
526 return false;
527 }
528 return super.eventEnabled(e);
529 }
530
531 /**
532 * Processes events on this check box.
533 * If the event is an instance of <code>ItemEvent</code>,
534 * this method invokes the <code>processItemEvent</code> method.
535 * Otherwise, it calls its superclass's <code>processEvent</code> method.
536 * <p>Note that if the event parameter is <code>null</code>
537 * the behavior is unspecified and may result in an
538 * exception.
539 *
540 * @param e the event
541 * @see java.awt.event.ItemEvent
542 * @see #processItemEvent
543 * @since JDK1.1
544 */
545 protected void processEvent(AWTEvent e) {
546 if (e instanceof ItemEvent) {
547 processItemEvent((ItemEvent)e);
548 return;
549 }
550 super.processEvent(e);
551 }
552
553 /**
554 * Processes item events occurring on this check box by
555 * dispatching them to any registered
556 * <code>ItemListener</code> objects.
557 * <p>
558 * This method is not called unless item events are
559 * enabled for this component. Item events are enabled
560 * when one of the following occurs:
561 * <ul>
562 * <li>An <code>ItemListener</code> object is registered
563 * via <code>addItemListener</code>.
564 * <li>Item events are enabled via <code>enableEvents</code>.
565 * </ul>
566 * <p>Note that if the event parameter is <code>null</code>
567 * the behavior is unspecified and may result in an
568 * exception.
569 *
570 * @param e the item event
571 * @see java.awt.event.ItemEvent
572 * @see java.awt.event.ItemListener
573 * @see #addItemListener
574 * @see java.awt.Component#enableEvents
575 * @since JDK1.1
576 */
577 protected void processItemEvent(ItemEvent e) {
578 ItemListener listener = itemListener;
579 if (listener != null) {
580 listener.itemStateChanged(e);
581 }
582 }
583
584 /**
585 * Returns a string representing the state of this <code>Checkbox</code>.
586 * This method is intended to be used only for debugging purposes, and the
587 * content and format of the returned string may vary between
588 * implementations. The returned string may be empty but may not be
589 * <code>null</code>.
590 *
591 * @return the parameter string of this check box
592 */
593 protected String paramString() {
594 String str = super.paramString();
595 String label = this.label;
|
54 * <p>
55 * <img src="doc-files/Checkbox-1.gif" alt="The following context describes the graphic."
56 * style="float:center; margin: 7px 10px;">
57 * <p>
58 * The button labeled <code>one</code> is in the "on" state, and the
59 * other two are in the "off" state. In this example, which uses the
60 * <code>GridLayout</code> class, the states of the three check
61 * boxes are set independently.
62 * <p>
63 * Alternatively, several check boxes can be grouped together under
64 * the control of a single object, using the
65 * <code>CheckboxGroup</code> class.
66 * In a check box group, at most one button can be in the "on"
67 * state at any given time. Clicking on a check box to turn it on
68 * forces any other check box in the same group that is on
69 * into the "off" state.
70 *
71 * @author Sami Shaio
72 * @see java.awt.GridLayout
73 * @see java.awt.CheckboxGroup
74 * @since 1.0
75 */
76 public class Checkbox extends Component implements ItemSelectable, Accessible {
77
78 static {
79 /* ensure that the necessary native libraries are loaded */
80 Toolkit.loadLibraries();
81 if (!GraphicsEnvironment.isHeadless()) {
82 initIDs();
83 }
84 }
85
86 /**
87 * The label of the Checkbox.
88 * This field can be null.
89 * @serial
90 * @see #getLabel()
91 * @see #setLabel(String)
92 */
93 String label;
94
173 * returns <code>true</code>
174 * @see java.awt.GraphicsEnvironment#isHeadless
175 */
176 public Checkbox(String label, boolean state) throws HeadlessException {
177 this(label, state, null);
178 }
179
180 /**
181 * Constructs a Checkbox with the specified label, set to the
182 * specified state, and in the specified check box group.
183 *
184 * @param label a string label for this check box,
185 * or <code>null</code> for no label.
186 * @param state the initial state of this check box.
187 * @param group a check box group for this check box,
188 * or <code>null</code> for no group.
189 * @exception HeadlessException if
190 * <code>GraphicsEnvironment.isHeadless</code>
191 * returns <code>true</code>
192 * @see java.awt.GraphicsEnvironment#isHeadless
193 * @since 1.1
194 */
195 public Checkbox(String label, boolean state, CheckboxGroup group)
196 throws HeadlessException {
197 GraphicsEnvironment.checkHeadless();
198 this.label = label;
199 this.state = state;
200 this.group = group;
201 if (state && (group != null)) {
202 group.setSelectedCheckbox(this);
203 }
204 }
205
206 /**
207 * Creates a check box with the specified label, in the specified
208 * check box group, and set to the specified state.
209 *
210 * @param label a string label for this check box,
211 * or <code>null</code> for no label.
212 * @param group a check box group for this check box,
213 * or <code>null</code> for no group.
214 * @param state the initial state of this check box.
215 * @exception HeadlessException if
216 * <code>GraphicsEnvironment.isHeadless</code>
217 * returns <code>true</code>
218 * @see java.awt.GraphicsEnvironment#isHeadless
219 * @since 1.1
220 */
221 public Checkbox(String label, CheckboxGroup group, boolean state)
222 throws HeadlessException {
223 this(label, state, group);
224 }
225
226 /**
227 * Constructs a name for this component. Called by
228 * <code>getName</code> when the name is <code>null</code>.
229 *
230 * @return a name for this component
231 */
232 String constructComponentName() {
233 synchronized (Checkbox.class) {
234 return base + nameCounter++;
235 }
236 }
237
238 /**
239 * Creates the peer of the Checkbox. The peer allows you to change the
407 */
408 if (oldGroup != null && oldState) {
409 oldGroup.setSelectedCheckbox(null);
410 }
411 }
412
413 /**
414 * Adds the specified item listener to receive item events from
415 * this check box. Item events are sent to listeners in response
416 * to user input, but not in response to calls to setState().
417 * If l is null, no exception is thrown and no action is performed.
418 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
419 * >AWT Threading Issues</a> for details on AWT's threading model.
420 *
421 * @param l the item listener
422 * @see #removeItemListener
423 * @see #getItemListeners
424 * @see #setState
425 * @see java.awt.event.ItemEvent
426 * @see java.awt.event.ItemListener
427 * @since 1.1
428 */
429 public synchronized void addItemListener(ItemListener l) {
430 if (l == null) {
431 return;
432 }
433 itemListener = AWTEventMulticaster.add(itemListener, l);
434 newEventsOnly = true;
435 }
436
437 /**
438 * Removes the specified item listener so that the item listener
439 * no longer receives item events from this check box.
440 * If l is null, no exception is thrown and no action is performed.
441 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
442 * >AWT Threading Issues</a> for details on AWT's threading model.
443 *
444 * @param l the item listener
445 * @see #addItemListener
446 * @see #getItemListeners
447 * @see java.awt.event.ItemEvent
448 * @see java.awt.event.ItemListener
449 * @since 1.1
450 */
451 public synchronized void removeItemListener(ItemListener l) {
452 if (l == null) {
453 return;
454 }
455 itemListener = AWTEventMulticaster.remove(itemListener, l);
456 }
457
458 /**
459 * Returns an array of all the item listeners
460 * registered on this checkbox.
461 *
462 * @return all of this checkbox's <code>ItemListener</code>s
463 * or an empty array if no item
464 * listeners are currently registered
465 *
466 * @see #addItemListener
467 * @see #removeItemListener
468 * @see java.awt.event.ItemEvent
469 * @see java.awt.event.ItemListener
523 itemListener != null) {
524 return true;
525 }
526 return false;
527 }
528 return super.eventEnabled(e);
529 }
530
531 /**
532 * Processes events on this check box.
533 * If the event is an instance of <code>ItemEvent</code>,
534 * this method invokes the <code>processItemEvent</code> method.
535 * Otherwise, it calls its superclass's <code>processEvent</code> method.
536 * <p>Note that if the event parameter is <code>null</code>
537 * the behavior is unspecified and may result in an
538 * exception.
539 *
540 * @param e the event
541 * @see java.awt.event.ItemEvent
542 * @see #processItemEvent
543 * @since 1.1
544 */
545 protected void processEvent(AWTEvent e) {
546 if (e instanceof ItemEvent) {
547 processItemEvent((ItemEvent)e);
548 return;
549 }
550 super.processEvent(e);
551 }
552
553 /**
554 * Processes item events occurring on this check box by
555 * dispatching them to any registered
556 * <code>ItemListener</code> objects.
557 * <p>
558 * This method is not called unless item events are
559 * enabled for this component. Item events are enabled
560 * when one of the following occurs:
561 * <ul>
562 * <li>An <code>ItemListener</code> object is registered
563 * via <code>addItemListener</code>.
564 * <li>Item events are enabled via <code>enableEvents</code>.
565 * </ul>
566 * <p>Note that if the event parameter is <code>null</code>
567 * the behavior is unspecified and may result in an
568 * exception.
569 *
570 * @param e the item event
571 * @see java.awt.event.ItemEvent
572 * @see java.awt.event.ItemListener
573 * @see #addItemListener
574 * @see java.awt.Component#enableEvents
575 * @since 1.1
576 */
577 protected void processItemEvent(ItemEvent e) {
578 ItemListener listener = itemListener;
579 if (listener != null) {
580 listener.itemStateChanged(e);
581 }
582 }
583
584 /**
585 * Returns a string representing the state of this <code>Checkbox</code>.
586 * This method is intended to be used only for debugging purposes, and the
587 * content and format of the returned string may vary between
588 * implementations. The returned string may be empty but may not be
589 * <code>null</code>.
590 *
591 * @return the parameter string of this check box
592 */
593 protected String paramString() {
594 String str = super.paramString();
595 String label = this.label;
|