Criando Comportamentos de Suplemento

   Use suplementos para estender o comportamento de um tipo de item específico ou uma categoria chamando o código personalizado que você colocou na tabela de conteúdo da Caixa de Ferramentas. Você pode facilmente criar suplementos que aparecem nos menus de atalho do item para executar ações personalizadas. Você não precisa saber todos os detalhes da arquitetura da Caixa de Ferramentas para criar um suplemento. Se você pular a discussão da arquitetura, ainda será possível criar comportamentos de suplemento e distribuir seus conjuntos de ferramenta a outros desenvolvedores. No entanto, para criar suplementos realmente úteis, os seguintes exemplos acessam as propriedades e os métodos das classes de ferramenta discutidas anteriormente.

Comportamentos de Suplemento do Item da Ferramenta

A Caixa de Ferramentas ainda suporta muitos tipos de itens e seus comportamentos. Eles são descritos na Tabela 9.

Tabela 9 Itens da Caixa de Ferramentas e seus comportamentos

Tipo de Ferramenta	Comportamento
Class Library-Based Class	Esses itens representam classes que podem ser criadas no designer de classe (Checkbox, Label, TextBox, Form e assim por diante). Essas classes são definidas em um arquivo da biblioteca de classe (.vcx). Você pode arrastar e soltar esse tipo de item para áreas de trabalho do designer de classe e de formulário para liberar uma instância de objeto. Você também pode arrastar e soltar janelas do editor de texto ou de comando para criar chamadas de instanciação do objeto. A subclasse Modify and Create também está disponível no menu de atalho. Selecionar Modify abre o designer de classe para aquela classe. Clique na subclasse Create para abrir a caixa de diálogo New Class do Visual FoxPro (CREATE CLASS). Os itens de classe do formulário também possuem o formulário Create disponível no menu de atalho. A seleção desse item de menu cria um novo formulário (.scx) herdado da classe de formulário.
Program-Based Class	Esses itens representam classes definidas em um arquivo de programa (.prg). A função arrastar e soltar funciona da mesma maneira que os itens de classe baseados na biblioteca de classe. Modify também está disponível no menu de atalho. Clique em Modify para abrir o arquivo de programa que apresenta a definição de classe.
Base Class	Esses itens representam as classes base do Visual FoxPro contidas na categoria Base Classes do Visual FoxPro. A função arrastar e soltar funciona da mesma maneira que os itens de classe baseados na biblioteca de classe. Clique na subclasse Create no menu de atalho para abrir a caixa de diálogo New Class do Visual FoxPro (CREATE CLASS).
Class Library File	Esses itens representam os próprios arquivos da biblioteca de classe (.vcx). Arraste e solte um item da biblioteca de classe para um editor um uma janela de comando para colocar o caminho e o nome do arquivo como texto. Clique no item para abrir a caixa de diálogo Modify Class, que é o mesmo se você clicar em Modify no menu de atalho.
Program	Esses itens representam arquivos de programas (.prg, .mpr). Arraste e solte um item de programa para um editor um uma janela de comando para colocar o caminho e o nome do arquivo como texto. Clique no item para abrir a caixa de diálogo Modify Class, que é o mesmo se você clicar em Modify no menu de atalho. Você também pode clicar em Run no menu de atalho para executar o programa.
Form	Esses itens representam arquivos do formulário do Visual FoxPro (.scx). Arraste e solte um item de formulário para um editor um uma janela de comando para colocar o caminho e o nome do arquivo como texto. Clique no item para abrir o formulário no designer de formulários, que é o mesmo se você clicar em Modify no menu de atalho. Você também pode clicar em Run no menu de atalho para executar o formulário.
Menu	Esses itens representam arquivos de menu do Visual FoxPro (.mnx). Arraste e solte um item de menu para um editor um uma janela de comando para colocar o caminho e o nome do arquivo como texto. Clique no item para abrir o menu designer de menu, que é o mesmo se você clicar em Modify no menu de atalho.
Report	Esses itens representam arquivos do relatório do Visual FoxPro (.frx). Arraste e solte um item de relatório para um editor um uma janela de comando para colocar o caminho e o nome do arquivo como texto. Clique no item para abrir o relatório no designer de relatórios, que é o mesmo se você clicar em Modify no menu de atalho. Você também pode clicar em Run no menu de atalho para executar o relatório.
Project	Esses itens representam arquivos do projeto do Visual FoxPro (.pjx). Arraste e solte um item de projeto para um editor um uma janela de comando para colocar o caminho e o nome do arquivo como texto. Clique no item para abrir o gerente de projetos, que é o mesmo se você clicar em Modify no menu de atalho.
Database	Esses itens representam arquivos do banco de dados do Visual FoxPro (.dbc). Arraste e solte um item de banco de dados para uma janela de editor ou de comando para colocar OPEN DATABASE com o caminho e o nome do arquivo. Você também pode clicar em Open no menu de atalho para abrir o banco de dados. Clique no item para abrir o banco de dados no designer de banco de dados, que é o mesmo se você clicar em Modify no menu de atalho.
Table	Esses itens representam arquivos de tabela do Visual FoxPro (.dbc). Arraste e solte um item de banco de dados para um editor um uma janela de comando para colocar o comando USE com o caminho e o nome do arquivo. Você também pode clicar em Open no menu de atalho para abrir a tabela. Arraste e solte um item da tabela para o designer de formulário, ou clique duas vezes quando um designer estiver aberto para adicionar uma grade ao formulário e a tabela ao ambiente de dados. Por padrão, ele solta o Visual FoxPro base class Grid. Você pode alterar essa classe na guia Field Mappings da caixa de diálogo Options do Visual FoxPro acessada a partir do menu Tools. Selecione o tipo Multiple e clique em Modify para alterar a classe e as informações da biblioteca de classe. Se nenhum designer estiver aberto, clique duas vezes no item da tabela para navegar na tabela, que é igual a clicar em Browse no menu de atalho. Você também pode selecionar Modify no menu de atalho para abrir o designer da tabela.
Image	Esses itens representam arquivos de imagem (.ani, .bmp, .cur, .dib, .gif, .ico, .jpg). Arraste e solte um item de imagem para os designers ou clique duas vezes quando um designer estiver aberto para colocar um controle de imagem com o conjunto de propriedades da figura. Você também pode clicar em Open no menu de atalho para abrir a imagem em seu editor de imagem padrão. Isso é controlado pelo sistema operacional do Windows (ShellExecute) e tem o mesmo efeito de clicar duas vezes no arquivo de imagem no Windows Explorer.
Application	Esses itens representam arquivos do aplicativo do Visual FoxPro (.app). Arraste e solte um item do aplicativo para um editor um uma janela de comando para colocar o caminho e o nome do arquivo como texto. Clique no item para executar o aplicativo, que é o mesmo se você clicar em Run no menu de atalho.
Text File	Esses itens representam arquivos de texto (.txt). Arraste e solte um item do arquivo de texto para um editor um uma janela de comando para colocar o caminho e o nome do arquivo como texto. Clique no item para abrir o arquivo no editor, que é o mesmo se você clicar em Modify no menu de atalho.
Text Scrap	Esses itens são partes de texto. Selecione e arraste o texto para a categoria Text Scrap para criar um item de recorte de texto. Arraste e solte um recorte de texto para uma janela do editor, do comando ou outro aplicativo do Windows que suporta texto arrastar e soltar. Os itens de recorte de texto também podem ser avaliados usando o recurso de mesclagem de texto do Visual FoxPro de modo que o código possa ser incorporado no recorte de texto e seja avaliado quando liberado. Arraste e solte um recorte de texto para os designers para soltar relatórios de etiqueta para cada linha no recorte. Clique em Copy to clipboard no menu de atalho para copiar os conteúdos do recorte de texto para a Área de Transferência do Windows.
ActiveX Control	Esses itens representam os conteúdos carregados do ActiveX. Você pode arrastar e soltar esse tipo de item para áreas de trabalho do designer de classe e de formulário para liberar um OleControl. Você também pode arrastar e soltar uma janela do editor de texto ou de comando para criar chamadas de instanciação do objeto. Você também pode clicar em Open no pesquisador de objeto no menu de atalho para pesquisar as propriedades, os eventos e os métodos do componente.
XML Web Service	Esses itens representam XML Web services registrados. Você pode arrastar e soltar esse tipo de item para áreas de trabalho do designer de classe e de formulário para liberar uma classe Proxy do Web service que você especificar. Por padrão, é usada a classe WSHandler na biblioteca de classe de fundação _ws3client FoxPro. Arraste e solte itens do XML Web service para janelas do editor de texto para que o código proxy seja gerado automaticamente.
Other Windows File Types	Os itens baseados em qualquer tipo de arquivo do Windows que não possui comportamentos específicos suportados pela Caixa de Ferramentas ainda serão mantidos nas categorias como um tipo de arquivo genérico. Clique nesses itens ou em Open no menu de atalho para iniciar o editor padrão do Windows. Isso é controlado pelo sistema operacional do Windows (ShellExecute) e tem o mesmo efeito de clicar duas vezes no arquivo no Windows Explorer.

   Você pode criar seus próprios comportamentos de suplemento para esses comportamentos adicionando registros à tabela de conteúdo da Caixa de Ferramentas. Esses suplementos aparecem como opções do menu de atalho para um tipo de item. Por exemplo, você pode criar um suplemento para ferramentas do projeto que criam o projeto em um aplicativo. Você quer que uma opção Build Application apareça no menu de atalho para todos os itens de ferramenta do projeto na Caixa de Ferramentas. Quando selecionada, ela cria o projeto em um arquivo .app. Esses tipos de suplemento simples apenas solicitam a entrada de registros na tabela de conteúdo.

