Referência para a classe KCModule

Nesse artigo, veremos os detalhes da classe KCModule, que é a classe base para os módulos de configuração disponíveis no systemsettings da Kde. Módulos de configuração são plugins que são carregados apenas quando são necessários. O módulo é um widget simples que exibe o item a ser modificado. Ele possui uma interface bem simples. Toda a lógica necessária e itens da interface são fornecidos pelo centro de controle e não precisam ser uma preocupação para o autor do módulo.

Para criar um módulo, você tem que criar uma biblioteca que contenha uma função como a seguinte:

 #include <KPluginFactory>
 K_PLUGIN_FACTORY(MyKCModuleFactory, registerPlugin<MyKCModule>() )
 K_EXPORT_PLUGIN(MyKCModuleFactory("yourLibName","name_of_the_po_file") )

O parâmetro opcional “name_of_the_po_file” tem que ser correspondente com os alvos de mensagens que contenham as strings a ser traduzidas. Ao invés de usar o nome da biblioteca para yourLibName você pode também usar outro nome que seja especificado no arquivo .desktop na opção X-KDE-FactoryName. Isso é útil para ter de uma função na mesma biblioteca.
O construtor do módulo KCModule fica parecido com isso:

 YourKCModule::YourKCModule( QWidget* parent )
   : KCModule( YourKCModuleFactory::componentData(), parent )
 {
   KAboutData *about = new KAboutData(
     <kcm name>, 0, ki18n( "..." ),
     KDE_VERSION_STRING, KLocalizedString(), KAboutData::License_GPL,
     ki18n( "Copyright 2006 ..." ) );
   about->addAuthor( ki18n(...) );
   setAboutData( about );
   .
   .
   .
 }

Se quiser tornar o módulo disponível apenas em certas condições (isto é, ser exibido na lista de módulos disponíveis apenas se algum tipo de teste tiver sucesso), assim você pode usar Hidden no arquivo .desktop. Um exemplo:

 Hidden[$e]=$(if test -e /dev/js*; then echo "false"; else echo "true"; fi)

O exemplo executa o código fornecido em um terminal e usa a saída do stdout como valor de Hidden (assim Hidden=true ou Hidden=false).

Documentação dos membros do tipo Enumeration

Um tipo enumeration para os botões usados pelo módulo.
Você deve usar apenas Help, Default e Apply. Os outros são obsoletos. NoAdditionButton pode ser usado quando não precisarmos ter nenhum outro botão além de Ok e Cancel.

Enumerador:
NoAdditionalButton
Help
Default
Apply
Export

Documentação para o Construtor & Destrutor

KCModule::KCModule(const KComponentData &componentData,  QWidget *parent = 0,  const QVariantList &args = QVariantList() ) [explicit]

Classe base para todos os módulos KControlModules.

Nota:
Não emita sinals para modificações aqui, já que  eles ainda não estarão conectados a um slot;

KCModule::~KCModule( )

Destrói o módulo.

Documentação das funções membro

const KAboutData * KCModule::aboutData( )const [virtual]

Essa função é chamada geralmente por KBugReport. Se você sobrecarregar essa função deve retornar um ponteiro para uma constante.

Retorno:
KAboutData desse módulo

KConfigDialogManager * KCModule::addConfig(KCoreConfigSkeleton *config,  QWidget *widget ) [protected]

Adiciona um item config KCoreConfigskeleton para observar o widget widget. Essa função é útil se você precisa manipular múltiplos arquivos de configuração.

Retorno:
um ponteiro para o KCoreConfigDialogManager em uso.
Parameters:
configthe KCoreConfigSkeleton to usewidgetthe widget to watch

KConfigDialogManager * KCModule::addConfig(KConfigSkeleton *config,  QWidget *widget ) [protected]

Adiciona um item config KConfigskeleton para observar o widget widget. Essa função é útil se você precisa manipular múltiplos arquivos de configuração.
Retorno:

um ponteiro para o KConfigDialogManager em uso
Parameters:
configthe KConfigSkeleton to usewidgetthe widget to watch

KAuth::Action * KCModule::authAction( )const

Retorna a ação configurada anteriormente com setAuthAction(). Por padrão, retorna uma ação inválida.

Retorno:
A ação que tem que ser autorizada para executar o método save().

void KCModule::authStatusChanged(intstatus )[protected, slot]

Retorna se o status da ação auth, se existir, foi alterado.

KCModule::Buttons KCModule::buttons( )const

Indica quais botões serão usados. O valor de retorno é um valor que funciona em conjunto com o tipo enumeração do Botão.

void KCModule::changed(boolstate )[signal]

Indica que o estado do conteúdo dos módulos foi alterado. Esse sinal é emitido toda vez que o estado das configurações mostrada no módulo é alterada. Isso permite que o módulo mantenha um registro das alterações não salvas.

void KCModule::changed( )[protected, slot]

Chamando esse slot é equivalente a emitir  changed(true).

KComponentData KCModule::componentData( )const

QListKConfigDialogManager * > KCModule::configs( )const

Retorno:
uma lista dos KConfigDialogManager em uso, se existir algum.

void KCModule::defaults( )[virtual, slot]

Ajusta as configurações para valores padrões sensíveis. Esse método é chamado quando o usuário clica no botão “Default”. Deve ajustar a exibição de valores úteis. Se você usar KConfigXT, não terá que reimplementar essa função já que a captura e ajuste dos valores padrão é feito automaticamente. Porém, se você reimplementar e também usar KCOnfigXT, lembre de chamar a função base no final de sua reimplementação.
 

QString KCModule::exportText( )const

Retorna o valor configurado por setExportText().

