Implementar uma página de preferências

Definir a página

O plug-in JFace proporciona um quadro para implementar assistentes, páginas de preferências e diálogos. A implementação destes diálogos segue um padrão comum. O conteúdo de uma página ou diálogo é definido pela implementação de um método createContents que cria os controlos de SWT que representam o conteúdo da página. Este método deve também adicionar ouvintes para quaisquer eventos de interesse. A página é responsável por criar e devolver o compósito que será ascendente de todos os controlos na página. A porção de código seguinte mostra os destaques:

protected Control createContents(Composite parent)
{
	...
	//composite_textField << parent
	Composite composite_textField = createComposite(parent, 2);
	Label label_textField = createLabel(composite_textField, MessageUtil.getString("Text_Field"));	 
	textField = createTextField(composite_textField);
	pushButton_textField = createPushButton(composite_textField, MessageUtil.getString("Change")); 

	//composite_tab << parent
	Composite composite_tab = createComposite(parent, 2);
	Label label1 = createLabel(composite_tab, MessageUtil.getString("Radio_Button_Options")); 

	//
	tabForward(composite_tab);
	//radio button composite << tab composite
	Composite composite_radioButton = createComposite(composite_tab, 1);
	radioButton1 = createRadioButton(composite_radioButton, MessageUtil.getString("Radio_button_1")); 
	radioButton2 = createRadioButton(composite_radioButton, MessageUtil.getString("Radio_button_2")); 
	radioButton3 = createRadioButton(composite_radioButton, MessageUtil.getString("Radio_button_3")); 


	//composite_tab2 << parent
	Composite composite_tab2 = createComposite(parent, 2);
	Label label2 = createLabel(composite_tab2, MessageUtil.getString("Check_Box_Options")); //$NON-NLS-1$

	//
	tabForward(composite_tab2);
	//composite_checkBox << composite_tab2
	Composite composite_checkBox = createComposite(composite_tab2, 1);
	checkBox1 = createCheckBox(composite_checkBox, MessageUtil.getString("Check_box_1")); 
	checkBox2 = createCheckBox(composite_checkBox, MessageUtil.getString("Check_box_2")); 
	checkBox3 = createCheckBox(composite_checkBox, MessageUtil.getString("Check_box_3")); 

	initializeValues();

	return new Composite(parent, SWT.NULL);
}

A maioria do código neste método prende-se com a criação e esquematização dos controlos, de modo que não as abordamos aqui.   A página correspondente assemelha-se ao seguinte:

Página de preferências da ferramenta readme

A outra responsabilidade principal de uma página de preferências consiste em reagir à mensagem performOk. Regra geral, este método actualiza e armazena as preferências de utilizador e, se necessário, actualiza outros objectos de plug-in para reflectirem a alteração nas preferências. O método performDefaults é utilizado para restaurar o estado predefinido das preferências quando o utilizador prime o botão Restaurar Predefinições.   

Poderá sobrepor performApply se tiver processamento adicional quando o utilizador seleccionar Aplicar.  A implementação predefinida consiste em chamar performOk.  

As páginas de preferências devem sobrepor o método doGetPreferenceStore() para devolver um arquivo de preferências para armazenar os respectivos valores.

Arquivo de preferências de plug-ins

Os arquivos de preferências são um mecanismo conveniente para aceder e armazenar valores de preferências numa classe de plug-in. Proporcionam acesso de nível de plug-in a preferências que estejam realmente armazenadas com o serviço de preferências de tempo de execução. AbstractUIPlugin define um arquivo de preferências de plug-ins abrangente que é mantido durante o ciclo de vida do plug-in. O plug-in pode adicionar entradas a este arquivo de preferências e actualizar os valores à medida que o utilizador altera as definições na página de preferências. Dado que os arquivos de preferências utilizam o serviço de preferências da plataforma, encarregam-se de guardar valores de preferências no âmbito e na localização apropriados, e de inicializar o arquivo de preferências com os mecanismos apropriados.

O código seguinte na ReadmePreferencePage obtém o arquivo de preferências para o ReadmePlugin.

   protected IPreferenceStore doGetPreferenceStore() {
      return ReadmePlugin.getDefault().getPreferenceStore();
   }

Dado que o ReadmePlugin estende a classe AbstractUIPlugin, herda automaticamente um arquivo de preferências. Este arquivo de preferências é inicializado com o serviço de preferências da plataforma. A única coisa que o ReadmePlugin tem que fazer é implementar um método que inicialize os controlos de preferências nos respectivos valores predefinidos. Estes valores são utilizados da primeira vez que a página de preferências é mostrada ou quando o utilizador premir o botão Predefinições na página de preferências.

protected void initializeDefaultPreferences(IPreferenceStore store) {
	// These settings will show up when Preference dialog
	// opens up for the first time.
	store.setDefault(IReadmeConstants.PRE_CHECK1, true);
	store.setDefault(IReadmeConstants.PRE_CHECK2, true);
	store.setDefault(IReadmeConstants.PRE_CHECK3, false);
	store.setDefault(IReadmeConstants.PRE_RADIO_CHOICE, 2);
	store.setDefault(IReadmeConstants.PRE_TEXT, MessageUtil.getString("Default_text")); //$NON-NLS-1$
}
Nota:  Se não houver preferências de plug-in guardadas em lugar algum, o plug-in irá obter um arquivo de preferências vazio.

Obter e guardar preferências

Uma vez associado o arquivo de preferências do plug-in à página de preferências, poderá implementar a lógica para obter e guardar as preferências.

As páginas de preferências são responsáveis pela inicialização de valores dos seus controlos mediante as definições de preferências oriundas do arquivo de preferências. Este processo é semelhante a inicializar valores de controlos de diálogos nas definições do diálogo. A ReadmePreferencePage inicializa todos os seus controlos num único método, initializeValues, o qual é chamado a partir do seu método createContents.

   private void initializeValues() {
	IPreferenceStore store = getPreferenceStore();
	checkBox1.setSelection(store.getBoolean(IReadmeConstants.PRE_CHECK1));
	checkBox2.setSelection(store.getBoolean(IReadmeConstants.PRE_CHECK2));
	checkBox3.setSelection(store.getBoolean(IReadmeConstants.PRE_CHECK3));
	...
}

Quando se prime o botão OK (ou Aplicar), os valores actuais dos controlos da página de preferências devem ser armazenados no arquivo de preferências. A ReadmePreferencePage implementa esta lógica num método separado, storeValues.

   private void storeValues() {
	IPreferenceStore store = getPreferenceStore();
	store.setValue(IReadmeConstants.PRE_CHECK1, checkBox1.getSelection());
	store.setValue(IReadmeConstants.PRE_CHECK2, checkBox2.getSelection());
	store.setValue(IReadmeConstants.PRE_CHECK3, checkBox3.getSelection());
	...
}

Quando o utilizador prime o botão Predefinições, a plataforma restaura as predefinições de todos os valores do arquivo de preferências especificados na classe do plug-in. Todavia, a página de preferências é responsável por reflectir estas predefinições nos controlos na página de preferências. A ReadmePreferencePage implementa isto em initializeDefaults.

   private void initializeDefaults() {
      IPreferenceStore store = getPreferenceStore();
      checkBox1.setSelection(store.getDefaultBoolean(IReadmeConstants.PRE_CHECK1));
      checkBox2.setSelection(store.getDefaultBoolean(IReadmeConstants.PRE_CHECK2));
      checkBox3.setSelection(store.getDefaultBoolean(IReadmeConstants.PRE_CHECK3));
      ...
   }