Abra sua tabela da Caixa de Ferramentas e adicione um novo registro digitando as informações na Tabela 10.

Tabela 10 Informações necessárias para adicionar uma opção do menu de atalho Build Application

Campo	Valor
UNIQUEID	MASSI.BUILDAPP
SHOWTYPE	A
TOOLTYPEID	PJX
TOOLNAME	Build Application
INACTIVE	.F.

   O A no campo Showtype e PJX em TooltypeID indicam à Caixa de ferramentas que este é um suplemento para itens de ferramenta do projeto. Desse modo, uma opção Build Application aparece no menu de atalho para todas as ferramentas do projeto na Caixa de Ferramentas. Especifique o código a ser executado no campo Tooldata.

   LPARAMETERS oToolItem
LOCAL cFilename
cFilename = oToolItem.GetDataValue("filename")
IF FILE(cFilename)
BUILD APP (FORCEEXT(cFilename, "APP")) FROM (cFilename)
ENDIF

   Os suplementos recebem um parâmetro, oToolItem, que é uma referência ao objeto da ferramenta em que o suplemento foi ativado. Você pode acessar qualquer propriedade ou método do item e executar qualquer código. Esse suplemento específico cria o projeto em um arquivo .app. Feche a tabela da Caixa de Ferramentas e reinicie a Caixa de Ferramentas. Build Application aparece no menu de atalho para todas as ferramentas do projeto na Caixa de Ferramentas (Figura 7).

  
   Figura 7 Suplementos podem aparecer como opções do menu de atalho para um tipo de item específico.

