/*******************************************************************************
 * Copyright (c) 2007 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 * Port to the D programming language:
 *     Frank Benoit <benoit@tionex.de>
 ******************************************************************************/

module dwtx.ui.forms.IMessageManager;

import dwtx.ui.forms.IMessagePrefixProvider;
import dwtx.ui.forms.IMessage;

import dwt.widgets.Control;
import dwtx.jface.dialogs.IMessageProvider;
import dwtx.jface.fieldassist.ControlDecoration;
import dwtx.ui.forms.widgets.Form;

import dwt.dwthelper.utils;

/**
 * This interface provides for managing typed messages in a form. Typed messages
 * are messages associated with a type that indicates their severity (error,
 * warning, information). The interface is responsible for:
 * <ul>
 * <li>Bridging the concept of typed messages and control decorations</li>
 * <li>Adding one or more messages per control in a form</li>
 * <li>Rolling the local messages up to the form header</li>
 * <li>Adding one or more general messages to the form header</li>
 * </ul>
 * <p>
 * To use it in a form, do the following:
 * <ol>
 * <li>For each interactive control, add a listener to it to monitor user input</li>
 * <li>Every time the input changes, validate it. If there is a problem, add a
 * message with a unique key to the manager. If there is already a message with
 * the same key in the manager, its type and message text will be replaced (no
 * duplicates). Note that you add can messages with different keys to the same
 * control to track multiple problems with the user input.</li>
 * <li>If the problem has been cleared, remove the message using the key
 * (attempting to remove a message that is not in the manager is safe).</li>
 * <li>If something happens in the form that is not related to any control, use
 * the other <code>addMessage</code> method.</li>
 * </ol>
 * <p>
 * This interface should only be referenced. It must not be implemented or
 * extended.
 * </p>
 *
 * @since 3.3
 * @see IMessageProvider
 * @see IManagedForm
 * @noimplement This interface is not intended to be implemented by clients.
 */

public interface IMessageManager {
    /**
     * Adds a general message that is not associated with any decorated field.
     * Note that subsequent calls using the same key will not result in
     * duplicate messages. Instead, the previous message with the same key will
     * be replaced with the new message.
     *
     * @param key
     *            a unique message key that will be used to look the message up
     *            later
     *
     * @param messageText
     *            the message to add
     * @param data
     *            an object for application use (can be <code>null</code>)
     * @param type
     *            the message type as defined in <code>IMessageProvider</code>.
     */
    void addMessage(Object key, String messageText, Object data, int type);

    /**
     * Adds a message that should be associated with the provided control. Note
     * that subsequent calls using the same key will not result in duplicate
     * messages. Instead, the previous message with the same key will be
     * replaced with the new message.
     *
     * @param key
     *            the unique message key
     * @param messageText
     *            the message to add
     * @param data
     *            an object for application use (can be <code>null</code>)
     * @param type
     *            the message type
     * @param control
     *            the control to associate the message with
     */
    void addMessage(Object key, String messageText, Object data, int type,
            Control control);

    /**
     * Removes the general message with the provided key. Does nothing if
     * message for the key does not exist.
     *
     * @param key
     *            the key of the message to remove
     */
    void removeMessage(Object key);

    /**
     * Removes all the general messages. If there are local messages associated
     * with controls, the replacement message may show up drawing user's
     * attention to these local messages. Otherwise, the container will clear
     * the message area.
     */
    void removeMessages();

    /**
     * Removes a keyed message associated with the provided control. Does
     * nothing if the message for that key does not exist.
     *
     * @param key
     *            the id of the message to remove
     * @param control
     *            the control the message is associated with
     */
    void removeMessage(Object key, Control control);

    /**
     * Removes all the messages associated with the provided control. Does
     * nothing if there are no messages for this control.
     *
     * @param control
     *            the control the messages are associated with
     */
    void removeMessages(Control control);

    /**
     * Removes all the local field messages and all the general container
     * messages.
     */
    void removeAllMessages();

    /**
     * Updates the message container with the messages currently in the manager.
     * There are two scenarios in which a client may want to use this method:
     * <ol>
     * <li>When controls previously managed by this manager have been disposed.</li>
     * <li>When automatic update has been turned off.</li>
     * </ol>
     * In all other situations, the manager will keep the form in sync
     * automatically.
     *
     * @see #setAutoUpdate(bool)
     */
    void update();

    /**
     * Controls whether the form is automatically updated when messages are
     * added or removed. By default, auto update is on. Clients can turn it off
     * prior to adding or removing a number of messages as a batch. Turning it
     * back on will trigger an update.
     *
     * @param enabled
     *            sets the state of the automatic update
     */
    void setAutoUpdate(bool enabled);

    /**
     * Tests whether the form will be automatically updated when messages are
     * added or removed.
     *
     * @return <code>true</code> if auto update is active, <code>false</code>
     *         otherwise.
     */
    bool isAutoUpdate();

    /**
     * Sets the alternative message prefix provider. The default prefix provider
     * is set by the manager.
     *
     * @param provider
     *            the new prefix provider or <code>null</code> to turn the
     *            prefix generation off.
     */
    void setMessagePrefixProvider(IMessagePrefixProvider provider);

    /**
     * @return the current prefix provider or <code>null</code> if prefixes
     *         are not generated.
     */
    IMessagePrefixProvider getMessagePrefixProvider();

    /**
     * Message manager uses DWT.LEFT|DWT.BOTTOM for the default decoration
     * position. Use this method to change it.
     *
     * @param position
     *            the decoration position
     * @see ControlDecoration
     */
    void setDecorationPosition(int position);

    /**
     * Returns the currently used decoration position for all control messages.
     *
     * @return the current decoration position
     */

    int getDecorationPosition();

    /**
     * When message manager is used in context of a form, and there are
     * hyperlink listeners for messages in the header, the hyperlink event will
     * carry an object of type <code>IMessage[]</code> as an href. You can use
     * this method to create a summary text from this array consistent with the
     * tool tip used by the form header.
     *
     * @param messages
     *            an array of messages
     * @return a textual representation of the messages with one message per
     *         line.
     * @see Form#addMessageHyperlinkListener(dwtx.ui.forms.events.IHyperlinkListener)
     */
    String createSummary(IMessage[] messages);
}