Arquitetura da Caixa de Ferramentas

   O aplicativo da caixa de Ferramentas está presente no diretório base do Visual FoxPro (HOME()) e é chamado de Toolbox.app. Como você já viu, o conteúdo específico do usuário é armazenado no arquivo Toolbox.dbf que a Caixa de Ferramentas lê para carregar ferramentas, categorias e filtros que o usuário criou. O local da tabela de conteúdo da Caixa de Ferramentas é armazenado no arquivo de recurso Foxuser e é padronizado para a pasta HOME(7).

O aplicativo da Caixa de Ferramentas também lê uma tabela chamada Tooltype que armazena informações sobre os tipos de categoria e de ferramenta que a Caixa de Ferramentas suporta. Essa tabela direciona o aplicativo da Caixa de Ferramentas para o carregamento das classes de ferramentas a partir da biblioteca de classe _toolbox.vcx. A biblioteca de classe apresenta a implementação de classe para todos os tipos de ferramenta e categoria suportados. A biblioteca de classe _toolbox.vcx e a tabela Tooltype estão armazenadas em uma pasta \Toolbox no diretório base do Visual FoxPro. Ter a biblioteca de classe e os metadados armazenados fora de Toolbox.app permite a criação e a distribuição de novos tipos de categoria e de ferramenta de que os desenvolvedores precisarão posteriormente. Isso significa que a Caixa de ferramentas pode evoluir tão rápido quanto a comunidade do desenvolvedor que a suporta.

O mecanismo da Caixa de Ferramentas é responsável pelo carregamento do formulário da caixa de Ferramentas, pela leitura das tabelas de dados e pelo carregamento das classes de ferramentas corretas para a Caixa de Ferramentas no tempo de execução. Desse modo você pode alterar a implementação de classes do item de ferramentas sem precisar compilar novamente Toolbox.app. Ao visualizar os exemplos sobre como criar novas ferramentas e categorias, você irá compreender o valor desse recurso.

A variável de sistema da Caixa de Ferramentas _TOOLBOX especifica o caminho e o nome do arquivo para a Caixa de Ferramentas do Visual FoxPro. Por padrão, esse caminho é o diretório base do Visual FoxPro, e o nome do arquivo é Toolbox.app. No entanto, você pode especificar um caminho e um nome do arquivo para _TOOLBOX na guia File Locations na caixa de diálogo Visual FoxPro Options. Você pode passar um parâmetro da seqüência de caracteres que é o ID Único da categoria no aplicativo da Caixa de Ferramentas que especifica a categoria a ser exibida quando ele for aberto.

   DO (_TOOLBOX) WITH "MASSI.COOLCAT" 

   Além disso, quando o formulário da Caixa de Ferramentas estiver aberto no IDE do Visual FoxPro, a variável global _oToolbox está exposta. Como você já viu, isso pode ser prático ao instalar conjuntos de ferramentas de modo que a Caixa de Ferramentas possa ser fechada enquanto o script de instalação é executado. Você também pode alternar ou criar tabelas de conteúdo da Caixa de Ferramentas por programação usando a propriedade _oToolbox.ToolboxTable. Outras propriedades de leitura/gravação são _oToolbox.FilterName e _oToolbox.Category, que podem ser o ID único ou o nome do filtro ou da categoria que você deseja aplicar à Caixa de Ferramentas.

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

Tabela de Conteúdo da caixa de Ferramenta

Conforme mencionado anteriormente, a tabela de conteúdo da Caixa de Ferramentas está armazenada por padrão em sua pasta \Documents and Settings\UserName\Application Data\Microsoft\Visual FoxPro 8\Toolbox\ e é chamada Toolbox.dbf. O nome e o local podem ser alterados na caixa de diálogo Customize Toolbox > Options. Esta tabela armazena todos os itens, filtros, suplementos e as categorias para cada usuário. É importante estar acostumado com a estrutura dessa tabela se você quiser criar comportamentos personalizados ou definir conjuntos de ferramentas especializados. A Tabela 4 descreve a estrutura e a descrição de cada campo na tabela de conteúdo da Caixa de Ferramentas.

Tabela 4 Campos na tabela de conteúdo da Caixa de Ferramentas

