Arquitetura do Task Pane Manager

   O aplicativo Task Pane Manager está no diretório base do Visual FoxPro (HOME()) e é chamado Taskpane.app. Como você já viu, o conteúdo específico do painel está armazenado no cache do painel que o Task Pane Manager lê para carregar painéis. O cache pode conter arquivos estáticos necessários para executar o painel e o conteúdo descarregados da Internet, dependendo do tipo de painel e de sua funcionalidade. Por padrão, os caches de painel estão localizados na pasta de trabalho HOME(7)+TaskPane\. Os painéis individuais armazenam arquivos em uma pasta baseada no ID único: HOME(7)+Taskpane\PaneCache\+PaneUniqueID. Por exemplo, por padrão o painel Solution Samples armazena seus arquivos em: \Documents and Settings\UserName\Application Data\Microsoft\Visual FoxPro 8\TaskPane\PaneCache\Microsoft.Solutions\.

Você pode alterar a pasta de trabalho do Task Pane Manager e a pasta do cache do painel a partir de Task Pane Manager Options. O aplicativo Task Pane Manager também lê tabelas localizadas na pasta de trabalho chamada TaskPane.dbf e em PaneContent.dbf que armazena informações sobre os painéis instalados e suas subseções do conteúdo. Ao modificar painéis a partir do formulário Pane Customization, você estará modificando os dados nessas tabelas.

A variável de sistema _TASKPANE especifica o caminho e o nome do arquivo para o Task Pane Manager do Visual FoxPro. Por padrão, esse caminho é o diretório base do Visual FoxPro, e o nome do arquivo é Taskpane.app. No entanto, você pode especificar um caminho e um nome do arquivo para _TASKPANE na guia File Locations na caixa de diálogo Visual FoxPro Options.

Você pode passar um parâmetro de seqüência de caracteres para o task Pane Manager que é o ID único do painel para que seja aberto automaticamente.

    DO (_TASKPANE) WITH "MICROSOFT.FILER"

   Você também pode passar uma opção “-s” para abrir diretamente o formulário Pane Customization.

    DO (_TASKPANE) WITH "-s"

   Além disso, quando o Task Pane Manager estiver aberto no IDE do Visual FoxPro, a variável global _oTaskpane está exposta.

Todo código-fonte para o aplicativo Task Pane Manager está incluído no arquivo Xsource.zip apresentado na pasta \Tools\XSource\ no diretório base do Visual FoxPro.

Gerando Painéis com Conteúdo Rich

O Task Pane Manager pode gerar painéis que apresentam controles do Visual FoxPro a que também se refere como conteúdo rich. Você já viu alguns exemplos disso: o Painel Filer e o Painel Minesweeper. Para criar um painel com controles do Visual FoxPro, você herda de uma classe incluída no Task Pane Manager chamada PaneContainer. Essa classe estará disponível quando o Task Pane Manager estiver sendo executado, de modo que não deverá ser distribuída. Você também pode editar o código do painel diretamente do formulário Pane Customization. Você pode disponibilizar essa classe no tempo de design no IDE do Visual FoxPro se extrair a biblioteca de classe FoxPane.vcx da pasta TaskPane no arquivo Xsource.zip.

A classe base do PaneContainer é a classe Container. Você pode colocar qualquer tipo de controle em um painel. Você não precisará desconsiderar os método na classe PaneContainer, mas há alguns métodos úteis a serem notados.

OnRender(oPane, oContent)—Este método é chamado quando o recipiente estiver reproduzido. Ele passa os objetos Pane e Content. O objeto Pane controla os dados da instância para o painel de tarefas que está sendo reproduzido no Task Pane Manager, enquanto o objeto Content controla uma referência a uma seção de conteúdo específica. Pelo fato de haver apenas uma seção de conteúdo para painéis de conteúdo rich, este método é chamado apenas uma vez na classe PaneContainer. No entanto, os objetos Pane e Content também estão disponíveis ao reproduzir painéis HTML e XML, que podem conter várias subseções de conteúdo.