void KCModule::load( )[virtual, slot]

Carrega os dados de configuração do módulo. O método load configura os elementos da interface com o usuário do módulo para refletir as configurações armazenadas nos arquivos de configuração. Esse método é invocado sempre que o módulo precisa ler as configurações (a maioria das vezes de um arquivo de configuração) e atualizar a interface com o usuário. Isso acontece quando o usuário clica no botão “Reset” do painel de controle, para desafazer todas as suas alterações e voltar paras as configurações válidas. É chamado também logo após a inicialização do módulo.

bool KCModule::managedWidgetChangeState( )const [protected]

Retorna o estado alterado de widgets gerenciados automaticamente da caixa de diálogo.

bool KCModule::needsAuthorization( )const

Retorna o valor anteriormente configurado em setNeedsAuthorization(). O padrão é false.

Retorno:
true se o método save() do módulo precisa de autorização, e false caso contrário.

QString KCModule::quickHelp( )const [virtual]

Retorna um texto de ajuda. Esse método  é chamado quando o módulo está ancorado. O texto de ajuda deve conter uma descrição curta do módulo e links para os arquivos de ajuda do módulo. Você pode usar tags de formatação QML no texto.

Nota:
certifique-se de que o texto de ajuda seja traduzido (use i18n()).

void KCModule::quickHelpChanged( )[signal]

Indica que a ajuda do módulo foi alterada. Emita essa sinal sempre que a ajuda do módulo for alterada. O módulo implementado como caixa de diálogo com abas precisam implementar ajuda para cada aba por exemplo.

QString KCModule::rootOnlyMessage( )const

Obtém a mensagem RootOnly para esse módulo. Quando o módulo precisa ser executado como root, ou atuar de forma diferente com usuário normal ou root, é útil algumas vezes personalizar a mensagem que aparece na parte superior do módulo quando ele for usado como um usuário normal. Essa função retorna essa mensagem personalizada. Se nenhuma for configurada, a mensagem padrão será retornada.

void KCModule::rootOnlyMessageChanged(booluse,  QStringmessage ) [signal]

Indica se a mensagem de aviso RootOnly foi alterada. Emita esse sinal se a mensagem for alterada.

void KCModule::save( )[virtual, slot]

Salva os dados de configuração. O método save armazena as informações de configuração que são exibidos na interface nos arquivos de configuração. Se necessário, esse método também atualiza o sistema em execução, ex. reiniciando as aplicações. Isso normalmente não se aplica aos módulos KSettings::Dialog onde a atualização é feita pelo KSettings::Dispatcher. Esse método é chamado quando o usuário clica em “Apply” ou “Ok”.
Se você usar KConfigXT, o salvamento é feito automaticamente e você não precisa carregar manualmente. Porém, se você por alguma razão reimplementar esse método e também usar KConfigXT, precisa chamar essa função, senão o salvamento das opções do KConfigXT não funcionarão. Chame esse método no final de sua reimplementação, para evitar que sinais changed() quando modificar os widgets.

void KCModule::setAboutData(const KAboutData *about )

Configura o KAboutData retornado por aboutData()

void KCModule::setButtons(Buttonsbtn )[protected]

Configura os botões a exibir.
Help: mostra um botão de ajuda.
Default: mostra um botão “Use Defaults”.
Apply: no kcontrol isso exibirá botões “Apply” e “Reset” , no kcmshell serão exibidos os botões “Ok”, “Apply” e “Cancel”.
Se ‘Apply’ não for especificado, o kcmshell mostrará um botão “Close”.

void KCModule::setExportText(const QString &text )

Configure o valor de exportação de QString, usado pelos dados de exportação.

void KCModule::setNeedsAuthorization(boolneedsAuth )

Configura se o método save() do módulo precisa de autorização para ser executado. O módulo pode configurar essa propriedade para true se precisar de autorização. Ele ainda terá que executar a ação usando a biblioteca KAuth, de forma que esse método não é tecnicamente necessário para executar a ação, mas usando ele e/ou o método setAuthAction() garantirá que aplicações com o SystemSettings ou kcmshell se comportem de forma correta.
Chamado com true, esse método configurará a ação de “org.kde.kcontrol.name.save”, onde “name” é o valor de retorno de aboutData()->appName() Essa ação padrão não será configurada se o objeto aboutData() não for válido.
Note que se chamado com o valor false, esse método irá reiniciar o nome da ação com setAuthAction().

Paramêtros:
needsAuthTells if the module's save() method requires authorization to be executed.

void KCModule::setQuickHelp(const QString &help )[protected]

Configura a ajuda rápida.

void KCModule::setRootOnlyMessage(const QString &message )[protected]

Configura a mensagem do RootOnly. Essa mensagem será mostrada na parte superior do módulo se useRootOnlyMessage estiver configurado. Se nenhuma mensagem for configurada, uma mensagem padrão será usada.

void KCModule::setUseRootOnlyMessage(boolon )[protected]

Define se a mensagem RootOnly será mostrada ou não.

void KCModule::showEvent(QShowEvent *ev )[protected, virtual]

Reimplementação de QWidget.

void KCModule::unmanagedWidgetChangeState(boolchanged )[protected]

Chame esse método quando seus widgets gerenciados manualmente mudarem do estado alterado para não alterado.

bool KCModule::useRootOnlyMessage( )const

Diz se o KControl deve exibir a mensagem RootOnly quando o módulo estiver sendo executado por um usuário normal.

void KCModule::widgetChanged( )[protected, slot]

Um widget gerenciado foi alterado, as configurações desse widget são comparadas com as atuais e o sinal changed() será emitido.

Traduzido de http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKCModule.html