org.eclipse.cdt.ui/src/org/eclipse/cdt/ui/text/ITokenStore.java

   1 /*******************************************************************************
   2  * Copyright (c) 2008 Symbian Software Systems 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  * Andrew Ferguson (Symbian) - Initial implementation
  10  *******************************************************************************/
  11 package org.eclipse.cdt.ui.text;
  12
  13 import org.eclipse.jface.preference.IPreferenceStore;
  14 import org.eclipse.jface.text.rules.IToken;
  15
  16 import org.eclipse.cdt.ui.IPropertyChangeParticipant;
  17 import org.eclipse.cdt.ui.PreferenceConstants;
  18
  19 /**
  20  * An ITokenStore manages a set of tokens for a specified set of color property identifiers. Responsibilities include
  21  * <ul>
  22  * <li> Reacting to changes to preferences in a specified {@link IPreferenceStore}
  23  * <li> Managing whether further styles (bold, italic, strikethrough, underline) should be applied
  24  * <li> Coping with
  25  * </ul>
  26  *
  27  * ITokenStore assumes style preferences are stored under the following names
  28  * <p>
  29  * Preference color key + {@link PreferenceConstants#EDITOR_BOLD_SUFFIX} are used
  30  * to retrieve whether the token is rendered in bold.
  31  * </p>
  32  * <p>
  33  * Preference color key + {@link PreferenceConstants#EDITOR_ITALIC_SUFFIX} are used
  34  * to retrieve whether the token is rendered in italic.
  35  * </p>
  36  * <p>
  37  * Preference color key + {@link PreferenceConstants#EDITOR_STRIKETHROUGH_SUFFIX} are used
  38  * to retrieve whether the token is rendered in strikethrough.
  39  * </p>
  40  * <p>
  41  * Preference color key + {@link PreferenceConstants#EDITOR_UNDERLINE_SUFFIX} are used
  42  * to retrieve whether the token is rendered in underline.
  43  * </p>
  44  * <p>
  45  * Clients may implement this interface.
  46  * </p>
  47  *
  48  * @see ITokenStoreFactory
  49  * @since 5.0
  50  */
  51 public interface ITokenStore extends IPropertyChangeParticipant {
  52         /**
  53          * Ensures any IToken objects that will be <em>or have been</em> returned are
  54      * initialized for display.
  55          */
  56         void ensureTokensInitialised();
  57
  58         /**
  59          * @param property
  60          * @return a token for the specified property. The Token may not be suitable for use if the
  61          * current Display is null. Clients should call ITokenStoreFactory#ensureTokensInitialised() at the
  62          * point of token use in case this token store was originally initialized before a display was available.
  63          */
  64         IToken getToken(String property);
  65
  66         /**
  67          * @return The preference store used to read token styling preferences from.
  68          */
  69         IPreferenceStore getPreferenceStore();
  70 }