001: /*******************************************************************************
002: * Copyright (c) 2000, 2007 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.ui.forms.widgets;
011:
012: import org.eclipse.jface.action.IMenuManager;
013: import org.eclipse.jface.action.IToolBarManager;
014: import org.eclipse.swt.SWT;
015: import org.eclipse.swt.dnd.DragSourceListener;
016: import org.eclipse.swt.dnd.DropTargetListener;
017: import org.eclipse.swt.dnd.Transfer;
018: import org.eclipse.swt.graphics.Color;
019: import org.eclipse.swt.graphics.Font;
020: import org.eclipse.swt.graphics.Image;
021: import org.eclipse.swt.graphics.Point;
022: import org.eclipse.swt.graphics.Rectangle;
023: import org.eclipse.swt.widgets.Composite;
024: import org.eclipse.swt.widgets.Control;
025: import org.eclipse.swt.widgets.Layout;
026: import org.eclipse.swt.widgets.Menu;
027: import org.eclipse.ui.forms.IFormColors;
028: import org.eclipse.ui.forms.IMessage;
029: import org.eclipse.ui.forms.events.IHyperlinkListener;
030: import org.eclipse.ui.internal.forms.widgets.FormHeading;
031: import org.eclipse.ui.internal.forms.widgets.FormUtil;
032:
033: /**
034: * Form is a custom control that renders a title and an optional background
035: * image above the body composite. It can be used alone when part of parents
036: * that are scrolled. If scrolling is required, use <code>ScrolledForm</code>
037: * instead because it has an instance of <code>Form</code> and adds scrolling
038: * capability.
039: * <p>
040: * Form can have a title if set. If not set, title area will not be left empty -
041: * form body will be resized to fill the entire form. In addition, an optional
042: * title image can be set and is rendered to the left of the title (since 3.2).
043: * <p>
044: * Form can have a title drop down menu if the menu bar manager is not empty
045: * (since 3.3).
046: * <p>
047: * Form title can support drag and drop if drag and drop support methods are
048: * invoked. When used, additional decoration is rendered behind the title to
049: * reinforce the drag and drop ability (since 3.3).
050: * <p>
051: * The form supports status messages. These messages can have various severity
052: * (error, warning, info or none). If status hyperlink handler is specified, the
053: * messages with the specified severity other than none will be rendered as
054: * hyperlinks.
055: * <p>
056: * Form can have a background image behind the title text. The image is tiled as
057: * many times as needed to fill the title area. Alternatively, gradient
058: * background can be painted vertically or horizontally.
059: * <p>
060: * Form can be put in a 'busy' state. While in this state, title image is
061: * replaced with an animation that lasts as long as the 'busy' state is active.
062: * <p>
063: * It is possible to create an optional head client control. When created, this
064: * control is placed in the form heading as a second row.
065: * <p>
066: * Form has a custom layout manager that is wrap-enabled. If a form is placed in
067: * a composite whose layout manager implements ILayoutExtension, the body of the
068: * form will participate in wrapping as long as its layout manager implements
069: * ILayoutExtension as well.
070: * <p>
071: * Children of the form should typically be created using FormToolkit to match
072: * the appearance and behaviour. When creating children, use the form body as a
073: * parent by calling 'getBody()' on the form instance. Example:
074: *
075: * <pre>
076: * FormToolkit toolkit = new FormToolkit(parent.getDisplay());
077: * Form form = toolkit.createForm(parent);
078: * form.setText("Sample form");
079: * form.getBody().setLayout(new GridLayout());
080: * toolkit.createButton(form.getBody(), "Checkbox", SWT.CHECK);
081: * </pre>
082: *
083: * <p>
084: * No layout manager has been set on the body. Clients are required to set the
085: * desired layout manager explicitly.
086: * <p>
087: * Although the class is not final, it should not be subclassed.
088: *
089: * @since 3.0
090: */
091: public class Form extends Composite {
092: private FormHeading head;
093:
094: private Composite body;
095:
096: private SizeCache bodyCache = new SizeCache();
097:
098: private SizeCache headCache = new SizeCache();
099:
100: private FormText selectionText;
101:
102: private class FormLayout extends Layout implements ILayoutExtension {
103: public int computeMinimumWidth(Composite composite,
104: boolean flushCache) {
105: return computeSize(composite, 5, SWT.DEFAULT, flushCache).x;
106: }
107:
108: public int computeMaximumWidth(Composite composite,
109: boolean flushCache) {
110: return computeSize(composite, SWT.DEFAULT, SWT.DEFAULT,
111: flushCache).x;
112: }
113:
114: public Point computeSize(Composite composite, int wHint,
115: int hHint, boolean flushCache) {
116: if (flushCache) {
117: bodyCache.flush();
118: headCache.flush();
119: }
120: bodyCache.setControl(body);
121: headCache.setControl(head);
122:
123: int width = 0;
124: int height = 0;
125:
126: Point hsize = headCache.computeSize(FormUtil.getWidthHint(
127: wHint, head), SWT.DEFAULT);
128: width = Math.max(hsize.x, width);
129: height = hsize.y;
130:
131: boolean ignoreBody = getData(FormUtil.IGNORE_BODY) != null;
132:
133: Point bsize;
134: if (ignoreBody)
135: bsize = new Point(0, 0);
136: else
137: bsize = bodyCache.computeSize(FormUtil.getWidthHint(
138: wHint, body), SWT.DEFAULT);
139: width = Math.max(bsize.x, width);
140: height += bsize.y;
141: return new Point(width, height);
142: }
143:
144: protected void layout(Composite composite, boolean flushCache) {
145: if (flushCache) {
146: bodyCache.flush();
147: headCache.flush();
148: }
149: bodyCache.setControl(body);
150: headCache.setControl(head);
151: Rectangle carea = composite.getClientArea();
152:
153: Point hsize = headCache.computeSize(carea.width,
154: SWT.DEFAULT);
155: headCache.setBounds(0, 0, carea.width, hsize.y);
156: bodyCache.setBounds(0, hsize.y, carea.width, carea.height
157: - hsize.y);
158: }
159: }
160:
161: /**
162: * Creates the form content control as a child of the provided parent.
163: *
164: * @param parent
165: * the parent widget
166: */
167: public Form(Composite parent, int style) {
168: super (parent, SWT.NO_BACKGROUND | style);
169: super .setLayout(new FormLayout());
170: head = new FormHeading(this , SWT.NULL);
171: head.setMenu(parent.getMenu());
172: body = new LayoutComposite(this , SWT.NULL);
173: body.setMenu(parent.getMenu());
174: }
175:
176: /**
177: * Passes the menu to the form body.
178: *
179: * @param menu
180: * the parent menu
181: */
182: public void setMenu(Menu menu) {
183: super .setMenu(menu);
184: head.setMenu(menu);
185: body.setMenu(menu);
186: }
187:
188: /**
189: * Fully delegates the size computation to the internal layout manager.
190: */
191: public final Point computeSize(int wHint, int hHint, boolean changed) {
192: return ((FormLayout) getLayout()).computeSize(this , wHint,
193: hHint, changed);
194: }
195:
196: /**
197: * Prevents from changing the custom control layout.
198: */
199: public final void setLayout(Layout layout) {
200: }
201:
202: /**
203: * Returns the title text that will be rendered at the top of the form.
204: *
205: * @return the title text
206: */
207: public String getText() {
208: return head.getText();
209: }
210:
211: /**
212: * Returns the title image that will be rendered to the left of the title.
213: *
214: * @return the title image or <code>null</code> if not set.
215: * @since 3.2
216: */
217: public Image getImage() {
218: return head.getImage();
219: }
220:
221: /**
222: * Sets the foreground color of the form. This color will also be used for
223: * the body.
224: *
225: * @param fg
226: * the foreground color
227: */
228: public void setForeground(Color fg) {
229: super .setForeground(fg);
230: head.setForeground(fg);
231: body.setForeground(fg);
232: }
233:
234: /**
235: * Sets the background color of the form. This color will also be used for
236: * the body.
237: *
238: * @param bg
239: * the background color
240: */
241: public void setBackground(Color bg) {
242: super .setBackground(bg);
243: head.setBackground(bg);
244: body.setBackground(bg);
245: }
246:
247: /**
248: * Sets the font of the header text.
249: *
250: * @param font
251: * the new font
252: */
253: public void setFont(Font font) {
254: super .setFont(font);
255: head.setFont(font);
256: }
257:
258: /**
259: * Sets the text to be rendered at the top of the form above the body as a
260: * title.
261: * <p>
262: * <strong>Note:</strong> Mnemonics are indicated by an '&' that causes
263: * the next character to be the mnemonic. Mnemonics are not applicable in
264: * the case of the form title but need to be taken into acount due to the
265: * usage of the underlying widget that renders mnemonics in the title area.
266: * The mnemonic indicator character '&' can be escaped by doubling it in
267: * the string, causing a single '&' to be displayed.
268: * </p>
269: *
270: * @param text
271: * the title text
272: */
273: public void setText(String text) {
274: head.setText(text);
275: layout();
276: redraw();
277: }
278:
279: /**
280: * Sets the image to be rendered to the left of the title. This image will
281: * be temporarily hidden in two cases:
282: *
283: * <ol>
284: * <li>When the form is busy - replaced with a busy animation</li>
285: * <li>When the form has message set - replaced with the image indicating
286: * message severity</li>
287: * </ol>
288: *
289: * @param image
290: * the title image or <code>null</code> to show no image.
291: * @since 3.2
292: */
293: public void setImage(Image image) {
294: head.setImage(image);
295: layout();
296: redraw();
297: }
298:
299: /**
300: * Sets the background colors to be painted behind the title text in a
301: * gradient. Note that this method will reset color previously set by
302: * {@link #setBackground(Color)}. This is necessary for the simulated
303: * transparency of the heading in all of its children control.
304: *
305: * @param gradientColors
306: * the array of colors that form the gradient
307: * @param percents
308: * the partition of the overall space between the gradient colors
309: * @param vertical
310: * of <code>true</code>, the gradient will be rendered
311: * vertically, if <code>false</code> the orientation will be
312: * horizontal.
313: */
314:
315: public void setTextBackground(Color[] gradientColors,
316: int[] percents, boolean vertical) {
317: head.setTextBackground(gradientColors, percents, vertical);
318: }
319:
320: /**
321: * Returns the optional background image of the form head.
322: *
323: * @return the background image or <code>null</code> if not specified.
324: */
325: public Image getBackgroundImage() {
326: return head.getHeadingBackgroundImage();
327: }
328:
329: /**
330: * Sets the optional background image to be rendered behind the title
331: * starting at the position 0,0. If the image is smaller than the container
332: * in any dimension, it will be tiled.
333: *
334: * @since 3.2
335: *
336: * @param backgroundImage
337: * the head background image.
338: *
339: */
340: public void setBackgroundImage(Image backgroundImage) {
341: head.setHeadingBackgroundImage(backgroundImage);
342: }
343:
344: /**
345: * Returns the tool bar manager that is used to manage tool items in the
346: * form's title area.
347: *
348: * @return form tool bar manager
349: */
350: public IToolBarManager getToolBarManager() {
351: return head.getToolBarManager();
352: }
353:
354: /**
355: * Sets the tool bar vertical alignment relative to the header. Can be
356: * useful when there is more free space at the second row (with the head
357: * client).
358: *
359: * @param alignment
360: * SWT.TOP or SWT.BOTTOM
361: * @since 3.3
362: */
363:
364: public void setToolBarVerticalAlignment(int alignment) {
365: head.setToolBarAlignment(alignment);
366: }
367:
368: /**
369: * Returns the current tool bar alignment (if used).
370: *
371: * @return SWT.TOP or SWT.BOTTOM
372: * @since 3.3
373: */
374:
375: public int getToolBarVerticalAlignment() {
376: return head.getToolBarAlignment();
377: }
378:
379: /**
380: * Returns the menu manager that is used to manage title area drop-down menu
381: * items.
382: *
383: * @return title area drop-down menu manager
384: * @since 3.3
385: */
386: public IMenuManager getMenuManager() {
387: return head.getMenuManager();
388: }
389:
390: /**
391: * Updates the local tool bar manager if used. Does nothing if local tool
392: * bar manager has not been created yet.
393: */
394: public void updateToolBar() {
395: head.updateToolBar();
396: }
397:
398: /**
399: * Returns the container that occupies the head of the form (the form area
400: * above the body). Use this container as a parent for the head client.
401: *
402: * @return the head of the form.
403: * @since 3.2
404: */
405: public Composite getHead() {
406: return head;
407: }
408:
409: /**
410: * Returns the optional head client if set.
411: *
412: * @return the head client or <code>null</code> if not set.
413: * @see #setHeadClient(Control)
414: * @since 3.2
415: */
416: public Control getHeadClient() {
417: return head.getHeadClient();
418: }
419:
420: /**
421: * Sets the optional head client. Head client is placed after the form
422: * title. This option causes the tool bar to be placed in the second raw of
423: * the header (below the head client).
424: * <p>
425: * The head client must be a child of the composite returned by
426: * <code>getHead()</code> method.
427: *
428: * @param headClient
429: * the optional child of the head
430: * @since 3.2
431: */
432: public void setHeadClient(Control headClient) {
433: head.setHeadClient(headClient);
434: layout();
435: }
436:
437: /**
438: * Returns the container that occupies the body of the form (the form area
439: * below the title). Use this container as a parent for the controls that
440: * should be in the form. No layout manager has been set on the form body.
441: *
442: * @return Returns the body of the form.
443: */
444: public Composite getBody() {
445: return body;
446: }
447:
448: /**
449: * Tests if the background image is tiled to cover the entire area of the
450: * form heading.
451: *
452: * @return <code>true</code> if heading background image is tiled,
453: * <code>false</code> otherwise.
454: */
455: public boolean isBackgroundImageTiled() {
456: return head.isBackgroundImageTiled();
457: }
458:
459: /**
460: * Sets whether the header background image is repeated to cover the entire
461: * heading area or not.
462: *
463: * @param backgroundImageTiled
464: * set <code>true</code> to tile the image, or
465: * <code>false</code> to paint the background image only once
466: * at 0,0
467: */
468: public void setBackgroundImageTiled(boolean backgroundImageTiled) {
469: head.setBackgroundImageTiled(backgroundImageTiled);
470: }
471:
472: /**
473: * Returns the background image alignment.
474: *
475: * @deprecated due to the underlying widget limitations, background image is
476: * either painted at 0,0 and/or tiled.
477: * @return SWT.LEFT
478: */
479: public int getBackgroundImageAlignment() {
480: return SWT.LEFT;
481: }
482:
483: /**
484: * Sets the background image alignment.
485: *
486: * @deprecated due to the underlying widget limitations, background image is
487: * always tiled and alignment cannot be controlled.
488: * @param backgroundImageAlignment
489: * The backgroundImageAlignment to set.
490: * @since 3.1
491: */
492: public void setBackgroundImageAlignment(int backgroundImageAlignment) {
493: }
494:
495: /**
496: * Tests if background image is clipped.
497: *
498: * @deprecated due to the underlying widget limitations, background image is
499: * always clipped.
500: * @return true
501: * @since 3.1
502: */
503: public boolean isBackgroundImageClipped() {
504: return true;
505: }
506:
507: /**
508: * Sets whether the background image is clipped.
509: *
510: * @deprecated due to the underlying widget limitations, background image is
511: * always clipped.
512: * @param backgroundImageClipped
513: * the value to set
514: * @since 3.1
515: */
516: public void setBackgroundImageClipped(boolean backgroundImageClipped) {
517: }
518:
519: /**
520: * Tests if the form head separator is visible.
521: *
522: * @return <code>true</code> if the head/body separator is visible,
523: * <code>false</code> otherwise
524: * @since 3.2
525: */
526: public boolean isSeparatorVisible() {
527: return head.isSeparatorVisible();
528: }
529:
530: /**
531: * If set, adds a separator between the head and body. Since 3.3, the colors
532: * that are used to render it are {@link IFormColors#H_BOTTOM_KEYLINE1} and
533: * {@link IFormColors#H_BOTTOM_KEYLINE2}.
534: *
535: * @param addSeparator
536: * <code>true</code> to make the separator visible,
537: * <code>false</code> otherwise.
538: * @since 3.2
539: */
540: public void setSeparatorVisible(boolean addSeparator) {
541: head.setSeparatorVisible(addSeparator);
542: }
543:
544: /**
545: * Returns the color used to render the optional head separator. If gradient
546: * text background is used additional colors from the gradient will be used
547: * to render the separator.
548: *
549: * @return separator color or <code>null</code> if not set.
550: * @since 3.2
551: * @deprecated use <code>getHeadColor(IFormColors.H_BOTTOM_KEYLINE2)</code>
552: */
553:
554: public Color getSeparatorColor() {
555: return head.getColor(IFormColors.H_BOTTOM_KEYLINE2);
556: }
557:
558: /**
559: * Sets the color to be used to render the optional head separator.
560: *
561: * @param separatorColor
562: * the color to render the head separator or <code>null</code>
563: * to use the default color.
564: * @since 3.2
565: * @deprecated use
566: * <code>setHeadColor(IFormColors.H_BOTTOM_KEYLINE2, separatorColor)</code>
567: */
568: public void setSeparatorColor(Color separatorColor) {
569: head.putColor(IFormColors.H_BOTTOM_KEYLINE2, separatorColor);
570: }
571:
572: /**
573: * Sets the color used to paint an aspect of the form heading.
574: *
575: * @param key
576: * a valid form heading color key as defined in
577: * {@link IFormColors}. Relevant keys all start with an H_
578: * prefix.
579: * @param color
580: * the color to use for the provided key
581: * @since 3.3
582: */
583:
584: public void setHeadColor(String key, Color color) {
585: head.putColor(key, color);
586: }
587:
588: /**
589: * Returns the color that is currently use to paint an aspect of the form
590: * heading, or <code>null</code> if not defined.
591: *
592: * @param key
593: * the color key
594: * @return the color object or <code>null</code> if not set.
595: * @since 3.3
596: */
597:
598: public Color getHeadColor(String key) {
599: return head.getColor(key);
600: }
601:
602: /**
603: * Sets the message for this form. Message text is rendered in the form head
604: * when shown.
605: *
606: * @param message
607: * the message, or <code>null</code> to clear the message
608: * @see #setMessage(String, int)
609: * @since 3.2
610: */
611: public void setMessage(String message) {
612: this .setMessage(message, 0, null);
613: }
614:
615: /**
616: * Sets the message for this form with an indication of what type of message
617: * it is.
618: * <p>
619: * The valid message types are one of <code>NONE</code>,
620: * <code>INFORMATION</code>,<code>WARNING</code>, or
621: * <code>ERROR</code> defined in IMessageProvider interface.
622: * </p>
623: *
624: * @param newMessage
625: * the message, or <code>null</code> to clear the message
626: * @param newType
627: * the message type
628: * @see org.eclipse.jface.dialogs.IMessageProvider
629: * @since 3.2
630: */
631:
632: public void setMessage(String newMessage, int newType) {
633: this .setMessage(newMessage, newType, null);
634: }
635:
636: /**
637: * Sets the message for this form with an indication of what type of message
638: * it is.
639: * <p>
640: * The valid message types are one of <code>NONE</code>,
641: * <code>INFORMATION</code>,<code>WARNING</code>, or
642: * <code>ERROR</code> defined in IMessageProvider interface.
643: * </p>
644: * <p>
645: * In addition to the summary message, this method also sets an array of
646: * individual messages.
647: *
648: *
649: * @param newMessage
650: * the message, or <code>null</code> to clear the message
651: * @param newType
652: * the message type
653: * @param children
654: * the individual messages that contributed to the overall
655: * message
656: * @see org.eclipse.jface.dialogs.IMessageProvider
657: * @since 3.3
658: */
659:
660: public void setMessage(String newMessage, int newType,
661: IMessage[] children) {
662: head.showMessage(newMessage, newType, children);
663: layout();
664: }
665:
666: /**
667: * Adds a message hyperlink listener. If at least one listener is present,
668: * messages will be rendered as hyperlinks.
669: *
670: * @param listener
671: * @see #removeMessageHyperlinkListener(IHyperlinkListener)
672: * @since 3.3
673: */
674: public void addMessageHyperlinkListener(IHyperlinkListener listener) {
675: head.addMessageHyperlinkListener(listener);
676: }
677:
678: /**
679: * Remove the message hyperlink listener.
680: *
681: * @param listener
682: * @see #addMessageHyperlinkListener(IHyperlinkListener)
683: * @since 3.3
684: */
685: public void removeMessageHyperlinkListener(
686: IHyperlinkListener listener) {
687: head.removeMessageHyperlinkListener(listener);
688: }
689:
690: /**
691: * Tests if the form is in the 'busy' state. Busy form displays 'busy'
692: * animation in the area of the title image.
693: *
694: * @return <code>true</code> if busy, <code>false</code> otherwise.
695: * @since 3.2
696: */
697:
698: public boolean isBusy() {
699: return head.isBusy();
700: }
701:
702: /**
703: * Sets the form's busy state. Busy form will display 'busy' animation in
704: * the area of the title image.
705: *
706: * @param busy
707: * the form's busy state
708: * @since 3.2
709: */
710:
711: public void setBusy(boolean busy) {
712: head.setBusy(busy);
713: }
714:
715: /**
716: * Adds support for dragging items out of the form title area via a user
717: * drag-and-drop operation.
718: *
719: * @param operations
720: * a bitwise OR of the supported drag and drop operation types (
721: * <code>DROP_COPY</code>,<code>DROP_LINK</code>, and
722: * <code>DROP_MOVE</code>)
723: * @param transferTypes
724: * the transfer types that are supported by the drag operation
725: * @param listener
726: * the callback that will be invoked to set the drag data and to
727: * cleanup after the drag and drop operation finishes
728: * @see org.eclipse.swt.dnd.DND
729: * @since 3.3
730: */
731: public void addTitleDragSupport(int operations,
732: Transfer[] transferTypes, DragSourceListener listener) {
733: head.addDragSupport(operations, transferTypes, listener);
734: }
735:
736: /**
737: * Adds support for dropping items into the form title area via a user
738: * drag-and-drop operation.
739: *
740: * @param operations
741: * a bitwise OR of the supported drag and drop operation types (
742: * <code>DROP_COPY</code>,<code>DROP_LINK</code>, and
743: * <code>DROP_MOVE</code>)
744: * @param transferTypes
745: * the transfer types that are supported by the drop operation
746: * @param listener
747: * the callback that will be invoked after the drag and drop
748: * operation finishes
749: * @see org.eclipse.swt.dnd.DND
750: * @since 3.3
751: */
752: public void addTitleDropSupport(int operations,
753: Transfer[] transferTypes, DropTargetListener listener) {
754: head.addDropSupport(operations, transferTypes, listener);
755: }
756:
757: /*
758: * (non-Javadoc)
759: *
760: * @see org.eclipse.jface.dialogs.IMessageProvider#getMessage()
761: */
762: public String getMessage() {
763: return head.getMessage();
764: }
765:
766: /*
767: * (non-Javadoc)
768: *
769: * @see org.eclipse.jface.dialogs.IMessageProvider#getMessageType()
770: */
771: public int getMessageType() {
772: return head.getMessageType();
773: }
774:
775: /**
776: * Returns the children messages that the cause of the summary message
777: * currently set on the form.
778: *
779: * @return an array of children messages or <code>null</code> if not set.
780: * @see #setMessage(String, int, IMessage[])
781: * @since 3.3
782: */
783: public IMessage[] getChildrenMessages() {
784: return head.getChildrenMessages();
785: }
786:
787: void setSelectionText(FormText text) {
788: if (selectionText != null && selectionText != text) {
789: selectionText.clearSelection();
790: }
791: this.selectionText = text;
792: }
793: }
|