Outro exemplo é criar uma seleção de menu para os itens de classe chamada Rename Class. Quando selecionado, esse comando abre uma caixa de diálogo em que você digite um novo nome para a classe na biblioteca de classe. Ele, então, renomeia a classe na biblioteca de classe e atualiza a categoria. Abra sua tabela da Caixa de Ferramentas e adicione um novo registro digitando as informações na Tabela 11.

Tabela 11 Informações necessárias para adicionar uma opção do menu de atalho Rename Class

Campo	Valor
UNIQUEID	MASSI.RENAMECLASS
SHOWTYPE	A
TOOLTYPEID	CLASS
TOOLNAME	Rename Class
INACTIVE	.F.

   
   Em seguida, especifique o seguinte código no campo Tooldata:

   LPARAMETERS oToolItem
LOCAL cClassName, cClassLib, cNewName, oException

cClassName = oToolItem.GetDataValue("classname")
cClassLib = oToolItem.GetDataValue("classlib")
cNewName = INPUTBOX("New name for class:", "Rename Class", cClassName)
cNewName = LOWER(ALLTRIM(cNewName))

IF !EMPTY(cNewName) AND !(cNewName == LOWER(cClassName))
TRY
RENAME CLASS (cClassName) OF (cClassLib) TO (cNewName)

