Eclipse GEF 3.3

## org.eclipse.gef.ui.palette.customize
Class PaletteCustomizerDialog

    java.lang.Object
      org.eclipse.jface.window.Window
          org.eclipse.jface.dialogs.Dialog
              org.eclipse.gef.ui.palette.customize.PaletteCustomizerDialog

All Implemented Interfaces:
  EntryPageContainer, IShellProvider

public class PaletteCustomizerDialog
extends Dialog
implements EntryPageContainer

This class implements a default dialog that allows customization of the different entries/items on a GEF palette, i.e. the model behind the palette.

The construction of the dialog is broken down into different methods in order to allow clients to further customize the appearance of the dialog, if so desired.

This dialog can be re-used, i.e., it can be re-opened once closed. There is no need to create a new `PaletteCustomizerDialog` everytime a palette needs to be customized.

See Also:
  `PaletteEntry`, `PaletteCustomizer`

Nested Class Summary

Nested classes inherited from class org.eclipse.jface.window.Window
`Window.IExceptionHandler`

Field Summary
`protected static int` `APPLY_ID` The unique ID for the Apply Button.
`protected static int` `CLIENT_ID` Sub-classes that need to create their own unique IDs should do so by adding to this ID.

Fields inherited from class org.eclipse.jface.dialogs.Dialog
`blockedHandler, buttonBar, DIALOG_DEFAULT_BOUNDS, DIALOG_PERSISTLOCATION, DIALOG_PERSISTSIZE, dialogArea, DLG_IMG_ERROR, DLG_IMG_HELP, DLG_IMG_INFO, DLG_IMG_MESSAGE_ERROR, DLG_IMG_MESSAGE_INFO, DLG_IMG_MESSAGE_WARNING, DLG_IMG_QUESTION, DLG_IMG_WARNING, ELLIPSIS`

Fields inherited from class org.eclipse.jface.window.Window
`CANCEL, OK`

Constructor Summary
`PaletteCustomizerDialog(Shell shell, PaletteCustomizer customizer, PaletteRoot root)` Constructs a new customizer dialog.

Method Summary
`protected void` `buttonPressed(int buttonId)` This method will be invoked whenever any `Button` created using `createButton(Composite, int, String, int, ImageDescriptor)` or `Dialog#createButton(Composite, int, String, boolean)` is selected.
`void` `clearProblem()` This method should be invoked by EntryPages when an error that they had earlier reported (using `showProblem(String)`) is fixed.
`boolean` `close()` NOTE: This dialog can be re-opened.
`protected void` `configureShell(Shell newShell)`
`protected Button` `createButton(Composite parent, int id, String label, int stylebits, ImageDescriptor descriptor)` This method should not be used to create buttons for the button bar.
`protected void` `createButtonsForButtonBar(Composite parent)` Creates the OK, Cancel and Apply buttons
`protected Control` `createDialogArea(Composite parent)` The dialog area contains the following: Outline (`createOutline(Composite)`) Properties Panel (`createPropertiesPanel(Composite)`) It is recommended that this method not be overridden.
`protected Control` `createOutline(Composite container)` Creates the outline part of the dialog.
`protected List` `createOutlineActions()` Creates the actions that manipulate the palette model.
`protected Menu` `createOutlineContextMenu()` Uses a `MenuManager` to create the context menu for the outline.
`protected Control` `createOutlineToolBar(Composite parent)` Uses a ToolBarManager to create the ToolBar in the outline part of the dialog.
`protected TreeViewer` `createOutlineTreeViewer(Composite composite)` Creates the TreeViewer that is the outline of the model.
`protected Control` `createPropertiesPanel(Composite container)` Creates the part of the dialog where the properties of the element selected in the outline will be displayed.
`protected PageBook` `createPropertiesPanelTitle(Composite parent)` Creates the title for the properties panel.
`protected CLabel` `createSectionTitle(Composite composite, String text)` A convenient method to create CLabel titles (like the ones used in the Preferences dialog in the Eclipse workbench) throughout the dialog.
`protected Button` `getButton(int id)` Returns the Button with the given id; or `null` if none was found.
`protected PaletteCustomizer` `getCustomizer()`
`protected EntryPage` `getEntryPage(PaletteEntry entry)` Returns the `EntryPage` for the given `PaletteEntry`.
`protected List` `getOutlineActions()` Provides access to the actions that are used to manipulate the model.
`protected PaletteRoot` `getPaletteRoot()` Provides sub-classes with access to the PaletteRoot
`protected PaletteEntry` `getSelectedPaletteEntry()`
`protected TreeItem` `getSelectedTreeItem()`
`protected Widget` `getWidget(int id)` The `Widget`s that were created with a unique ID and added to this class' internal map can be retrieved through this method.
`protected void` `handleApplyPressed()` This method is invoked when the Apply button is pressed IMPORTANT: It is recommended that you not override this method.
`protected void` `handleDelete()` This method is called when the "Delete" action is run (either through the context menu or the toolbar).
`protected void` `handleMoveDown()` This method is called when the "Move Down" action is run (either through the context menu or the toolbar).
`protected void` `handleMoveUp()` This method is called when the "Move Up" action is run (either through the context menu or the toolbar).
`protected void` `handleOutlineSelectionChanged()` This is the method that is called everytime the selection in the outline (treeviewer) changes.
`protected void` `revertToSaved()` This method is invoked when the changes made since the last save need to be cancelled.
`protected void` `save()` This method is invoked when the changes made since the last save need to be saved.
`protected void` `setActiveEntry(PaletteEntry entry)` This methods sets the active entry.
`protected void` `setActiveEntryPage(EntryPage page)` Sets the given EntryPage as the top page in the PageBook that shows the properties of the item selected in the Outline.
`void` `setDefaultSelection(PaletteEntry entry)` Sets the given PaletteEntry as the one to be selected when the dialog opens.
`void` `showProblem(String error)` This method should be invoked by EntryPages when there is an error.
`protected void` `updateActions()` Updates the actions created in `createOutlineActions()`, enabling or disabling them as necessary.