O objeto Pane apresenta as seguintes propriedades.

Propriedade	Descrição
CacheDir	O nome do diretório de cache do painel do usuário
ContentTile	O nome da seção de conteúdo
UniqueID	UniqueID da seção de conteúdo
TaskPaneID	UniqueID do painel a que a seção de conteúdo pertence
User	Dados do usuário contidos na pasta User na tabela PaneContent

    FUNCTION OnKeyPress(nKeyCode, nShiftAltCtrl)
IF nKeyCode == 27
MESSAGEBOX("Escape Pressed")
RETURN .F.
ELSE
RETURN .T.
ENDIF
ENDFUNC

   Gerando Painéis com Conteúdo HTML/XML

O Task Pane Manager pode gerar painéis que apresentam conteúdo XML e HTML usando o controle ActiveX do Navegador Web do Internet Explorer. Este controle exibe conteúdo HTML ou XML que é criado pelo painel baseado nas configurações do formulário Pane Customization. Há várias maneiras de criação de painéis HTML e XML, mas geralmente esses painéis puxam conteúdo de várias fontes de dados como os arquivos e as tabelas estáticos no computador local, arquivos na Internet/intranet, XML Web services ou dados gerados a partir do código. Ele exibe os dados em um único painel. Você faz isso primeiro criando subseções de conteúdo do painel e definindo o método de obtenção de dados para cada uma delas a partir da guia Data no formulário Pane Customization.

Geralmente esse dado retorna como XML, mas também pode ser HTML ou texto estático. É possível especificar uma transformação, que é uma maneira de alterar o formato dos dados. A transformação é geralmente definida como XSLT e transforma os dados em HTML ou em um formato XML padrão. Em seguida, essas subseções de conteúdo podem ser exibidas na própria área do painel ou juntas, dependendo da transformação final.

O processo de renderização funciona com base nos dados de conteúdo de cada seção que são obtidos na guia Data do formulário Pane customization e transformados conforme especificado na guia Transform Data. Os dados resultantes para todas as subseções estão no formato de dados especificado pela guia Tab no conteúdo raiz e sua transformação final é executada antes da exibição do painel de tarefas. A figura 11 destaca a ordem doa passos envolvidos no processo de renderização para um painel com três subseções de conteúdo.

  
   Figura 11 O processo de renderização para um painel XML ou HTML com três subseções de conteúdo definidas.

Internamente, o Task Pane Manager cria dados mesclados a partir de todos os dados transformados das seções usados para a raiz. O formato dos dados depende de como o conteúdo é especificado na guia Data para o conteúdo raiz. Por padrão, a caixa Source na guia Data é definida para Static Text e está especificado o seguinte:

   < !-- CONTENT -->

   Isso indica que internamente o formato dos dados mesclados é um encadeamento de todo o conteúdo da subseção. Por exemplo, se cada subseção acima produziu os seguintes dados após sua transformação:

   This is my section < b>X

   em que X é o número da seção, você finaliza com os seguintes dados mesclados para o conteúdo raiz:

   This is my section < b>1
This is my section < b>2
This is my section < b>3

   Se especificado, a transformação final da raiz é aplicada a esses dados. A transformação final geralmente opera em dados XML retornado a partir das subseções. Nesse caso, você pode definir os elementos XML da raiz e posicionar a concatenação dos dados da subseção entre essas tags.

   < MyRootData>
< !-- CONTENT -->>
< /MyRootData>

   Por exemplo, se cada subseção produziu os seguintes dados:

    < MySubsectionData>This is my section X< /MySubsectionData>

   em que X é o número da seção, você finaliza com os seguintes dados mesclados para o conteúdo raiz:

   < MyRootData>