oToolItem.oEngine.RefreshCategory()

CATCH TO oException
MessageBox(oException.Message)
ENDTRY
ENDIF

   Esse suplemento específico renomeia a classe na biblioteca de classe e então atualiza a categoria que remove o item da ferramenta com a referência de classe antiga. O suplemento cria um novo item com uma referência ao novo nome. Chame o método RefreshCategory() no mecanismo da Caixa de Ferramentas para completar isso.

Suponhamos que você queira adicionar outro comportamento chamado Copy Class. Quando selecionado, ele abre uma caixa de diálogo em que você digita o nome para a nova classe. Ela cria uma cópia da classe do item da ferramenta na biblioteca de classe e atualiza a categoria para exibir essa nova classe como um item de ferramenta. Abra sua tabela da Caixa de Ferramentas, adicione um novo registro e digite as informações na Tabela 12.

Tabela 12 Informações necessárias para adicionar uma opção do menu de atalho Copy Class

Campo	Valor
UNIQUEID	MASSI.COPYCLASS
SHOWTYPE	A
TOOLTYPEID	CLASS
TOOLNAME	Copy Class
INACTIVE	.F.

   Especifique o código a ser executado no campo Tooldata:  

   LPARAMETERS oToolItem
LOCAL cClassName, cClassLib, cTempClassLib, oException, cNewName

cClassName= oToolItem.GetDataValue("classname")
cClassLib = oToolItem.GetDataValue("classlib")
cNewName = INPUTBOX("Name for the new class:", "Copy Class", cClassName)
cNewName = LOWER(ALLTRIM(cNewName))

IF !EMPTY(cNewName) AND !(cNewName == LOWER(cClassName))
cTempClassLib = ADDBS(SYS(2023)) + SYS(2015)

TRY
ADD CLASS (cClassName) OF (cClassLib) TO (cTempClassLib)
RENAME CLASS (cClassName) OF (cTempClassLib) TO (cNewName)
ADD CLASS (cNewName) OF (cTempClassLib) TO (cClassLib)

oToolItem.oEngine.RefreshCategory()
CATCH TO oException
MessageBox(oException.Message)
ENDTRY

ERASE (cTempClassLib + ".vcx")
ERASE (cTempClassLib + ".vct")
ENDIF 

   Feche a tabela da Caixa de Ferramentas e reinicie a Caixa de Ferramentas. Copy Class e Rename Class aparecem no menu de atalho para todas as ferramentas de classe.

Em vez de organizar o menu de atalho principal com esses dois suplementos, você pode especificar a exibição de Rename Class e Copy Class no submenu separado chamado Class Stuff. Você pode fazer isso facilmente adicionando as informações na Tabela 13 em um novo registro na tabela de conteúdo da Caixa de Ferramentas.

Tabela 13 Informações necessárias para adicionar um submenu Class Stuff

Campo	Valor
UNIQUEID	MASSI.CLASSSTUFF
SHOWTYPE	A
TOOLTYPEID	CLASS
TOOLNAME	Class Stuff
INACTIVE	.F.

   Atualize os campos ParentID dos suplementos Rename Class e Copy Class com o UniqueID do suplemento Class Stuff — MASSI.CLASSSTUFF. Não é necessário um código no registro do suplemento Class Stuff porque a Caixa de Ferramentas automaticamente gera a hierarquia dos menus de suplemento observando os campos ParentID (Figura 8).

      Figura 8 Você pode facilmente fazer com que os suplementos apareçam em seus próprios submenus.