Methods inherited from class org.eclipse.jface.dialogs.Dialog

`applyDialogFont, cancelPressed, convertHeightInCharsToPixels, convertHeightInCharsToPixels, convertHorizontalDLUsToPixels, convertHorizontalDLUsToPixels, convertVerticalDLUsToPixels, convertVerticalDLUsToPixels, convertWidthInCharsToPixels, convertWidthInCharsToPixels, create, createButton, createButtonBar, createButtonsForButtonBar, createContents, createDialogArea, dialogFontIsDefault, getBlockedHandler, getButtonBar, getCancelButton, getDialogArea, getDialogBoundsSettings, getDialogBoundsStrategy, getImage, getInitialLocation, getInitialSize, getOKButton, initializeBounds, initializeDialogUnits, isResizable, okPressed, setBlockedHandler, setButtonLayoutData, setButtonLayoutFormData, shortenText`

Methods inherited from class org.eclipse.jface.window.Window

`canHandleShellCloseEvent, configureShell, constrainShellSize, createShell, getConstrainedShellBounds, getContents, getDefaultImage, getDefaultImages, getDefaultOrientation, getLayout, getParentShell, getReturnCode, getShell, getShellListener, getShellStyle, getWindowManager, handleFontChange, handleShellCloseEvent, open, setBlockOnOpen, setDefaultImage, setDefaultImages, setDefaultModalParent, setDefaultOrientation, setExceptionHandler, setParentShell, setReturnCode, setShellStyle, setWindowManager`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### APPLY_ID

    protected static final int APPLY_ID

  The unique ID for the Apply Button. It can be used to retrieve that widget from the internal map (using `getWidget(int)` or `getButton(int)`), or to identify that widget in `buttonPressed(int)`.

  See Also:
    Constant Field Values

### CLIENT_ID

    protected static final int CLIENT_ID

  Sub-classes that need to create their own unique IDs should do so by adding to this ID.

  See Also:
    Constant Field Values

Constructor Detail

### PaletteCustomizerDialog

    public PaletteCustomizerDialog(Shell shell,
                                   PaletteCustomizer customizer,
                                   PaletteRoot root)

  Constructs a new customizer dialog.

Parameters:
  `shell` - the parent Shell
  `customizer` - the customizer
  `root` - the palette root

Method Detail

### buttonPressed

    protected void buttonPressed(int buttonId)

  This method will be invoked whenever any `Button` created using `createButton(Composite, int, String, int, ImageDescriptor)` or `Dialog#createButton(Composite, int, String, boolean)` is selected.

  See Also:
    `Dialog.buttonPressed(int)`

### clearProblem

    public void clearProblem()

  This method should be invoked by EntryPages when an error that they had earlier reported (using `showProblem(String)`) is fixed. This will hide the error message, enable the OK and Apply buttons and re-allow changing selection in the outline tree.

  Specified by:
    `clearProblem` in interface `EntryPageContainer`
  See Also:
    `EntryPageContainer.clearProblem()`, `showProblem(String)`

### close

    public boolean close()

  NOTE: This dialog can be re-opened.

  See Also:
    `Window.close()`

### configureShell

    protected void configureShell(Shell newShell)

  See Also:
    `org.eclipse.jface.window.Window#configureShell(Shell)`