< MySubsectionData>This is my section 1< /MySubsectionData>
< MySubsectionData>This is my section 2< /MySubsectionData>
< MySubsectionData>This is my section 3< /MySubsectionData>
< /MyRootData>

   Se especificado, a transformação final da raiz é aplicada a esses dados. Os painéis Community e Environment Manager usam dados mesclados dessa maneira.

Você também pode especificar que o formato dos dados mesclados deve ser expresso como XML e não uma concatenação simples especificando o seguinte como os dados para a raiz:

   < MyRootData>
< !-- XMLCONTENT -->
< /MyRootData>

   Nesse caso, o dado interno mesclado é um fragmento XML localizado entre os elementos raiz XML que você definir. O fragmento XML para uma única subseção possui o seguinte formato:

   < PaneContent id="uniqueid">
< PaneTitle>Content Subsection Title< /PaneTitle>
< HTMLText>
< ![CDATA[This is where your transformed subsection content is placed]]>
< /HTMLText>
< /PaneContent>

   Por exemplo, se cada subseção produziu os seguintes dados após sua transformação:

   This is my section < b>X< /b>

   em que X é o número da seção, você finaliza com os seguintes dados mesclados para o conteúdo raiz:

   < MyRootData>
< PaneContent id="uniqueid1">
< PaneTitle>Section 1< /PaneTitle>
< HTMLText>
< ![CDATA[This is my section < b>1< /b>]]>
< /HTMLText>
< /PaneContent>
< PaneContent id="uniqueid2">
< PaneTitle>Section 2< /PaneTitle>
< HTMLText>
< ![CDATA[This is my section < b>2< /b>]]>
< /HTMLText>
< /PaneContent>
< PaneContent id="uniqueid3">
< PaneTitle>Section 3< /PaneTitle>
< HTMLText>
< ![CDATA[This is my section < b>3< /b>]]>
< /HTMLText>
< /PaneContent>
< /MyRootData>

   Se especificado, a transformação final da raiz é aplicada a esses dados. Essa técnica é usada nos painéis de tarefa Start, Solution Samples e XML Web Services. Nota: não se engane pelo nome do elemento . Os dados aqui não precisam ser HTML, mesmo que geralmente sejam. Esse elemento representa os dados a partir da subseção independente do formato, de modo que você terá flexibilidade total no modo como você definir seu conteúdo. Seus pensamentos devem estar confusos nesse ponto, mas você verá exemplos sobre o uso dos dados mesclados a partir de subseções do conteúdo quando você criar painéis de tarefas HTML e XML.

Usando Manipuladores Internos

Os manipuladores são uma maneira para que o código do Visual FoxPro seja executado a partir de painéis de tarefas HTML e XML. Eles permitem que você especifique o código a ser executado ao clicar em hiperlinks no painel, e esse hiperlink começar por vfps:. Você já viu um exemplo disso ao criar o painel HTML está tico simples que exibia hiperlinks que abriam a janela do navegador. Por exemplo,

   < a href="vfps:linkto?url=http://www.somewhere.com/">Click Me< /a>

   A sintaxe vfps:linkto?url= chama um manipulador interno que abre a janela do navegador para o URL especificado.

Os seguintes manipuladores são criados no Task Pane Manager e podem ser usados diretamente a partir de hiperlink em seu painel de tarefas:

vfps:refresh—Recarrega o painel.

Exemplo: vfps:refresh

vfps:linkto—Abre o navegador para o URL especificado.

Parâmetros: url=cUrl

Exemplo: vfps:linkto?url=http://msdn.microsoft.com/vfoxpro/

vfps:gotopane—Alterna o Task Pane Manager para o painel especificado.

Parâmetros: uniqueid=cPaneUniqueID

Exemplo: vfps:gotopane?uniqueid=Microsoft.start

vfps:help—Exibe Ajuda por tópico ou ID.

Parâmetros: ID=cTopicID, Topic=cTopicName

