comparison org.eclipse.ui.forms/src/org/eclipse/ui/forms/widgets/Form.d @ 12:bc29606a740c

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