### createButton

    protected Button createButton(Composite parent,
                                  int id,
                                  String label,
                                  int stylebits,
                                  ImageDescriptor descriptor)

  This method should not be used to create buttons for the button bar. Use `Dialog#createButton(Composite, int, String, boolean)` for that. This method can be used to create any other button in the dialog. The parent `Composite` must have a GridLayout. These buttons will be available through `getButton(int)` and `getWidget(int)`. Ensure that the various buttons created by this method are given unique IDs. Pass in a `null` image descriptor if you don't want the button to have an icon. This method will take care of disposing the images that it creates. `buttonPressed(int)` will be called when any of the buttons created by this method are clicked (selected).

  Parameters:
    `parent` - The composite in which the button is to be created
    `id` - The button's unique ID
    `label` - The button's text
    `stylebits` - The style bits for creating the button (eg., `SWT.PUSH` or `SWT.CHECK`)
    `descriptor` - The ImageDescriptor from which the image/icon for this button should be created
  Returns:
    The newly created button for convenience

### createButtonsForButtonBar

    protected void createButtonsForButtonBar(Composite parent)

  Creates the OK, Cancel and Apply buttons

  See Also:
    `org.eclipse.jface.dialogs.Dialog#createButtonsForButtonBar(Composite)`

### createDialogArea

    protected Control createDialogArea(Composite parent)

  The dialog area contains the following:
  - Outline (`createOutline(Composite)`)
  - Properties Panel (`createPropertiesPanel(Composite)`)

  It is recommended that this method not be overridden. Override one of the methods that this method calls in order to customize the appearance of the dialog.

  See Also:
    `org.eclipse.jface.dialogs.Dialog#createDialogArea(Composite)`

### createOutline

    protected Control createOutline(Composite container)

  Creates the outline part of the dialog.

  The outline creates the following:

  - ToolBar (`createOutlineToolBar(Composite)`)
  - TreeViewer (`createOutlineTreeViewer(Composite)`)
  - Context menu (`createOutlineContextMenu()`)

  Parameters:
    `container` - The Composite within which the outline has to be created
  Returns:
    The newly created Control that has the outline

### createOutlineActions

    protected List createOutlineActions()

  Creates the actions that manipulate the palette model. These actions will populate the toolbar and the outline's context menu.

  IMPORTANT: All the elements in the returned List MUST be `PaletteCustomizationAction`s.

  Returns:
    A List of `PaletteCustomizationActions`

### createOutlineContextMenu

    protected Menu createOutlineContextMenu()

  Uses a `MenuManager` to create the context menu for the outline. The `IActions` used to create the context menu are those created in `createOutlineActions()`.

  Returns:
    The newly created Menu

### createOutlineToolBar

    protected Control createOutlineToolBar(Composite parent)

  Uses a ToolBarManager to create the ToolBar in the outline part of the dialog. The Actions used in the ToolBarManager are those that are created in `createOutlineActions()`.

  Parameters:
    `parent` - The Composite to which the ToolBar is to be added
  Returns:
    The newly created ToolBar

### createOutlineTreeViewer

    protected TreeViewer createOutlineTreeViewer(Composite composite)

  Creates the TreeViewer that is the outline of the model.

  Parameters:
    `composite` - The Composite to which the ToolBar is to be added
  Returns:
    The newly created TreeViewer

### createPropertiesPanel

    protected Control createPropertiesPanel(Composite container)

  Creates the part of the dialog where the properties of the element selected in the outline will be displayed.

  The properties panel contains the following:

  - Title (`createPropertiesPanelTitle(Composite)`)
  The rest of the panel is constructed in this method.

  Parameters:
    `container` - The Composite to which this part is to be added
  Returns:
    The properties panel