Exemplos: vfps:help?id=1231106

vfps:help?Topic=_taskpane

vfps:options—Exibe Task Pane Options para um painel.

Parâmetros: uniqueid=cPaneUniqueID

Exemplo: vfps:options?uniqueid=Microsoft.Start

vfps:message—Exibe uma caixa de mensagem informativa.

Parâmetros: msg=cMessage

Exemplo: vfps:message?msg =This is a message

Além disso, se Refresh estiver incluído como um parâmetro, o painel será sempre atualizado ao retornar de uma chamada. Isso é útil quando o resultado do link pode afetar o conteúdo do painel, já que uma atualização pode ser forçada. Refresh pode estar junto com outros parâmetros, como:

   vfps:message?msg=This is a message&refresh

   vfps:message?msg=This is a message&refreshRefresh também pode estar junto com outros parâmetros nos manipuladores personalizados.

Codificando Manipuladores Personalizados

Os manipuladores personalizados são manipuladores que você grava. Eles são definidos na guia Handler Code do formulário Pane Customization. Você pode criar ações personalizadas e manipulá-las a partir do código do Visual FoxPro que você gravou aqui. Por exemplo, para executar o seguinte manipulador, você executa seu próprio código:

   < a href="vfps:Action?Param1=Value1&Param2=Value2">This is my handler< /a>

   Qualquer ação que não possa ser manipulada pelos manipuladores do Task Pane Manager é passado para seu código do manipulador. Quando você especificar o código do manipulador, os seguintes parâmetros são passados:

   LPARAMETERS cAction, oParameters, oBrowser, oContent

   cAction—A ação é o texto após vfps: e antes de qualquer parâmetro. No exemplo anterior, a ação é Action.

oParameters— Esta é uma coleção dos parâmetros que você especificou. Para recuperar um valor, você pode acessar os parâmetros usando a sintaxe Item(x) normal, ou pode chamar a função GetParam com o nome do parâmetro:

   Value1 = oParameters.GetParam("Param1")

   O benefício do uso de GetParam é o fato de ele transferir a chamada em um TRY/CATCH de modo que não haja um erro caso o parâmetro não exista.

oBrowser - Controla a referência do objeto para o objeto Windows no controle do navegador no próprio painel. Você pode usar isso para acessar métodos e propriedades DHTML, se necessário, por exemplo:

   oBrowser.document.all("SearchResults").style.display = "none"

   oContent - Controla uma referência para a definição do conteúdo do painel de modo que você possa recuperar os valores da opção e a pasta de cache do painel especificada no Task Pane Manager Options. Esse é o mesmo objeto passado para o método OnRender para painéis de conteúdo rich.

Os manipuladores personalizados são usados nos painéis de tarefa da Microsoft para abrir arquivos e executar aplicativos. Por exemplo, observe o seguinte código do manipulador para o painel Start:

   LPARAMETERS cAction, oParameters, oBrowser, oContent
LOCAL cFilename

m.cFilename = oParameters.GetParam("filename")
DO CASE
CASE m.cAction == "doapplication"
IF EMPTY(m.cFilename)
m.cFilename = oParameters.GetParam("appname")
ENDIF
IF !EMPTY(m.cFilename)
DO &cFilename
ENDIF
CASE m.cAction == "doform"
IF !EMPTY(m.cFilename)
DO FORM &cFilename
ENDIF
ENDCASE

   Esse código define os manipuladores para duas ações personalizadas: doapplication e doform. O nome do arquivo (e/ou appname) é passado como um parâmetro e usado para executar o aplicativo ou o formulário. Se você precisar dessa funcionalidade em seu painel, você pode apenas copiar esse código para o código do manipulador.

Exibindo Mensagens de Erro