Nome do campo	Tipo	Descrição
UniqueID	C(25), Indexed	Um ID único para o registro criado. Deverá estar no formato de CompanyName.Uniqueid Por exemplo: microsoft.textscraps
ShowType	C(1), Indexed	Indica o tipo de item da Caixa de Ferramentas: 'C' = categoria 'F' = categoria de favoritos 'S' = conjunto de filtro 'T' = item da ferramenta 'I' = item do filtro 'A' = comportamento de suplemento 'M' = passa um menu de contexto como o segundo parâmetro que pode ser usado para criar um menu e não solicitar diretamente um comportamento de suplemento.
ToolTypeID	C(25), Indexed	Faz referência ao tipo de ferramenta conforme descrito em ToolType.dbf, e é copiado diretamente do campo ToolType.UniqueID quando o registro é criado.
ToolType	M	O nome amigável do tipo de ferramenta. Isso é copiado diretamente do campo ToolType.ToolType quando o registro é criado.
ParentID	C(25)	Para os itens de ferramenta e filtro (ShowType="T" OR "I"), faz referência a Toolbox.UniqueID da categoria pai ou conjunto de filtro a que eles pertencem. Para suplementos (ShowType="A"), refere-se a Toolbox.UniqueID da opção de menu pai a que o suplemento pretence.
ToolName	C(100)	Nome amigável do item de ferramenta, categoria ou conjunto de filtro.
ImageFile	M	A imagem a ser exibida para um item de ferramenta.
ClassType	C(10)	Designa o tipo de classe do comportamento. Corresponde à propriedade ClassType nas classes de item.
SetID	M	Designa o arquivo da biblioteca de classe para ferramentas de classe (por exemplo, o nome do arquivo VCX ou PRG de um item de ferramenta de classe).
ClassName	M	Nome da classe de item da Caixa de Ferramentas. Se não estiver especificado, será usado um padrão baseado no campo ShowType, por exemplo, _classtool.
ClassLib	M	A biblioteca de classe do item da Caixa de Ferramentas em que a classe está contida. Se não estiver especificado, padronize para _toolbox.vcx.
ToolTip	M	O texto que é exibido em ToolTips e na seção de texto Help da Caixa de Ferramentas.
HelpFile	M	Arquivo de ajuda quando F1 estiver pressionada ou Help estiver selecionada a partir do menu de contexto.
HelpID	N(10,0)	ID do contexto de ajuda quando F1 estiver pressionada ou Help estiver selecionada a partir do menu de contexto.
ToolData	M	Armazena dados específicos para o item. Esta é a informação na caixa de diálogo de propriedades do item e da categoria. Por exemplo, para um item de classe ele especificaria a classe base, o nome do objeto e propriedades adicionais neste formato: <baseclass>Editbox</baseclass> <objectname>Editbox</objectname> <properties></properties>
DisplayOrd	I	Indica a ordem em que o item é exibido.
LockAdd	L	Se o registro for uma categoria ou uma categoria de favoritos, defina como TRUE para evitar que novos itens sejam adicionados.
LockDelete	L	Definido como TRUE para evitar que essa ferramenta ou o item de ferramenta seja excluído.
LockRename	L	Definido como TRUE para evitar que essa ferramenta ou esse item seja renomeado.
Inactive	L	Definido como TRUE para marcar o item como inativo para evitar que ele apareça na Caixa de Ferramentas.
User	M	Definido pelo usuário.
Modified	T	Data/hora modificada recentemente.

   Tabela Tooltype

Além da tabela de conteúdo da Caixa de Ferramentas, também há uma tabela Tooltype localizada na subpasta \Toolbox\ do aplicativo da Caixa de Ferramentas (\Program Files\Microsoft Visual FoxPro 8\Toolbox\). Se essa tabela não for encontrada quando a Caixa de Ferramentas iniciar, será usada uma versão incluída que está compilada em Toolbox.app. A tabela Tooltype armazena informações sobre os tipos de categoria e de ferramenta que a Caixa de Ferramentas suporta. Cada linha representa um tipo de item de categoria ou de ferramenta suportado. Quando os itens de ferramenta e categorias são criados na Caixa de Ferramentas, as informações na tabela do item que está sendo criado são copiadas a partir da linha apropriada nessa tabela na tabela de conteúdo da caixa de Ferramentas. Se você quiser suportar um novo item da Caixa de Ferramentas e/ou tipos de categoria, adicione linhas a essa tabela. A Tabela 5 descreve a estrutura e a descrição de cada campo na tabela Tooltype.

