IContextProvider


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 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   *******************************************************************************/
11  package org.eclipse.help;
12  
13  /**
14   * Dynamic context provider. Classes that implement this interface should be
15   * returned from adaptable objects when <code>IContextProvider.class</code> is
16   * used as the adapter key. Adaptable objects must implement
17   * <code>org.eclipse.core.runtime.IAdaptable</code> interface.
18   * <p>
19   * Dynamic context providers should be used for providing focused dynamic help
20   * that changes depending on the various platform states. State change criteria
21   * is defined by bitwise-OR of the individual state change triggers. Each time a
22   * registered trigger occurs, the class that implements this interface will be
23   * called again to provide the help context for the given target.
24   * <p>
25   * Context provider should be used for all visual artifacts that provide context
26   * help that handle context help trigger by handling the SWT help event instead
27   * of tagging the artifact with a static context Id.
28   * <p>
29   * In addition to providing static help context, this interface can also be used
30   * to control the query string that is passed to the help search system on
31   * context switches. If not provided, the query string is computed based on the
32   * current context. Providing the string explicitly gives the context owners
33   * better control over the search outcome.
34   * 
35   * @since 3.1
36   * @see IContext
37   * @see org.eclipse.core.runtime.IAdaptable
38   */
39  public interface IContextProvider {
40      /**
41       * State change trigger indicating a static context provider.
42       */
43      int NONE = 0x0;
44  
45      /**
46       * State change trigger indicating that the provider should be asked for
47       * context help on each selection change.
48       */
49      int SELECTION = 0x1;
50  
51      /**
52       * Returns the mask created by combining supported change triggers using the
53       * bitwise OR operation.
54       * 
55       * @return a bitwise-OR combination of state change triggers or
56       *         <code>NONE</code> for a static provider.
57       */
58      int getContextChangeMask();
59  
60      /**
61       * Returns a help context for the given target. The number of times this
62       * method will be called depends on the context change mask. Static context
63       * providers will be called each time the owner of the target is activated.
64       * If change triggers are used, the method will be called each time the
65       * trigger occurs.
66       * 
67       * @param target
68       *            the focus of the context help
69       * @return context help for the provided target or <code>null</code> if
70       *         none is defined.
71       */
72      IContext getContext(Object   target);
73  
74      /**
75       * Returns a search expression that should be used to find more information
76       * about the current target. If provided, it can be used for background
77       * search.
78       * 
79       * @param target
80       *            the focus of the context help
81       * @return search expression as defined by the help system search, or
82       *         <code>null</code> if background search is not desired.
83       */
84      String   getSearchExpression(Object   target);
85  }
86
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags