As introduções estão organizadas em páginas que normalmente reflectem uma categoria específica do material introdutório. Por exemplo, uma página O Que Há de Novo pode apresentar novos conceitos ou funcionalidades desde edições anteriores. O conteúdo definido por uma configuração de introdução pode ser referenciado e expandido a partir de outros plug-ins utilizando o ponto de extensão org.eclipse.ui.intro.configExtension.
<!ELEMENT extension (config+)>
<!ATTLIST extension
point CDATA #REQUIRED
id CDATA #IMPLIED
name CDATA #IMPLIED>
<!ELEMENT config (presentation)>
<!ATTLIST config
introId CDATA #REQUIRED
id CDATA #REQUIRED
content CDATA #REQUIRED
configurer CDATA #IMPLIED>
Um elemento config pode ser utilizado para configurar um componente Intro personalizável. Um elemento config tem de especificar um id, um introId e um ficheiro de conteúdo. O ficheiro de conteúdo de introdução é um ficheiro XML que descreve as páginas, os grupos e as ligações que a introdução tem.
org.eclipse.ui.intro.IntroConfigurer
.<!ELEMENT presentation (implementation+ , launchBar?)>
<!ATTLIST presentation
home-page-id CDATA #REQUIRED
standby-page-id CDATA #IMPLIED>
O elemento de apresentação define todas as implementações possíveis de uma apresentação do componente Intro. Pode ter uma ou mais implementações definidas. No arranque apenas será escolhida uma apresentação, com base nos atributos os/ws das implementações. Caso contrário, será escolhida apenas a primeira sem atributos os/ws definidos.
<!ELEMENT implementation (head?)>
<!ATTLIST implementation
kind (swt|html)
style CDATA #IMPLIED
os CDATA #IMPLIED
ws CDATA #IMPLIED>
A apresentação da plataforma tem duas implementações. Uma delas baseia-se no browser SWT, enquanto que a outra se baseia em formulários de UI. O componente Intro personalizável pode ser configurado para escolher uma das duas apresentações com base no OS e Ws actual. O tipo de implementação pode ser swt ou html.
org.eclipse.core.runtime.Platform
).org.eclipse.core.runtime.Platform
).<!ELEMENT launchBar (handle? , shortcut*)>
<!ATTLIST launchBar
location (left|bottom|right|fastview) "fastview"
bg CDATA #IMPLIED
fg CDATA #IMPLIED
computed (true | false) "false">
A barra de lançamento funciona em conjunto com o comando "switchToLaunchBar". Quando executado, o comando irá fechar a introdução e irá criar uma barra de lançamento numa das áreas de ajuste da janela principal. A barra de lançamento irá conter pelo menos um botão que permitirá aos utilizadores regressarem à última página da introdução. Opcionalmente, pode conter botões adicionais definidos utilizando elementos shortcut
. Estes botões podem ser utilizados para ir rapidamente para uma determinada página da introdução. A partir da versão 3.1
left
, bottom
ou right
). Se a opção for definida como fastview
(a predefinição), a barra de lançamento será inicialmente criada onde estiver a barra de visualização rápida. true
, os elementos estáticos
shortcut
definidos em plugin.xml serão ignorados. <!ELEMENT shortcut EMPTY>
<!ATTLIST shortcut
tooltip CDATA #IMPLIED
icon CDATA #REQUIRED
url CDATA #REQUIRED>
Será criado um botão na barra de lançamento da introdução para cada elemento do atalho. O URL definido no atalho será executado quando o botão é premido. A partir da versão 3.1
<!ELEMENT handle EMPTY>
<!ATTLIST handle
close (true | false) "true"
image CDATA #IMPLIED>
Um elemento opcional que controla como é representado o parâmetro identificador da barra de lançamento. A partir da versão 3.1
true
).<!ELEMENT introContent (page+ , group* , extensionContent*)>
O elemento introContent define o corpo do ficheiro de conteúdo de introdução. O ficheiro de conteúdo é composto por páginas, grupos partilhados que podem ser incluídos em várias páginas e extensões para pontos de ancoragem definidos noutras configurações.
<!ELEMENT page (group* | link* | text* | head* | img* | include* | html* | title? | anchor* | contentProvider*)>
<!ATTLIST page
url CDATA #IMPLIED
id CDATA #REQUIRED
style CDATA #IMPLIED
alt-style CDATA #IMPLIED
filteredFrom (swt|html)
content CDATA #IMPLIED
style-id CDATA #IMPLIED
shared-style (true | false)
bgImage CDATA #IMPLIED>
Este elemento é utilizado para descrever uma página a ser apresentada. A
introdução pode apresentar páginas dinâmicas e estáticas.
O conteúdo para as páginas dinâmicas é gerado a partir de subelementos da página, como se descreve a seguir. O estilo ou o estilo alternativo será aplicado dependendo da apresentação. Os estilos podem ser melhorados referindo o ID ou ID de classe.
As páginas estáticas permitem a reutilização dos documentos HTML existentes dentro de uma determinada introdução e podem ser ligadas a partir de qualquer página estática ou dinâmica. As páginas estáticas não estão definidas num elemento page, são simplesmente ficheiros html aos quais outras páginas podem ligar-se.
A página inicial, cujo ID se encontra especificado no elemento presentation do ponto de extensão da configuração da introdução, pode ter um url que indica que é uma página estática. Se não for especificado nenhum URL, então parte-se do princípio que a página inicial é dinâmica. Todas as outras páginas descritas utilizando o elemento page são dinâmicas.
Note também que quando é utilizada a apresentação SWT e é visualizada uma página estática, é lançado um browser externo e a página actual continua visível.
Os subelementos utilizados numa página dinâmica são os seguintes: um subelemento group é utilizado para agrupar conteúdos relacionados e para aplicar o estilo através do conteúdo agrupado. Um subelemento link define uma ligação que pode ser utilizada para efectuar uma ligação a uma página estática ou dinâmica e executar um comando/acção de introdução. Uma ligação é normalmente definida ao nível da página, para navegar entre páginas principais, ao contrário das ligações dentro de uma página. Um subelemento text define conteúdo textual ao nível da página. Um subelemento head só é aplicável à apresentação baseada na Web e permite que se adicione html extra à secção HTML head. Esta capacidade é útil para adicionar scripts Java ou folhas de estilos adicionais. Um subelemento img define conteúdo de imagem ao nível da página. Um subelemento include permite que qualquer elemento, exceptuando uma página, seja novamente utilizado. Um subelemento html só é aplicável à apresentação baseada na Web e permite incorporar ou incluir html no conteúdo da página. A incorporação permite que um ficheiro html completamente definido seja incorporado num objecto HTML object, através da referência ao ficheiro html. A inclusão permite a inserção de um fragmento html directamente a partir de um ficheiro html. Um subelemento title define o título da página. Um subelemento anchor define um ponto onde podem ser efectuadas contribuições externas por parte de um elemento <extensionContent>.
true
(a predefinição), o estilo partilhado é adicionado aos estilo da página. Se for false
, o estilo partilhado definido na configuração do componente Intro não será injectado nos estilos desta página. <!ELEMENT group (group* | link* | text* | img* | include* | html* | anchor* | contentProvider*)>
<!ATTLIST group
id CDATA #REQUIRED
label CDATA #IMPLIED
style-id CDATA #IMPLIED
filteredFrom (swt|html)
computed (true | false) "false"
bgImage CDATA #IMPLIED>
Utilizado para agrupar conteúdos relacionados, conteúdos que devem ter estilos semelhantes aplicados ou conteúdos que serão incluídos conjuntamente noutras páginas.
true
, o elemento descendente do grupo
será facultado pelo configurador de introdução em tempo de execução. Neste caso, é
aconselhável não definir nenhum elemento descendente estaticamente. <!ELEMENT head EMPTY>
<!ATTLIST head
src CDATA #REQUIRED
encoding CDATA #IMPLIED>
HTML directo a incluir numa área de conteúdo HEAD da página. Permite que seja adicionado html adicional à secção HTML HEAD. Isto é útil para adicionar srcipts java ou folhas de estilo adicionais. Se o conteúdo contiver segmentos de substituição do formato $plugin:plugin_id$, estes serão substituídos pelo caminho absoluto para o plug-in com plugin_id. Esta marcação deve ser utilizada apenas com uma implementação do componente Intro baseada em HTML. Será simplesmente ignorado no caso de uma implementação de formulários de UI. Uma página pode ter mais do que um elemento head. Uma implementação pode ter apenas um elemento head (uma vez que é partilhado através de todas as páginas).
<!ELEMENT title EMPTY>
<!ATTLIST title
id CDATA #IMPLIED
style-id CDATA #IMPLIED
filteredFrom (swt|html) >
um fragmento de texto que pode conter opcionalmente códigos de escape HTML. É utilizado apenas como um Título de Página e por isso uma determinada página pode ter um máximo de um elemento title.
<!ELEMENT link (text? , img?)>
<!ATTLIST link
id CDATA #IMPLIED
label CDATA #IMPLIED
url CDATA #REQUIRED
style-id CDATA #IMPLIED
filteredFrom (swt|html) >
Pode estabelecer ligação a um ficheiro HTML estático, a um sítio da Web externo ou pode executar uma acção de URL de introdução.
action name - descrição da acção
action parameter1 - descrição do parâmetro
action parameter2 (optional) - descrição do parâmetro
action parameter3 (optional) = ("true" "false") "false" - descrição do parâmetro, escolha true ou false e "false" é o valor predefinido.
close - fecha o componente intro
não são necessários parâmetros
navigate - navegar pelas páginas de introdução num determinado sentido ou regressar à página inicial
direction = ("backward" "forward" "home") - especifica a direcção da deslocação
openBrowser - abrir o URL num browser externo. A partir da versão 3.1, esta acção depende do suporte de browser da área de trabalho. Isto significa que qualquer conjunto de preferências do utilizador para o browser será aplicado.
url - um URL válido para um sítio da Web externo ou um ficheiro HTML local.
pluginId (optional) - se o URL for relativo, então é relativo a um plug-in. Especifique aqui o ID do plug-in que contém o ficheiro.
openURL - abrir o URL incorporado na página Bem-vindo. No caso da apresentação de SWT, o URL é apresentado num browser externo (semelhante à acção openBrowser anterior). A partir da versão 3.1
url - um URL válido para um sítio da Web externo ou para um ficheiro HTML local.
pluginId (optional) - se o URL é relativo, então especifica o ID do plug-in que contém o ficheiro.
runAction - executa a acção especificada
class - o nome da classe totalmente qualificado da classe que implementa uma das seguintes opções: org.eclipse.ui.intro.config.IIntroAction
, org.eclipse.jface.actino.IAction
ou org.eclipse.ui.IActionDelegate
pluginId - o ID do plug-in que contém a classe.
standby (optional) = ("true" "false") "false" - indica se define ou não a introdução para o modo em espera após a execução da acção.
additional parameters - quaisquer parâmetros adicionais são transferidos para acções que implementam org.eclipse.ui.intro.config.IIntroAction
setStandbyMode - define o estado do componente intro
standby = ("true" "false") - true para colocar o componente Intro no respectivo modo em espera parcialmente visível e false para torná-lo completamente visível.
showHelp - Abrir o sistema de ajuda.
não são necessários parâmetros
showHelpTopic - Abrir o tópico de ajuda.
id - o URL do recurso de ajuda. (Consultar Javadoc para org.eclipse.ui.help.WorkbenchHelp.displayHelpResource)
embed (optional) = ("true" "false") "true" - indica que o recurso da ajuda tem de ser visualizado incorporado como componente das páginas Bem-vindo. A predefinição é false. Este sinalizador será simplesmente ignorado no caso de uma apresentação de SWt. Isto é o equivalente ao comando openURL(), mas para os tópico de Sistema de Ajuda. O URL incorporado ocupa o estado real completo da página actual. A partir da versão 3.1
embedTarget (optional) - o caminho para uma div na página actual Bem-vindo que irá conter o conteúdo do tópico Ajuda. Se especificado, então embed é true por predefinição e o URL incorporado é inserido dentro da div com o caminho especificado. O caminho é relativo à página e não deve começar pelo ID da página. Os descendentes da div são substituídos pelo conteúdo do URL. Apenas pode ser utilizada uma div por página como um destino incorporado. Este sinalizador será simplesmente ignorado no caso de uma apresentação de SWt. Também não é suportado quando se utiliza XHTML como conteúdo de introdução. A partir da versão 3.1
showMessage - Apresenta uma mensagem ao utilizador recorrendo uma caixa de diálogo de informações padrão.
message - a mensagem a mostrar ao utilizador
showStandby - Define o componente intro para modo de espera e mostra standbyContentPart com a entrada estabelecida
partId - o id de standbyContentPart a mostrar
input - os dados de entrada a definir em standbyContentPart
showPage - mostrar a página de introdução com um determinado id
id - o id da página de introdução a mostrar
standby (optional) = ("true" "false") "false" - indica se define ou não a introdução para o modo em espera depois de mostrar a página
Se quaisquer parâmetros transferidos para estas acções tiverem caracteres especiais (isto é, caracteres que não são legais num URL), então devem ser codificados utilizando a codificação de URL UTF-8. Para receber estes parâmetros no respectivo estado descodificado, pode ser utilizado um parâmetro especial decode = ("true" "false") para forçar a descodificação destes parâmetros quando a infra-estrutura do componente Intro os processar.
Por exemplo, o seguinte URL do componente Intro:
http://org.eclipse.ui.intro/showMessage?message=This+is+a+message
irá processar o parâmetro de mensagem como "This+is+a+message"
enquanto que
http://org.eclipse.ui.intro/showMessage?message=This+is+a+message&decode=true
irá processar o parâmetro de mensagem como "This is a message".
<!ELEMENT text EMPTY>
<!ATTLIST text
id CDATA #IMPLIED
style-id CDATA #IMPLIED
filteredFrom (swt|html) >
um fragmento de texto que pode conter opcionalmente códigos de escape HTML. Pode incluir códigos b e li. Também pode conter referências a URLs. Se forem necessários vários parágrafos, então o texto pode ser dividido em várias secções, cada uma começando e terminando pelo código p.
<!ELEMENT img EMPTY>
<!ATTLIST img
id CDATA #REQUIRED
src CDATA #REQUIRED
alt CDATA #IMPLIED
style-id CDATA #IMPLIED
filteredFrom (swt|html) >
Uma imagem que representa o conteúdo da introdução e não uma apresentação (em oposição a imagens de decoração definidas nos estilos).
<!ATTLIST html
id CDATA #REQUIRED
src CDATA #REQUIRED
type (inline|embed)
style-id CDATA #IMPLIED
filteredFrom (swt|html)
encoding CDATA #IMPLIED>
HTML directo a incluir na página quer incorporando todo o documento ou inserindo um fragmento in loco HTML. Deve definir-se uma imagem ou texto de urgência para a representação da apresentação swt alternativa.
Se o conteúdo contiver segmentos de substituição do formato $plugin:plugin_id$,
estes serão substituídos pelo caminho absoluto para o plug-in com plugin_id.
A incorporação permite que um ficheiro html totalmente definido seja incorporado no conteúdo da página dinâmica. É criado um elemento object que referencia o ficheiro html.
A inclusão permite a inserção de um fragmento html directamente a partir de uma página html dinâmica.
<!ELEMENT include EMPTY>
<!ATTLIST include
configId CDATA #IMPLIED
path CDATA #REQUIRED
merge-style (true | false) >
Expande um elemento de destino um de um determinado caminho e atributos configID opcionais. O caminho deve dirigir exclusivamente dentro da configuração especificada. Pode indicar um grupo partilhado definido ao nível da configuração ou qualquer elemento numa página.
true
, será adicionado o estilo que pertence à página que é proprietária do elemento included à lista de estilo da página de inclusão. Se for false
(a predefinição), a página de inclusão é responsável por controlar as propriedades do elemento included. <!ELEMENT anchor EMPTY>
<!ATTLIST anchor
id CDATA #REQUIRED>
uma âncora é o elemento utilizado para declarar extensibilidade. É a localização na configuração que permite contribuições externas. Apenas as âncoras constituem valores destino válidos do atributo path num extensionContent
<!ELEMENT extensionContent (text | group | link | html | include)>
<!ATTLIST extensionContent
style CDATA #IMPLIED
alt-style CDATA #IMPLIED
path CDATA #REQUIRED
content CDATA #IMPLIED
id CDATA #IMPLIED
name CDATA #IMPLIED>
O conteúdo a ser adicionado à âncora destino. Apenas um extensionContent é atribuído a uma determinada configExtension, porque se esta extensão não for processada (se não se localizar a configuração ou o elemento de referência de destino), então as páginas e/ou grupos na extensão deverão ser ignorados.
<!ELEMENT contentProvider (text?)>
<!ATTLIST contentProvider
id CDATA #REQUIRED
pluginId CDATA #IMPLIED
class CDATA #REQUIRED>
Um proxy para um fornecedor de conteúdo de introdução, que permite que uma página de introdução extraia dados de modo dinâmico a partir da várias origens (por exemplo, a web, eclipse, etc.) e fornece o conteúdo no ambiente de execução com base nestes dados dinâmicos. Se a classe IIntroContentProvider for especificada no atributo class, não poderá ser transferida, então, em vez disso, será representado o conteúdo do elemento text. Esta é a versão dinâmica do código de introdução html. Enquanto que o código html permite a incorporação ou introdução de um conteúdo html estático na página de introdução html gerada, o código contentProvider permite a criação dinâmica desse conteúdo no tempo da execução. Outra diferença entre os códigos é que o código html é suportado apenas para a apresentação HTML, enquanto que este código contentProvider é suportado para apresentações HTML e SWT. A partir da 3.0.1
<!ELEMENT hr EMPTY>
<!ATTLIST hr
id CDATA #IMPLIED
style-id CDATA #IMPLIED
filteredFrom (swt|html) >
uma regra horizontal.
<extension id=
"intro"
point=
"org.eclipse.ui.intro.config"
>
<config introId=
"com.org.xyz.intro"
id=
"com.org.xyz.introConfig"
content=
"introContent.xml"
>
<presentation home-page-id=
"root"
title=
"%intro.title"
>
<implementation ws=
"win32"
style=
"css/shared.css"
kind=
"html"
os=
"win32"
>
</implementation>
<implementation style=
"css/shared_swt.properties"
kind=
"swt"
>
</implementation>
</presentation>
</config>
</extension>
Copyright (c) 2004, 2006 IBM Corporation e outros.
Todos os direitos reservados.
Este programa e os materiais que o acompanham estão disponíveis sob os termos
da Eclipse Public License v1.0, que acompanha esta distribuição e estão
disponíveis em
http://www.eclipse.org/legal/epl-v10.html