Taela 5 Campos na tabela Tooltype

Nome do campo	Tipo	Descrição
UniqueID	C(25)	Um ID único para o registro criado. As entradas que você criar devem estar no formato de CompanyName.Uniqueid.
ShowType	C(1)	O tipo de item da caixa de ferramentas que este tipo representa: 'C' = categoria 'T' = item da caixa de ferramentas
ToolType	C(50)	O nome amigável do tipo de ferramenta.
ClassName	M	Nome da classe de item da Caixa de Ferramentas. Se não estiver especificado, será usado um padrão baseado no campo ShowType. Por exemplo, _classtool.
ClassLib	M	A biblioteca de classe do item da Caixa de Ferramentas em que a classe está contida. Se não estiver especificado, padronize para _toolbox.vcx.
FileType	M	Uma lista separada por vírgula dos tipos de arquivo aos quais Tooltype se aplica. É usada para determinar o tipo de item a ser criado quando você arrasta um arquivo do Explorer para a Caixa de Ferramentas.
DataValues	M	Não é usado atualmente. Posteriormente, irá representar ToolData padrão ao criar um item desse tipo.
ShowNew	L	Defina como TRUE para exibir na caixa de lista de tipos de itens disponíveis ao adicionar um novo item na Caixa de Ferramentas.
PropSheet	L	Defina como TRUE para exibir a caixa de diálogo de propriedades imediatamente após a criação de um item/uma categoria desse tipo.
DefaultID	C(25)	Para tipos de categoria (ShowType = 'C'), refere-se a ToolType.UniqueID para os itens padrão que essa categoria deveria apresentar.
DisplayOrd	I	Indica a ordem em que o item é exibido.
ToolTip	M	O texto que é exibido em ToolTips e na seção de texto Help da Caixa de Ferramentas.
Inactive	L	Definido como TRUE para marcar o item como inativo para evitar que ele apareça na Caixa de Ferramentas.
User	M	Definido pelo usuário.
Modified	T	Data/hora modificada recentemente.

   Biblioteca de Classe da Caixa de Ferramentas

A biblioteca de classe da Caixa de Ferramentas contém a hierarquia de classe para todos os itens de ferramenta e categorias suportados na Caixa de Ferramentas (Figura 6). Por padrão, cada tipo de ferramenta suportada apresentada na tabela Tooltype corresponde a classes nessa biblioteca. Você herda dessas classes para anular comportamentos ou suportar novos tipos. Você também pode modificar essa biblioteca de classe diretamente para alterar o comportamento das classes suportadas. Se você adicionar um novo comportamento do menu de atalho a um item, é possível fazer isso por meio de um suplemento. É útil, mas não crítico, compreender as características gerais das classes nessa biblioteca ao criar seus suplementos. No entanto, ele será necessário quando você criar seus próprios tipos de ferramenta e categoria. Nesta seção, você verá alguns métodos e propriedades importantes dessas classes. Você estará concentrado nos métodos comuns que você geralmente substitui para suportar suas próprias ferramentas.

  
   Figura 6 A hierarquia de classe das classes do item da Caixa de Ferramentas.

A hierarquia de classe das classes da Caixa de Ferramentas inicia em _root. Todos os itens de ferramenta e as categorias são herdados dessa classe. É onde os métodos comuns que são usados para controlar o comportamento são definidos: OnClick, OnDblClick, OnKeyPress, OnOleSetData, OnStartDrag, e OnCompleteDrag. Esses métodos fornecem o controle de graduação fina do clique e comportamentos arrastar e soltar de todas as ferramentas e categorias na Caixa de Ferramentas. Veja a seguir as propriedades e os métodos mais importantes das classes da Caixa de Ferramentas.

Propriedades e Métodos Comuns