Como você pode ver, os suplementos podem ser muito poderosos e fáceis de serem criados. Até agora você criou opções de menu estático. E se você quiser criar um submenu de suplemento dinamicamente? Por exemplo, suponha que você queira adicionar um comportamento a uma ferramenta da biblioteca de classe (.vcx) que exibe os membros da classe em um menu de suplemento. Quando selecionado, esse menu de suplemento irá abrir o Class Designer. Dependendo da ferramenta da biblioteca de classe que você selecionar, esse menu pode apresentar itens diferentes. Felizmente, a Caixa de Ferramentas fornece a flexibilidade para criar manualmente o menu de suplemento se você digitar M no campo Showtype ao definir um registro de suplemento (Tabela 14).

Tabela 14 O M em ShowType permite que você especifique os conteúdos do menu em seu código.

Campo	Valor
UNIQUEID	MASSI.MODICLASSLIB
SHOWTYPE	M
TOOLTYPEID	VCX
TOOLNAME	Modify Class
INACTIVE	.F.

   No campo ToolData para esse suplemento de menu, o seguinte código cria os itens de menu dinamicamente baseados nos nomes de classe contidos em VCX. Ele faz isso manipulando o objeto oContextMenu manualmente com o método AddMenu. Quando o nome de classe estiver selecionado no menu, ele chama outro suplemento que está marcado como inativo com o UniqueID = MASSI.MODICLASS. É o InvokeAddIn do método do item de ferramenta que chama o suplemento MODICLASS e abre Class Designer para a classe selecionada.

   *-- Add-Ins with ShowType == 'M' pass the context menu as the 2nd
*-- parameter which we can use to create a dynamic menu.
LPARAMETERS oToolItem, oContextMenu
LOCAL cFilename
LOCAL nClassCnt
LOCAL i
LOCAL ARRAY aClassList[1]

cFilename = oToolItem.GetDataValue("filename")
nClassCnt = AVCXCLASSES(aClassList, cFileName)

*-- Create the menu items dynamically
FOR i = 1 TO nClassCnt
*-- When the menu item is selected we will invoke the MODICLASS add-in
*-- record passing it the name of the class that was selected.
oContextMenu.AddMenu(aClassList[i, 1], ;
[oRef.InvokeAddIn("MASSI.MODICLASS", "] + aClassList[i, 1] + [")])
ENDFOR

   Agora, para estabelecer o suplemento MODICLASS, adicione um registro usando as informações na Tabela 15.

Tabela 15 Informações necessárias para estabelecer o suplemento MODICLASS

Campo	Valor
UNIQUEID	MASSI.MODICLASS
SHOWTYPE	A
TOOLTYPEID	VCX
INACTIVE	.T.

   Note que o campo Inactive está definido para true (.T.) para evitar que esse suplemento esteja visível na Caixa de Ferramentas. No entanto, isso não evita que ele seja chamado manualmente usando o método InvokeAddin.

O código ToolData é o seguinte:

   LPARAMETERS oToolItem, cClassName
LOCAL cFilename
cFilename = oToolItem.GetDataValue("filename")
MODIFY CLASS (cClassName) OF (cFilename) NOWAIT

   Feche a tabela e reinicie a Caixa de Ferramentas. Ao ativar o menu de atalho para um item da biblioteca de classe, você verá que a opção do menu do suplemento Modify Class e seu submenu apresentam os nomes de classe apresentados na biblioteca (Figura 9). Selecionar um fará com que ele seja aberto em Class Designer.

   Figura 9 Você pode criar menus de suplementos que são criados dinamicamente no tempo de execução.

Comportamentos de Suplemento da Categoria

Os comportamentos de suplemento também podem ser criados para tipos de categoria. A tabela 16 lista os tipos de categoria suportados e seus comportamentos.

Tabela 16 Tipos de categoria suportados e seus comportamentos de suplemento

