1 /*******************************************************************************

     2  * Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies).

     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  *     Nokia Corporation - initial implementation

    10  *******************************************************************************/

    11 package org.eclipse.swt.internal.qt;

    12 

    13 import org.eclipse.ercp.swt.mobile.Command;

    14 import org.eclipse.swt.internal.qt.CommandArranger.CommandCollection;

    15 import org.eclipse.swt.widgets.Control;

    16 import org.eclipse.swt.widgets.Display;

    17 /**

    18  * This is the interface that all the {@link Command} presentation is delegated to.

    19  * The implementations of this abstract class are expected to provide the

    20  * presentation logic for their respective uses.

    21  *

    22  * The implementations of this class can be specific to a platform, toolkit or a

    23  * combination of factors. Refer to {@link CommandArranger} on the loading mechanism

    24  * of the {@link CommandPresentationStrategy} implementation.

    25  *

    26  * Since the implementations can be specific to a toolkit implementations are expected to

    27  * handle the following.

    28  * <ul>

    29  * 	<li>Ordering of the {@link Command}s</li>

    30  * 	<li>Positioning {@link Command}s to correct soft keys or menus so that they are accessible</li>

    31  * </ul>

    32  *

    33  */

    34 public abstract class CommandPresentationStrategy {

    35 

    36 

    37     /**

    38      * CommandArranger delegates to this method when the currently active menu bar has changed.

    39      * This does not include the cases where menu bar changes due to active window change which

    40      * causes the menu bar to change on some platforms.

    41      *

    42      * @param newMenuBar

    43      * @param commands

    44      */

    45     protected abstract void handleMenuBarChanged( int newMenuBar, CommandCollection commands );

    46 

    47     /**

    48      * CommandArranger delegates to this method when the currently focused control has changed.

    49      * On some platforms a focus change can also be accompanied with a menu bar change. Such menu bar

    50      * changes due to active window change must be handled here.

    51      *

    52      * @param focused-currently focused control

    53      * @param oldCommands-the commands of the previous focus context

    54      * @param commands-of the current focus context

    55      *

    56      * @see CommandArranger#focusedControlChanged()

    57      */

    58     protected abstract void handleFocusChange( Control focused, CommandCollection oldCommands, CommandCollection commands );

    59 

    60     /**

    61      * CommandArranger delegates to this method, an added or removed Command is in the current

    62      * focus context and needs to be presented. In other words, this method does not get notification of

    63      * all added or removed Commands but only those that has some impact on the representation.

    64      *

    65      * @param added Command

    66      * @param removed Command

    67      * @param commands including the added/removed command

    68      *

    69      * @see CommandArranger#commandAdded(Command)

    70      * @see CommandArranger#commandRemoved(Command)

    71      */

    72     protected abstract void handleCommandListChange(Command added, Command removed, CommandCollection commands );

    73 

    74     /**

    75      * CommandArranger reports the default command changes to this method. However implementations

    76      * should take into account default commands on focus changes.

    77      *

    78      * @param defaultCommand

    79      */

    80     protected abstract void handleDefaultCommandChange( Command defaultCommand );

    81     /**

    82      * This method is called when the CommandArranger is disposed as part of

    83      * the disposal of the {@link Display} or

    84      * if it is replaced by a new one on the CommandArranger.

    85      *

    86      * On Display dispose, the method is called after all the Shells are disposed but before the Display is cleaned.

    87      *

    88      * @see CommandArranger#setPresentationStrategy(CommandPresentationStrategy)

    89      */

    90     protected abstract void dispose();

    91 

    92 }