ShowAsLink—Esta propriedade é definida como .T. se o item precisar ser exibido em um estilo de hiperlink quando o mouse focalizá-lo. Isso se aplica somente a itens sem categoria. Por exemplo, as ferramentas de arquivo possuem essa propriedade definida como true.

oEngine—Esta propriedade apresenta uma referência ao mecanismo da caixa de Ferramentas e é usada para chamar métodos do mecanismo. (Você verá exemplos do uso dessa propriedade quando criar suplementos e um tipo de categoria dinâmica.)

OnDblClick()—Este método é chamado quando se clica duas vezes no item. Ele também é executado para um único clique se a opção Double-click para abrir um item na caixa de diálogo Toolbox Options não estiver selecionada.

OnClick()—Este método é chamado quando se clica no item.

OnKeyPress(nKeyCode, nShiftAltCtrl)—Este método é chamado quando o objeto tiver o foco e for pressionada uma tecla.

OnRenderCategory (oToolCollection)—Este método está disponível para classes herdadas da classe _category. Este método é executado quando a categoria estiver aberta para ser preenchida com itens da ferramenta. (Você verá um exemplo do uso deste método ao criar uma categoria dinâmica posteriormente.)

CreateContextMenu (oContextMenu)—Este método é chamado quando o menu de atalho para um item estiver ativado. É onde as opções de menu de contexto específicas da ferramenta são adicionadas. O parâmetro oContextMenu é o objeto do menu que pode ser manipulado usando o método AddMenu, por exemplo:

   LPARAMETERS oContextMenu
LOCAL oMenuBar
oMenuBar = oContextMenu.Addmenu("Run", "oRef.RunItem()")
oMenuBar.Bold = .T.

   O primeiro parâmetro para o método AddMenu do menu de contexto é a legenda de opção de menu. O segundo parâmetro é uma seqüência de caracteres que contém o código a ser executado quando o item de menu estiver selecionado, neste caso, oRef.RunItem(). A variável oRef é avaliada no momento de execução para o objeto da ferramenta quando o usuários escolher a seleção de menu. Neste exemplo, o método RunItem do objeto é chamado. No entanto, também é possível executar um assistente ou outro programa externo. O método AddMenu da classe do menu de contexto retorna um objeto da barra de menu de modo que você possa estabelecer as propriedades conforme mostrado na Tabela 6.

Tabela 6 Propriedades da barra de menu

Propriedade	Tipo	Padrão	Descrição
Caption	String		Legenda a ser exibida na barra de menu
ActionCode	String		Código a ser avaliado e executado quando a barra de menu estiver selecionada
Picture	String		Nome da figura a ser exibida
Checked	Logical	.F.	Indica se a barra de menu está selecionada
IsEnabled	Logical	.T.	Indica se a barra de menu está ativada
Bold	Logical	.F.	Indica se a barra de menu apresenta fontes em negrito

   Essas propriedades também podem ser passadas para o método AddMenu conforme mostrado nos parâmetros na ordem.  

   oContextMenu.Addmenu("Run", "oRef.RunItem()", "Picture.bmp", .F., .T., .T.) 

   OnCreateDataValues()—Alguns itens na Caixa de Ferramentas especificam informações adicionais na folha de propriedades. Por exemplo, os itens de ferramenta baseados no arquivo possuem uma propriedade de nome de arquivo. O método OnCreateDataValues é chamado quando o item tiver uma instância e preencher um conjunto de propriedades para instância particular. Ele faz isso chamando o método AddDataValue que insere uma nova propriedade em oDataCollection. Isso adiciona opções à folha de propriedade do item.  

   LOCAL cName, xDefaultValue, cCaption, cToolTip, lReadOnly, ;
cClassName, cClassLibrary
cName = "filename"
xDefaultValue = ""
cCaption = "File name"
cToolTip = "Specify a file which this tool represents"
lReadOnly = .F.
cClassName = "cfoxfilename"
cClassLibrary = ""
DODEFAULT()
THIS.AddDataValue(cName, xDefaultValue, cCaption, cTooltip, lReadOnly, ;
cClassName, cClassLibrary)

   Tabela 7 Parâmetros do método AddDataValue

