SFWidgets.PopupMenu serviço
O serviço PopupMenu pode ser utilizado para criar menus pop-up que podem ser associados a eventos ou executados por scripts. Este serviço oferece as seguintes funcionalidades:
-
Criação de menus pop-up com entradas personalizadas, caixas de seleção e botões de opção.
-
Decoração dos itens do menu com ícones e dicas de informação.
Chamada de serviço
Antes de utilizar o serviço PopupMenu, é necessário carregar ou importar a biblioteca ScriptForge:
• As macros básicas requerem o carregamento da biblioteca ScriptForge através da seguinte instrução:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Os scripts Python requerem a importação do módulo scriptforge:
from scriptforge import CreateScriptService
O serviço PopupMenu pode ser instanciado de várias formas. O exemplo abaixo cria um menu pop-up sem o associar a um evento do rato ou da aplicação.
Sub ShowPopup
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
Dim myPopup As Object
Set myPopup = CreateScriptService("SFWidgets.PopupMenu", , 300, 300)
myPopup.AddItem("Item ~A")
myPopup.AddItem("Item ~B")
vResponse = myPopup.Execute()
MsgBox("ID do item selecionado: " & vResponse)
myPopup.Dispose()
End Sub
Ao executar o Sub definido acima, será criado um menu pop-up com duas entradas na posição X=300 e Y=300 no ecrã.
O prefixo SFWidgets pode ser omitido ao invocar o serviço PopupMenu.
O exemplo seguinte define um Sub que pode ser associado a um evento do rato:
Sub MyPopupClick(Optional poMouseEvent as Object)
Dim myPopup As Object
Set myPopup = CreateScriptService("PopupMenu", poMouseEvent)
' Preencher o menu pop-up com itens
Dim vResponse As Variant
vResponse = myPopup.Execute(False)
' Fazer algo com base na vResponse
' ...
myPopup.Dispose()
End Sub
Utilize o método Dispose para libertar recursos após a execução do menu pop-up.
Também é possível associar um menu pop-up a eventos desencadeados por aplicações LibreOffice, controlos de formulário e de caixa de diálogo. Eventos como «Botão do rato premido» e «Botão do rato solto» são frequentemente associados a menus pop-up.
Sub MyPopupClick(Optional poEvent as Object)
Dim myPopup As Object
Set myPopup = CreateScriptService("PopupMenu", poEvent)
' ...
End Sub
Os exemplos acima podem ser escritos em Python da seguinte forma:
from scriptforge import CreateScriptService
def show_popup(args=None):
my_popup = CreateScriptService("SFWidgets.PopupMenu", None, 300, 300)
bas = CreateScriptService("Basic")
my_popup.AddItem("Item ~A")
my_popup.AddItem("Item ~B")
response = my_popup.Execute()
bas.MsgBox(f"Selected item ID: {response}")
my_popup.Dispose()
def my_popup_click(poEvent=None):
my_popup = CreateScriptService("SFWidgets.PopupMenu", poEvent)
# Preencher o menu pop-up com itens
response = my_popup.Execute()
# Fazer algo com base na resposta
my_popup.Dispose()
Características
|
Nome |
Apenas leitura |
Tipo |
Descrição |
|---|---|---|---|
|
ShortcutCharacter |
Não |
String |
Caractere utilizado para definir a tecla de acesso de um item de menu. O caractere predefinido é ~. |
|
SubmenuCharacter |
Não |
String |
Caractere ou cadeia de caracteres que define a forma como os itens do menu são aninhados. O caractere predefinido é >. |
Menu e submenus
Para criar um menu pop-up com submenus, utilize o carácter definido na propriedade SubmenuCharacter ao criar a entrada do menu, para definir onde esta será colocada. Por exemplo, considere a seguinte hierarquia de menus e submenus.
' Item A
' Item B > Item B.1
' Item B.2
' ------ (line separator)
' Item C > Item C.1 > Item C.1.1
' Item C.1.2
' Item C > Item C.2 > Item C.2.1
' Item C.2.2
' ------ (line separator)
' Item C.2.3
' Item C.2.4
The code below uses the default submenu character > to create the menu/submenu hierarchy defined above:
myPopup.AddItem("Item A")
myPopup.AddItem("Item B>Item B.1")
myPopup.AddItem("Item B>Item B.2")
myPopup.AddItem("---")
myPopup.AddItem("Item C>Item C.1>Item C.1.1")
myPopup.AddItem("Item C>Item C.1>Item C.1.2")
myPopup.AddItem("Item C>Item C.2>Item C.2.1")
myPopup.AddItem("Item C>Item C.2>Item C.2.2")
myPopup.AddItem("Item C>Item C.2>---")
myPopup.AddItem("Item C>Item C.2>Item C.2.3")
myPopup.AddItem("Item C>Item C.2>Item C.2.4")
O código abaixo utiliza o caractere padrão do submenu > para criar a hierarquia de menus e submenus definida acima:
Utilização de ícones
Os itens do menu podem ter ícones, que são especificados como argumentos nos métodos AddCheckBox, AddItem e AddRadioButton.
Todos os ícones disponíveis no LibreOffice podem ser utilizados indicando o seu caminho relativo à pasta onde se encontram os ficheiros de ícones na pasta de instalação. Os ícones encontram-se na seguinte pasta:
INSTALLDIR/share/config
Utilize a propriedade InstallFolder do serviço FileSystem para determinar onde o LibreOffice está instalado no seu sistema.
Esta pasta contém uma série de ficheiros ZIP com os ficheiros de imagem de cada conjunto de ícones disponível. As imagens contidas nestes ficheiros ZIP estão organizadas em pastas. Para utilizar um ícone, especifique o ficheiro do ícone indicando o caminho para a sua localização dentro do ficheiro ZIP.
O exemplo abaixo utiliza o ícone «sc_newdoc.svg», que se encontra na pasta «cmd». O carácter barra «/» é utilizado como separador de caminho, independentemente do sistema operativo.
myMenu.AddItem("Item A", Icon := "cmd/sc_newdoc.svg")
myMenu.AddItem("Item A", icon="cmd/sc_newdoc.svg")
Todos os conjuntos de ícones têm a mesma estrutura interna. O ícone efetivamente apresentado depende do conjunto de ícones que está a ser utilizado nesse momento.
Métodos
|
List of Methods in the PopupMenu Service |
||
|---|---|---|
AddCheckBox
Lista de métodos do serviço PopupMenu
svc.AddCheckBox(menuitem: str, opt name: str, opt status: bool = False, opt icon: str, opt tooltip: str): int
item do menu: Define o texto a apresentar no menu. Este argumento também define a hierarquia do item dentro do menu, utilizando o carácter de submenu.
nome: Valor de cadeia de caracteres a ser devolvido quando se clicar no item. Por predefinição, é utilizado o último componente da hierarquia do menu.
estado: Define se o item está selecionado quando o menu é criado (Predefinição = False).
ícone: Caminho e nome do ícone a apresentar, sem o separador de caminho inicial. O ícone efetivamente apresentado depende do conjunto de ícones que estiver a ser utilizado.
dica: Texto a apresentar como dica.
myPopup.AddCheckBox("Option A", Status := True)
my_popup.AddCheckBox("Option A", status=True)
AddItem
Inserir uma opção no menu de contexto. Devolve um valor inteiro que identifica a opção inserida.
svc.AddItem(menuitem: str, opt name: str, opt icon: str, opt tooltip: str): int
item do menu: Define o texto a apresentar no menu. Este argumento também define a hierarquia do item dentro do menu, utilizando o carácter de submenu.
nome: Valor de cadeia de caracteres a ser devolvido quando se clicar no item. Por predefinição, é utilizado o último componente da hierarquia do menu.
ícone: Caminho e nome do ícone a apresentar, sem o separador de caminho inicial. O ícone efetivamente apresentado depende do conjunto de ícones que estiver a ser utilizado.
dica: Texto a apresentar como dica.
myPopup.AddItem("Item A", Tooltip := "Uma mensagem descritiva")
my_popup.AddItem("Item A", tooltip = "Uma mensagem descritiva")
AddRadioButton
Inserir uma opção de botão de rádio no menu pop-up. Devolve um valor inteiro que identifica o item inserido.
svc.AddRadioButton(menuitem: str, opt name: str, opt status: bool = False, opt icon: str, opt tooltip: str): int
item do menu: Define o texto a apresentar no menu. Este argumento também define a hierarquia do item dentro do menu, utilizando o carácter de submenu.
nome: Valor de cadeia de caracteres a ser devolvido quando se clicar no item. Por predefinição, é utilizado o último componente da hierarquia do menu.
estado: Define se o item está selecionado quando o menu é criado (Predefinição = False).
ícone: Caminho e nome do ícone a apresentar, sem o separador de caminho inicial. O ícone efetivamente apresentado depende do conjunto de ícones que estiver a ser utilizado.
dica: Texto a apresentar como dica.
myPopup.AddRadioButton("Option A", Name := "A", Status := True)
my_popup.AddRadioButton("Option A", name="A", status=True)
Execute
Exibe o menu pop-up e aguarda uma ação do utilizador. Devolve o item em que o utilizador clicou.
Se o utilizador clicar fora do menu pop-up ou premir a tecla Esc, nenhum item será selecionado. Nesses casos, o valor devolvido depende do parâmetro returnid. Se returnid = True e nenhum item for selecionado, é devolvido o valor 0 (zero). Caso contrário, é devolvida uma cadeia de caracteres vazia "" .
svc.Execute(opt returnid: bool = True): any
returnid: Se for True, é devolvido o ID do item selecionado. Se for False, o método devolve o nome do item (padrão = True).
Nos exemplos abaixo, é criado um menu pop-up e é devolvido o nome do item, uma vez que o argumento returnid está definido como False.
myPopup.AddItem("Item A", Name := "A")
myPopup.AddItem("Item B", Name := "B")
Dim vResponse as Variant
vResponse = myPopup.Execute(False)
my_popup.AddItem("Item A", name="A")
my_popup.AddItem("Item B", name="B")
response = my_popup.Execute(False)
Todas as rotinas ou identificadores do ScriptForge Basic que tenham o caractere de sublinhado «_» como prefixo estão reservados para uso interno. Não se destinam a ser utilizados em macros do Basic ou em scripts Python.