As mensagens de erro são exibidas em painéis HTML e XML como uma região articulada/expansível na parte superior do painel. O Task Pane Manager exibe automaticamente um erro quando há problemas de conectividade com o conteúdo da Internet e XML Web services. Além disso, nos painéis da Microsoft, os erros de configuração são exibidos quando as informações da opção do painel de tarefas necessárias para executar o painel não estiverem especificadas. Por exemplo, o painel Community precisa de uma senha Universal Thread válida e um nome de usuário para acessar as notícias. Se a opção para exibir as notícias estiver selecionada, você deve fornecer sua senha e seu nome de usuário. Se não fizer isso, o painel exibe uma mensagem na área superior do painel (Figura 12).

  
   Figura 12 Mensagens de erro são exibidas se houver problemas de conectividade de Internet ou se as informações de opção do painel de tarefas não estiver especificado.

Você pode exibir erros personalizados quando Source dos dados de conteúdo especificados na guia Data do formulário Pane Customization estiver definido para Script. Nesse caso, o objeto oContent é passado para o código de script, e você pode usar um método chamado LogError para exibir uma mensagem de erro personalizada. Por exemplo, o seguinte código tenta usar uma tabela que não existe e exibe um erro chamado My Error com a mensagem de exceção, e também cria um link chamado Options que abre as opções do painel de tarefas para a seção de conteúdo especificada:

   LPARAMETERS oContent
LOCAL cXML
TRY
USE Sometable IN 0 SHARED
CURSORTOXML(Sometable, cXML)
CATCH TO exc
oContent.LogError("My Error", exc.Message, "Options", ;
"vfps:options?uniqueid=Massi.contentsection1")
cXML = ""
FINALLY
IF USED("Sometable")
USE IN SomeTable
ENDIF
ENDTRY
Return cXML

   Especificando Opções do Painel

As opções do painel para todos os painéis instalados são exibidas em Task Pane Manager Options e acessadas clicando na categoria do painel na exibição de árvore à esquerda. Caso haja opções para o painel ou subseção de conteúdo do painel elas são exibidas à direita.

Você pode especificar os dados de opção para uma seção específica de conteúdo do painel na guia Options do formulário Pane Customization. Para tipos de painel XML e HTML, as opções podem ser especificadas apenas no conteúdo da subseção. Para controles de página da Web e do Visual FoxPro, as opções estão especificadas na seção do conteúdo raiz. Quando você cria uma opção na guia Options, você especifica o nome da opção usado no código, o tipo de controle que você deseja criar e a legenda a ser exibida em Task Pane Options. Você também pode especificar valores comuns de propriedade associados com os controles de opção que você cria, como InputMask, PasswordChar, Width, ou qualquer outra propriedade que deve ser atribuída adicionando novas propriedades para a lista.

Você pode acessar os valores dessas opções no código por meio do método GetOption do objeto Content.

   Value = oContent.GetOption(cOptionName, xDefaultValue)

   Com este método, você pode especificar o valor padrão a ser retornado se a opção estiver vazia. Todos os valores das opções retornam como seqüências de caracteres, a menos que xDefaultValue especifique um tipo de dado diferente. Nesse caso, o valor resultando é convertido para aquele tipo antes de retornar.

Os valores de opção também podem ser acessados nas chamadas do método Web ou URLs na guia Data, como:

   ##optionname##

   em que optionname é o nome da opção do painel. Isso mescla os valores na chamada antes da execução. Por exemplo, na guia Data se você especificar Source como Web Service, você pode usar os valores de opção no campo Method:

   MyWebMethod(##myoption##)

   Se o método Web espera um parâmetro de seqüência de caracteres, coloque-o entre aspas:

   MyWebMethod("##myoption##")

   Agora que você compreendeu a arquitetura básica e o painel que reproduz os recursos do Task Pane Manager, é hora de criar painéis de tarefas avançados. Você estará criando painéis HTML e XML configuráveis que exibem conteúdo a partir de arquivos na Internet, XML Web services e geram dados XML com código do Visual FoxPro.

   Voltar para o menu