Parâmetro	Tipo	Descrição
cName	String	Nome da opção.
xDefaultValue	Any	Valor padrão.
cCaption	String	Legenda a ser exibida na folha de propriedades.
cTooltip	String	Texto ToolTip.
lReadOnly	Logical	Indica que o controle é somente para leitura.
cClassName	String	Nome de classe do controle usado para coletar esse valor de propriedade.
cClassLibrary	String	Biblioteca de classe em que o controle a ser exibido é definido. Se este parâmetro não estiver especificado ou vazio, ele é padronizado para ToolboxCtrls.vcx que é compilado para o aplicativo da Caixa de Ferramentas.

   Os dois últimos parâmetros desse método especificam o nome da classe e o local dos controles a serem exibidos na folha de propriedades. Se não houver uma biblioteca de classe especificada, serão usadas as classes do controle da folha de propriedade contidas na biblioteca de classe ToolboxCtrls.vcx compilada. As classes comuns nesta biblioteca de classe estão listadas na Tabela 8.

Tabela 8 Classes comuns na biblioteca de classe

Classe de controle da folha de propriedades	Classe base
cFoxCheckbox	Checkbox
cFoxEditbox	EditBox
cFoxSpinner	Spinner
cFoxTextBox	TextBox
cFoxDirectory	Container – (Exibe a caixa de diálogo GETDIR())
cFoxFileName	Container – (Exibe a caixa de diálogo GETFILE())

 

   Além disso, o método GetDataValue recupera o valor da propriedade a partir da coleção e SetDataValue estabelece um valor de uma propriedade existente na coleção. Você também pode usar o método EvalText para avaliar o valor da propriedade. Se o valor estiver entre parênteses, EvalText retorna a versão avaliada do valor; caso contrário, o valor é considerado literal. Isso é útil se a propriedade apresentar código de script, funções ou variáveis.

   cFileName = THIS.EvalText(NVL(THIS.GetDataValue("filename"), ''))

   Os conteúdos dessa coleção são salvos como XML no campo ToolData do item na tabela de conteúdo da Caixa de Ferramentas.

Métodos Arrastar e Soltar do OLE

As classes de ferramentas estão baseadas na classe Custom do Visual FoxPro e não suporta por natureza métodos arrastar e soltar do OLE do Visual FoxPro com os quais você está acostumado. Portanto, as classes de ferramentas são chamadas do método arrastar e soltar do OLE encaminhadas a partir dos botões da Caixa de Ferramentas que as contém. Por exemplo, o método OLEStartDrag da classe toolboxbutton chama o método OnStartDrag da classe do item de ferramentas quando a operação arrastar inicia. Para obter mais informações sobre arrastar e soltar do OLE, consulte OLE Drag-and-Drop Overview na documentação do Visual FoxPro.

OnOleSetData(oDataObject, eFormat, oDropTarget, nMouseXPos, nMouseYPos)—Este método estabelece os dados arrastar e soltar. Você pode colocar os dados em oDataObject no formato específico com o método SetData.

   #include "foxpro.h"
LPARAMETERS oDataObject, eFormat, oDropTarget, nMouseXPos, nMouseYPos
LOCAL cText

IF VARTYPE(eFormat) == 'N' AND eFormat == CF_TEXT AND ;
VARTYPE(oDropTarget) <> 'O'

cText = NVL(THIS.GetDataValue("filename"), '')
oDataObject.SetData(cText, eFormat)
ENDIF

   OnStartDrag(oDataObject, nEffect)—Este método é chamado quando uma operação arrastar inicia.

OnCompleteDrag(nEffect, oDropTarget, nMouseXPos, nMouseYPos)—Este método é chamado quando o item da Caixa de Ferramentas cai no alvo.

   LPARAMETERS nEffect, oDropTarget, nMouseXPos, nMouseYPos
LOCAL lcSCXName = ""
THIS.DropOnContainer(oDropTarget, lcSCXName, nMouseXPos, nMouseYPos)
RETURN

   DropOnContainer(oDropTarget, cSCXName, nXPos, nYPos)—As ferramentas herdadas de _baseclasstool possuem este método, que é chamado a partir do método OnCompleteDrag. O código é executado e estabelece os dados apropriados para passarem ao método DropOnObject. O objeto pode, então, ser colocado em áreas de trabalho do designer e em janelas do editor.

   Voltar para o menu