Tipo de Categoria	Comportamento
Categoria geral	Esta categoria não apresenta um comportamento em especial. É uma categoria estática que pode apresentar qualquer tipo de item de ferramenta.
Categoria da pasta dinâmica	Você especifica uma pasta do sistema de arquivo e tipos de arquivo para que esta categoria leia. Quando a categoria estiver aberta, os conteúdos do conjunto de ferramentas são preenchidos dinamicamente baseados nos conteúdos da pasta do sistema de arquivo. Open está disponível no menu de atalho que abre o Windows Explorer na pasta do sistema.
Recortes de texto	Este tipo de categoria cria ferramentas de recorte quando o texto estiver selecionado e colocado nesta categoria. Você também pode selecionar texto a partir de outros aplicativos do Windows, como o Word, e arrastá-lo para a categoria de Recorte de texto para criar um recorte automaticamente. Arraste o recorte de texto da Caixa de Ferramentas para janelas do editor ou outros aplicativos do Windows para colocar o texto. Os recortes de texto também podem ser criados usando os recurso de mesclagem de texto do Visual FoxPro de modo que o código possa ser incorporado no recorte e avaliado quando liberado.
Controles ActiveX registrados	Este tipo exibe todos os controles ActiveX carregados no Visual FoxPro. Você carrega esses controles no menu Tools do Visual FoxPro. Clique em Options e selecione a guia Controls.
XML Web services	Este tipo de categoria exibe todos os XML Web services registrados do Visual FoxPro especificados no IntelliSense manager do Visual FoxPro.

   Você também pode criar seus próprios comportamentos de suplemento da categoria para esses comportamentos adicionando registros à tabela de conteúdo da Caixa de Ferramentas. A única diferença é o fato de o campo ToolTypeID indicar um tipo de categoria e não um tipo de ferramenta. Por exemplo, para criar um suplemento para categorias gerais, digite CATEGORY, GENERAL para o valor de ToolTypeID.

Outros Suplementos

Você também pode criar suplementos que estão disponíveis em todos os menus de atalho para todos os itens na Caixa de Ferramentas. Isso é útil caso você tenha um comportamento que não é específico para qualquer tipo de ferramenta. Por exemplo, você deseja adicionar Dock no menu de atalho para todos os itens na Caixa de Ferramentas. Quando selecionado, este comando encaixa a Caixa de Ferramentas no lado direito da área de trabalho. Você pode fazer isso adicionando um registro com as informações na Tabela 17.

Tabela 17 Informações para adicionar a opção do menu de atalho Dock

Campo	Valor
UNIQUEID	MASSI.DOCK
SHOWTYPE	A
TOOLTYPEID
TOOLNAME	Dock
INACTIVE	.F.

   Note que o campo ToolTypeID está vazio. Isso pede para a Caixa de Ferramentas colocar este suplemento em todos os menus de contexto. O código no campo ToolData é auto-explicativo:

   LPARAMETERS oToolItem
*-- 0 = dock left, 1 = dock right
_oToolbox.DockIt(1)

   Em vez de criar suplementos que aparecem nos menus de atalho, você pode criar um comportamento que é executado quando a Caixa de Ferramentas, uma categoria ou um item é aberto. Nesse caso, o campo ClassType para o suplemento é definido para ONLOAD. Por exemplo, insira um novo registro de suplemento com as informações na Tabela 18.

Tabela 18 Informações para adicionar o comportamento ONLOAD

Campo	Valor
UNIQUEID	MASSI.ONLOADEXAMPLE
SHOWTYPE	A
CLASSTYPE	ONLOAD
INACTIVE	.F.

   No campo ToolData, é exibida uma caixa de mensagem simples para esse exemplo. No entanto, note que é passada para o código uma referência para o mecanismo da caixa de ferramentas:

   LPARAMETERS oToolboxEngine
Messagebox("Reading Toolbox Table " + oToolboxEngine.ToolboxTable) 

   Quando você reiniciar a Caixa de Ferramentas, esse código é executado antes de o formulário da Caixa de Ferramentas ser exibido.

Lembre-se de que todos esses registros de suplemento podem ser distribuídos do mesmo modo descrito anteriormente. Desse modo, você pode facilmente trocar comportamentos de suplemento com outros desenvolvedores como parte de seus conjuntos de ferramentas. Se você estiver criando ferramentas de terceiros, siga as mesmas convenções de nome de outras ferramentas no conjunto incluindo o nome do fornecedor ou do produto com os IDs únicos de modo que eles possam ser incluídos nos processos de instalação e atualização.

   Voltar para o menu