51 * After this choice menu has been added to a panel,
52 * it appears as follows in its normal state:
53 * <p>
54 * <img src="doc-files/Choice-1.gif" alt="The following text describes the graphic"
55 * style="float:center; margin: 7px 10px;">
56 * <p>
57 * In the picture, <code>"Green"</code> is the current choice.
58 * Pushing the mouse button down on the object causes a menu to
59 * appear with the current choice highlighted.
60 * <p>
61 * Some native platforms do not support arbitrary resizing of
62 * <code>Choice</code> components and the behavior of
63 * <code>setSize()/getSize()</code> is bound by
64 * such limitations.
65 * Native GUI <code>Choice</code> components' size are often bound by such
66 * attributes as font size and length of items contained within
67 * the <code>Choice</code>.
68 *
69 * @author Sami Shaio
70 * @author Arthur van Hoff
71 * @since JDK1.0
72 */
73 public class Choice extends Component implements ItemSelectable, Accessible {
74 /**
75 * The items for the <code>Choice</code>.
76 * This can be a <code>null</code> value.
77 * @serial
78 * @see #add(String)
79 * @see #addItem(String)
80 * @see #getItem(int)
81 * @see #getItemCount()
82 * @see #insert(String, int)
83 * @see #remove(String)
84 */
85 Vector<String> pItems;
86
87 /**
88 * The index of the current choice for this <code>Choice</code>
89 * or -1 if nothing is selected.
90 * @serial
91 * @see #getSelectedItem()
141
142 /**
143 * Creates the <code>Choice</code>'s peer. This peer allows us
144 * to change the look
145 * of the <code>Choice</code> without changing its functionality.
146 * @see java.awt.Toolkit#createChoice(java.awt.Choice)
147 * @see java.awt.Component#getToolkit()
148 */
149 public void addNotify() {
150 synchronized (getTreeLock()) {
151 if (peer == null)
152 peer = getToolkit().createChoice(this);
153 super.addNotify();
154 }
155 }
156
157 /**
158 * Returns the number of items in this <code>Choice</code> menu.
159 * @return the number of items in this <code>Choice</code> menu
160 * @see #getItem
161 * @since JDK1.1
162 */
163 public int getItemCount() {
164 return countItems();
165 }
166
167 /**
168 * @deprecated As of JDK version 1.1,
169 * replaced by <code>getItemCount()</code>.
170 */
171 @Deprecated
172 public int countItems() {
173 return pItems.size();
174 }
175
176 /**
177 * Gets the string at the specified index in this
178 * <code>Choice</code> menu.
179 * @param index the index at which to begin
180 * @see #getItemCount
181 */
182 public String getItem(int index) {
183 return getItemImpl(index);
184 }
185
186 /*
187 * This is called by the native code, so client code can't
188 * be called on the toolkit thread.
189 */
190 final String getItemImpl(int index) {
191 return pItems.elementAt(index);
192 }
193
194 /**
195 * Adds an item to this <code>Choice</code> menu.
196 * @param item the item to be added
197 * @exception NullPointerException if the item's value is
198 * <code>null</code>
199 * @since JDK1.1
200 */
201 public void add(String item) {
202 addItem(item);
203 }
204
205 /**
206 * Obsolete as of Java 2 platform v1.1. Please use the
207 * <code>add</code> method instead.
208 * <p>
209 * Adds an item to this <code>Choice</code> menu.
210 * @param item the item to be added
211 * @exception NullPointerException if the item's value is equal to
212 * <code>null</code>
213 */
214 public void addItem(String item) {
215 synchronized (this) {
216 insertNoInvalidate(item, pItems.size());
217 }
218
219 // This could change the preferred size of the Component.
274 index = Math.min(index, pItems.size());
275
276 insertNoInvalidate(item, index);
277 }
278
279 // This could change the preferred size of the Component.
280 invalidateIfValid();
281 }
282
283 /**
284 * Removes the first occurrence of <code>item</code>
285 * from the <code>Choice</code> menu. If the item
286 * being removed is the currently selected item,
287 * then the first item in the choice becomes the
288 * selected item. Otherwise, the currently selected
289 * item remains selected (and the selected index is
290 * updated accordingly).
291 * @param item the item to remove from this <code>Choice</code> menu
292 * @exception IllegalArgumentException if the item doesn't
293 * exist in the choice menu
294 * @since JDK1.1
295 */
296 public void remove(String item) {
297 synchronized (this) {
298 int index = pItems.indexOf(item);
299 if (index < 0) {
300 throw new IllegalArgumentException("item " + item +
301 " not found in choice");
302 } else {
303 removeNoInvalidate(index);
304 }
305 }
306
307 // This could change the preferred size of the Component.
308 invalidateIfValid();
309 }
310
311 /**
312 * Removes an item from the choice menu
313 * at the specified position. If the item
314 * being removed is the currently selected item,
315 * then the first item in the choice becomes the
316 * selected item. Otherwise, the currently selected
317 * item remains selected (and the selected index is
318 * updated accordingly).
319 * @param position the position of the item
320 * @throws IndexOutOfBoundsException if the specified
321 * position is out of bounds
322 * @since JDK1.1
323 */
324 public void remove(int position) {
325 synchronized (this) {
326 removeNoInvalidate(position);
327 }
328
329 // This could change the preferred size of the Component.
330 invalidateIfValid();
331 }
332
333 /**
334 * Removes an item from the <code>Choice</code> at the
335 * specified position, but does not invalidate the <code>Choice</code>.
336 * Client methods must provide their
337 * own synchronization before invoking this method.
338 * @param position the position of the item
339 */
340 private void removeNoInvalidate(int position) {
341 pItems.removeElementAt(position);
342 ChoicePeer peer = (ChoicePeer)this.peer;
343 if (peer != null) {
344 peer.remove(position);
345 }
346 /* Adjust selectedIndex if selected item was removed. */
347 if (pItems.size() == 0) {
348 selectedIndex = -1;
349 } else if (selectedIndex == position) {
350 select(0);
351 } else if (selectedIndex > position) {
352 select(selectedIndex-1);
353 }
354 }
355
356
357 /**
358 * Removes all items from the choice menu.
359 * @see #remove
360 * @since JDK1.1
361 */
362 public void removeAll() {
363 synchronized (this) {
364 if (peer != null) {
365 ((ChoicePeer)peer).removeAll();
366 }
367 pItems.removeAllElements();
368 selectedIndex = -1;
369 }
370
371 // This could change the preferred size of the Component.
372 invalidateIfValid();
373 }
374
375 /**
376 * Gets a representation of the current choice as a string.
377 * @return a string representation of the currently
378 * selected item in this choice menu
379 * @see #getSelectedIndex
380 */
458 int index = pItems.indexOf(str);
459 if (index >= 0) {
460 select(index);
461 }
462 }
463
464 /**
465 * Adds the specified item listener to receive item events from
466 * this <code>Choice</code> menu. Item events are sent in response
467 * to user input, but not in response to calls to <code>select</code>.
468 * If l is <code>null</code>, no exception is thrown and no action
469 * is performed.
470 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
471 * >AWT Threading Issues</a> for details on AWT's threading model.
472 * @param l the item listener
473 * @see #removeItemListener
474 * @see #getItemListeners
475 * @see #select
476 * @see java.awt.event.ItemEvent
477 * @see java.awt.event.ItemListener
478 * @since JDK1.1
479 */
480 public synchronized void addItemListener(ItemListener l) {
481 if (l == null) {
482 return;
483 }
484 itemListener = AWTEventMulticaster.add(itemListener, l);
485 newEventsOnly = true;
486 }
487
488 /**
489 * Removes the specified item listener so that it no longer receives
490 * item events from this <code>Choice</code> menu.
491 * If l is <code>null</code>, no exception is thrown and no
492 * action is performed.
493 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
494 * >AWT Threading Issues</a> for details on AWT's threading model.
495 * @param l the item listener
496 * @see #addItemListener
497 * @see #getItemListeners
498 * @see java.awt.event.ItemEvent
499 * @see java.awt.event.ItemListener
500 * @since JDK1.1
501 */
502 public synchronized void removeItemListener(ItemListener l) {
503 if (l == null) {
504 return;
505 }
506 itemListener = AWTEventMulticaster.remove(itemListener, l);
507 }
508
509 /**
510 * Returns an array of all the item listeners
511 * registered on this choice.
512 *
513 * @return all of this choice's <code>ItemListener</code>s
514 * or an empty array if no item
515 * listeners are currently registered
516 *
517 * @see #addItemListener
518 * @see #removeItemListener
519 * @see java.awt.event.ItemEvent
520 * @see java.awt.event.ItemListener
574 itemListener != null) {
575 return true;
576 }
577 return false;
578 }
579 return super.eventEnabled(e);
580 }
581
582 /**
583 * Processes events on this choice. If the event is an
584 * instance of <code>ItemEvent</code>, it invokes the
585 * <code>processItemEvent</code> method. Otherwise, it calls its
586 * superclass's <code>processEvent</code> method.
587 * <p>Note that if the event parameter is <code>null</code>
588 * the behavior is unspecified and may result in an
589 * exception.
590 *
591 * @param e the event
592 * @see java.awt.event.ItemEvent
593 * @see #processItemEvent
594 * @since JDK1.1
595 */
596 protected void processEvent(AWTEvent e) {
597 if (e instanceof ItemEvent) {
598 processItemEvent((ItemEvent)e);
599 return;
600 }
601 super.processEvent(e);
602 }
603
604 /**
605 * Processes item events occurring on this <code>Choice</code>
606 * menu by dispatching them to any registered
607 * <code>ItemListener</code> objects.
608 * <p>
609 * This method is not called unless item events are
610 * enabled for this component. Item events are enabled
611 * when one of the following occurs:
612 * <ul>
613 * <li>An <code>ItemListener</code> object is registered
614 * via <code>addItemListener</code>.
615 * <li>Item events are enabled via <code>enableEvents</code>.
616 * </ul>
617 * <p>Note that if the event parameter is <code>null</code>
618 * the behavior is unspecified and may result in an
619 * exception.
620 *
621 * @param e the item event
622 * @see java.awt.event.ItemEvent
623 * @see java.awt.event.ItemListener
624 * @see #addItemListener(ItemListener)
625 * @see java.awt.Component#enableEvents
626 * @since JDK1.1
627 */
628 protected void processItemEvent(ItemEvent e) {
629 ItemListener listener = itemListener;
630 if (listener != null) {
631 listener.itemStateChanged(e);
632 }
633 }
634
635 /**
636 * Returns a string representing the state of this <code>Choice</code>
637 * menu. This method is intended to be used only for debugging purposes,
638 * and the content and format of the returned string may vary between
639 * implementations. The returned string may be empty but may not be
640 * <code>null</code>.
641 *
642 * @return the parameter string of this <code>Choice</code> menu
643 */
644 protected String paramString() {
645 return super.paramString() + ",current=" + getSelectedItem();
646 }
|
51 * After this choice menu has been added to a panel,
52 * it appears as follows in its normal state:
53 * <p>
54 * <img src="doc-files/Choice-1.gif" alt="The following text describes the graphic"
55 * style="float:center; margin: 7px 10px;">
56 * <p>
57 * In the picture, <code>"Green"</code> is the current choice.
58 * Pushing the mouse button down on the object causes a menu to
59 * appear with the current choice highlighted.
60 * <p>
61 * Some native platforms do not support arbitrary resizing of
62 * <code>Choice</code> components and the behavior of
63 * <code>setSize()/getSize()</code> is bound by
64 * such limitations.
65 * Native GUI <code>Choice</code> components' size are often bound by such
66 * attributes as font size and length of items contained within
67 * the <code>Choice</code>.
68 *
69 * @author Sami Shaio
70 * @author Arthur van Hoff
71 * @since 1.0
72 */
73 public class Choice extends Component implements ItemSelectable, Accessible {
74 /**
75 * The items for the <code>Choice</code>.
76 * This can be a <code>null</code> value.
77 * @serial
78 * @see #add(String)
79 * @see #addItem(String)
80 * @see #getItem(int)
81 * @see #getItemCount()
82 * @see #insert(String, int)
83 * @see #remove(String)
84 */
85 Vector<String> pItems;
86
87 /**
88 * The index of the current choice for this <code>Choice</code>
89 * or -1 if nothing is selected.
90 * @serial
91 * @see #getSelectedItem()
141
142 /**
143 * Creates the <code>Choice</code>'s peer. This peer allows us
144 * to change the look
145 * of the <code>Choice</code> without changing its functionality.
146 * @see java.awt.Toolkit#createChoice(java.awt.Choice)
147 * @see java.awt.Component#getToolkit()
148 */
149 public void addNotify() {
150 synchronized (getTreeLock()) {
151 if (peer == null)
152 peer = getToolkit().createChoice(this);
153 super.addNotify();
154 }
155 }
156
157 /**
158 * Returns the number of items in this <code>Choice</code> menu.
159 * @return the number of items in this <code>Choice</code> menu
160 * @see #getItem
161 * @since 1.1
162 */
163 public int getItemCount() {
164 return countItems();
165 }
166
167 /**
168 * @deprecated As of JDK version 1.1,
169 * replaced by <code>getItemCount()</code>.
170 */
171 @Deprecated
172 public int countItems() {
173 return pItems.size();
174 }
175
176 /**
177 * Gets the string at the specified index in this
178 * <code>Choice</code> menu.
179 * @param index the index at which to begin
180 * @see #getItemCount
181 */
182 public String getItem(int index) {
183 return getItemImpl(index);
184 }
185
186 /*
187 * This is called by the native code, so client code can't
188 * be called on the toolkit thread.
189 */
190 final String getItemImpl(int index) {
191 return pItems.elementAt(index);
192 }
193
194 /**
195 * Adds an item to this <code>Choice</code> menu.
196 * @param item the item to be added
197 * @exception NullPointerException if the item's value is
198 * <code>null</code>
199 * @since 1.1
200 */
201 public void add(String item) {
202 addItem(item);
203 }
204
205 /**
206 * Obsolete as of Java 2 platform v1.1. Please use the
207 * <code>add</code> method instead.
208 * <p>
209 * Adds an item to this <code>Choice</code> menu.
210 * @param item the item to be added
211 * @exception NullPointerException if the item's value is equal to
212 * <code>null</code>
213 */
214 public void addItem(String item) {
215 synchronized (this) {
216 insertNoInvalidate(item, pItems.size());
217 }
218
219 // This could change the preferred size of the Component.
274 index = Math.min(index, pItems.size());
275
276 insertNoInvalidate(item, index);
277 }
278
279 // This could change the preferred size of the Component.
280 invalidateIfValid();
281 }
282
283 /**
284 * Removes the first occurrence of <code>item</code>
285 * from the <code>Choice</code> menu. If the item
286 * being removed is the currently selected item,
287 * then the first item in the choice becomes the
288 * selected item. Otherwise, the currently selected
289 * item remains selected (and the selected index is
290 * updated accordingly).
291 * @param item the item to remove from this <code>Choice</code> menu
292 * @exception IllegalArgumentException if the item doesn't
293 * exist in the choice menu
294 * @since 1.1
295 */
296 public void remove(String item) {
297 synchronized (this) {
298 int index = pItems.indexOf(item);
299 if (index < 0) {
300 throw new IllegalArgumentException("item " + item +
301 " not found in choice");
302 } else {
303 removeNoInvalidate(index);
304 }
305 }
306
307 // This could change the preferred size of the Component.
308 invalidateIfValid();
309 }
310
311 /**
312 * Removes an item from the choice menu
313 * at the specified position. If the item
314 * being removed is the currently selected item,
315 * then the first item in the choice becomes the
316 * selected item. Otherwise, the currently selected
317 * item remains selected (and the selected index is
318 * updated accordingly).
319 * @param position the position of the item
320 * @throws IndexOutOfBoundsException if the specified
321 * position is out of bounds
322 * @since 1.1
323 */
324 public void remove(int position) {
325 synchronized (this) {
326 removeNoInvalidate(position);
327 }
328
329 // This could change the preferred size of the Component.
330 invalidateIfValid();
331 }
332
333 /**
334 * Removes an item from the <code>Choice</code> at the
335 * specified position, but does not invalidate the <code>Choice</code>.
336 * Client methods must provide their
337 * own synchronization before invoking this method.
338 * @param position the position of the item
339 */
340 private void removeNoInvalidate(int position) {
341 pItems.removeElementAt(position);
342 ChoicePeer peer = (ChoicePeer)this.peer;
343 if (peer != null) {
344 peer.remove(position);
345 }
346 /* Adjust selectedIndex if selected item was removed. */
347 if (pItems.size() == 0) {
348 selectedIndex = -1;
349 } else if (selectedIndex == position) {
350 select(0);
351 } else if (selectedIndex > position) {
352 select(selectedIndex-1);
353 }
354 }
355
356
357 /**
358 * Removes all items from the choice menu.
359 * @see #remove
360 * @since 1.1
361 */
362 public void removeAll() {
363 synchronized (this) {
364 if (peer != null) {
365 ((ChoicePeer)peer).removeAll();
366 }
367 pItems.removeAllElements();
368 selectedIndex = -1;
369 }
370
371 // This could change the preferred size of the Component.
372 invalidateIfValid();
373 }
374
375 /**
376 * Gets a representation of the current choice as a string.
377 * @return a string representation of the currently
378 * selected item in this choice menu
379 * @see #getSelectedIndex
380 */
458 int index = pItems.indexOf(str);
459 if (index >= 0) {
460 select(index);
461 }
462 }
463
464 /**
465 * Adds the specified item listener to receive item events from
466 * this <code>Choice</code> menu. Item events are sent in response
467 * to user input, but not in response to calls to <code>select</code>.
468 * If l is <code>null</code>, no exception is thrown and no action
469 * is performed.
470 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
471 * >AWT Threading Issues</a> for details on AWT's threading model.
472 * @param l the item listener
473 * @see #removeItemListener
474 * @see #getItemListeners
475 * @see #select
476 * @see java.awt.event.ItemEvent
477 * @see java.awt.event.ItemListener
478 * @since 1.1
479 */
480 public synchronized void addItemListener(ItemListener l) {
481 if (l == null) {
482 return;
483 }
484 itemListener = AWTEventMulticaster.add(itemListener, l);
485 newEventsOnly = true;
486 }
487
488 /**
489 * Removes the specified item listener so that it no longer receives
490 * item events from this <code>Choice</code> menu.
491 * If l is <code>null</code>, no exception is thrown and no
492 * action is performed.
493 * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
494 * >AWT Threading Issues</a> for details on AWT's threading model.
495 * @param l the item listener
496 * @see #addItemListener
497 * @see #getItemListeners
498 * @see java.awt.event.ItemEvent
499 * @see java.awt.event.ItemListener
500 * @since 1.1
501 */
502 public synchronized void removeItemListener(ItemListener l) {
503 if (l == null) {
504 return;
505 }
506 itemListener = AWTEventMulticaster.remove(itemListener, l);
507 }
508
509 /**
510 * Returns an array of all the item listeners
511 * registered on this choice.
512 *
513 * @return all of this choice's <code>ItemListener</code>s
514 * or an empty array if no item
515 * listeners are currently registered
516 *
517 * @see #addItemListener
518 * @see #removeItemListener
519 * @see java.awt.event.ItemEvent
520 * @see java.awt.event.ItemListener
574 itemListener != null) {
575 return true;
576 }
577 return false;
578 }
579 return super.eventEnabled(e);
580 }
581
582 /**
583 * Processes events on this choice. If the event is an
584 * instance of <code>ItemEvent</code>, it invokes the
585 * <code>processItemEvent</code> method. Otherwise, it calls its
586 * superclass's <code>processEvent</code> method.
587 * <p>Note that if the event parameter is <code>null</code>
588 * the behavior is unspecified and may result in an
589 * exception.
590 *
591 * @param e the event
592 * @see java.awt.event.ItemEvent
593 * @see #processItemEvent
594 * @since 1.1
595 */
596 protected void processEvent(AWTEvent e) {
597 if (e instanceof ItemEvent) {
598 processItemEvent((ItemEvent)e);
599 return;
600 }
601 super.processEvent(e);
602 }
603
604 /**
605 * Processes item events occurring on this <code>Choice</code>
606 * menu by dispatching them to any registered
607 * <code>ItemListener</code> objects.
608 * <p>
609 * This method is not called unless item events are
610 * enabled for this component. Item events are enabled
611 * when one of the following occurs:
612 * <ul>
613 * <li>An <code>ItemListener</code> object is registered
614 * via <code>addItemListener</code>.
615 * <li>Item events are enabled via <code>enableEvents</code>.
616 * </ul>
617 * <p>Note that if the event parameter is <code>null</code>
618 * the behavior is unspecified and may result in an
619 * exception.
620 *
621 * @param e the item event
622 * @see java.awt.event.ItemEvent
623 * @see java.awt.event.ItemListener
624 * @see #addItemListener(ItemListener)
625 * @see java.awt.Component#enableEvents
626 * @since 1.1
627 */
628 protected void processItemEvent(ItemEvent e) {
629 ItemListener listener = itemListener;
630 if (listener != null) {
631 listener.itemStateChanged(e);
632 }
633 }
634
635 /**
636 * Returns a string representing the state of this <code>Choice</code>
637 * menu. This method is intended to be used only for debugging purposes,
638 * and the content and format of the returned string may vary between
639 * implementations. The returned string may be empty but may not be
640 * <code>null</code>.
641 *
642 * @return the parameter string of this <code>Choice</code> menu
643 */
644 protected String paramString() {
645 return super.paramString() + ",current=" + getSelectedItem();
646 }
|