### createPropertiesPanelTitle

    protected PageBook createPropertiesPanelTitle(Composite parent)

  Creates the title for the properties panel. It is a PageBook that can switch between showing the regular title (the selected entry's label and icon) and an error message if an error has occured.

  Parameters:
    `parent` - The parent composite
  Returns:
    The newly created PageBook title

### createSectionTitle

    protected CLabel createSectionTitle(Composite composite,
                                        String text)

  A convenient method to create CLabel titles (like the ones used in the Preferences dialog in the Eclipse workbench) throughout the dialog.

  Parameters:
    `composite` - The composite in which the title is to be created (it must have a GridLayout with two columns).
    `text` - The title to be displayed
  Returns:
    The newly created CLabel for convenience

### getButton

    protected Button getButton(int id)

  Returns the Button with the given id; or `null` if none was found.

  See Also:
    `Dialog.getButton(int)`

### getCustomizer

    protected PaletteCustomizer getCustomizer()

  Returns:
    The customizer that is responsible for handling the various tasks and updating the model.

### getEntryPage

    protected EntryPage getEntryPage(PaletteEntry entry)

  Returns the `EntryPage` for the given `PaletteEntry`. The `EntryPage` is retrieved from the customizer. If the given entry is `null`, `null` will be returned. If the customizer returns `null` for the valid entry, a default page will be created and returned.

  Parameters:
    `entry` - The PaletteEntry whose properties need to be displayed
  Returns:
    The EntryPage with the properties of the given PaletteEntry

### getOutlineActions

    protected final List getOutlineActions()

  Provides access to the actions that are used to manipulate the model. The actions will be created, if they haven't been yet.

  Returns:
    the list of `PaletteCustomizationAction`s
  See Also:
    `createOutlineActions()`

### getPaletteRoot

    protected PaletteRoot getPaletteRoot()

  Provides sub-classes with access to the PaletteRoot

  Returns:
    the palette root

### getSelectedPaletteEntry

    protected PaletteEntry getSelectedPaletteEntry()

  Returns:
    The PaletteEntry that is currently selected in the Outline Tree; `null` if none is selected

### getSelectedTreeItem

    protected TreeItem getSelectedTreeItem()

  Returns:
    The TreeItem that is currently selected in the Outline Tree; `null` if none is selected

### getWidget

    protected Widget getWidget(int id)

  The `Widget`s that were created with a unique ID and added to this class' internal map can be retrieved through this method.

  Parameters:
    `id` - The unique ID of the Widget that you wish to retrieve
  Returns:
    The Widget, if one with the given id exists; `null` otherwise

### handleApplyPressed

    protected final void handleApplyPressed()

  This method is invoked when the Apply button is pressed

  IMPORTANT: It is recommended that you not override this method. Closing the dialog with the 'X' at the top right of the window, or by hitting 'Esc' or any other way, corresponds to a "Cancel." That will, however, not result in this method being invoked. To handle such cases, saving or rejecting the changes is handled in `close()`. Override `save()` and `revertToSaved()` to add to what needs to be done when saving or cancelling.

### handleDelete

    protected void handleDelete()

  This method is called when the "Delete" action is run (either through the context menu or the toolbar). It deletes the selected palette entry.

### handleMoveDown

    protected void handleMoveDown()

  This method is called when the "Move Down" action is run (either through the context menu or the toolbar). It moves the selected palette entry down.

### handleMoveUp

    protected void handleMoveUp()

  This method is called when the "Move Up" action is run (either through the context menu or the toolbar). It moves the selected entry up.

### handleOutlineSelectionChanged

    protected void handleOutlineSelectionChanged()

  This is the method that is called everytime the selection in the outline (treeviewer) changes.

### revertToSaved

    protected void revertToSaved()

  This method is invoked when the changes made since the last save need to be cancelled.

### save

    protected void save()

  This method is invoked when the changes made since the last save need to be saved.

### setActiveEntry

    protected void setActiveEntry(PaletteEntry entry)

  This methods sets the active entry. Based on the selection, this method will appropriately enable or disable the ToolBar items, will change the CLabel heading of the propreties panel, and will show the properties of the selected item in the properties panel.

  Parameters:
    `entry` - The new active entry, i.e., the new selected entry (it can be `null`)

### setActiveEntryPage

    protected void setActiveEntryPage(EntryPage page)

  Sets the given EntryPage as the top page in the PageBook that shows the properties of the item selected in the Outline. If the given EntryPage is null, nothing will be shown.

  Parameters:
    `page` - The EntryPage to be shown

### setDefaultSelection

    public void setDefaultSelection(PaletteEntry entry)

  Sets the given PaletteEntry as the one to be selected when the dialog opens. It is discarded when the dialog is closed.

  Parameters:
    `entry` - The PaletteEntry that should be selected when the dialog is opened

### showProblem

    public void showProblem(String error)

  This method should be invoked by EntryPages when there is an error. It will show the given error in the title of the properties panel. OK and Apply buttons will be disabled. Selecting some other entry in the outline tree will not be allowed until the error is fixed.

  Specified by:
    `showProblem` in interface `EntryPageContainer`
  Parameters:
    `error` - A description of the problem. Should be as brief as possible.
  See Also:
    `EntryPageContainer.showProblem(String)`

### updateActions

    protected void updateActions()

  Updates the actions created in `createOutlineActions()`, enabling or disabling them as necessary.

Eclipse GEF 3.3

Copyright (c) IBM Corp. and others 2000, 2007. All Rights Reserved.