SFWidgets.Menu service

The Menu service can be used to create and remove menus from the menubar of a LibreOffice document window. Each menu entry can be associated with a script or with a UNO command. This service provides the following capabilities:

note

Menus created with this service are available only for a specified document window. They are not saved into the document or as application settings. Closing and opening the document will restore the default menubar settings.


warning

When OLE objects such as Math formulas or Calc charts are edited from within a document, LibreOffice reconfigures the menubar according to the object. When this happens, the menus created with the Menu service are removed and are not be restored after editing the OLE object.


Service invocation

Before using the Menu service the ScriptForge library needs to be loaded or imported:

note

• Basic makroak erabiltzkeo, ScriptForge liburutegia kargatu behar da honako instrukzioa erabiliz:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python scriptak erabiltzeko, berriz, scriptforge modulu baten inportazioa behar dute:
from scriptforge import CreateScriptService


Basic lengoaian

The Menu service is instantiated by calling the CreateMenu method from the Document service. The code snippet below creates a menu named My Menu in the current document window with two entries Item A and Item B.


    Sub CreateMenu()
        GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
        Dim oDoc as Object, oMenu as Object
        Set oDoc = CreateScriptService("Document")
        Set oMenu = oDoc.CreateMenu("My Menu")
        With oMenu
            .AddItem("Item A", Command := "About")
            .AddItem("Item B", Script := "vnd.sun.star.script:Standard.Module1.ItemB_Listener?language=Basic&location=application")
            .Dispose()
        End With
    End Sub
  
note

After creating the menu, it is recommended to call the Dispose method to free the resources used by the Menu service instance.


In the example above, Item A is associated with the UNO command .uno:About whereas Item B is associated with the script ItemB_Listener defined in Module1 of the Standard library of the My Macros container.

The following example defines ItemB_Listener that will be called when Item B is clicked. This listener simply splits the argument string passed to the Sub and shows them in a message box.


    Sub ItemB_Listener(args As String)
        ' Process the argument string passed to the listener
        Dim sArgs as Object
        sArgs = Split(args, ",")
        MsgBox "Menu name: "   & sArgs(0) & Chr(13) & _
               "Menu item: "   & sArgs(1) & Chr(13) & _
               "Item ID: "     & sArgs(2) & Chr(13) & _
               "Item status: " & sArgs(3)
    End Sub
  

As shown in the example above, menu entries associated with a script receive a comma-separated string argument with the following values:

Python lengoaian

The examples above can be written in Python as follows:


    from scriptforge import CreateScriptService
    
    def create_menu(args=None):
        oDoc = CreateScriptService("Document")
        oMenu = oDoc.CreateMenu("My Menu")
        oMenu.AddItem("Item A", command="About")
        oMenu.AddItem("Item B", script="vnd.sun.star.script:my_macros.py$item_b_listener?language=Python&location=user")
        oMenu.Dispose()
  

    def item_b_listener(args):
        bas = CreateScriptService("Basic")
        s_args = args.split(",")
        msg = f"Menu name: {s_args[0]}\n"
        msg += f"Menu item: {s_args[1]}\n"
        msg += f"Item ID: {s_args[2]}\n"
        msg += f"Item status: {s_args[3]}"
        bas.MsgBox(msg)
  

Properties

Name

Readonly

Type

Description

ShortcutCharacter

No

String

Character used to define the access key of a menu item. The default character is "~".

SubmenuCharacter

No

String

Character or string that defines how menu items are nested. The default character is ">".


Menu and Submenus

To create a menu with submenus, use the character defined in the SubmenuCharacter property while creating the menu entry to define where it will be placed. For instance, consider the following menu/submenu hierarchy.


    ' 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:


    oMenu.AddItem("Item A")
    oMenu.AddItem("Item B>Item B.1")
    oMenu.AddItem("Item B>Item B.2")
    oMenu.AddItem("---")
    oMenu.AddItem("Item C>Item C.1>Item C.1.1")
    oMenu.AddItem("Item C>Item C.1>Item C.1.2")
    oMenu.AddItem("Item C>Item C.2>Item C.2.1")
    oMenu.AddItem("Item C>Item C.2>Item C.2.2")
    oMenu.AddItem("Item C>Item C.2>---")
    oMenu.AddItem("Item C>Item C.2>Item C.2.3")
    oMenu.AddItem("Item C>Item C.2>Item C.2.4")
  
note

The string "---" is used to define line separators in menus or submenus.


Ikonoak erabiltzea

Items in the menu can have icons, which are specified as arguments in the AddCheckBox, AddItem and AddRadioButton methods.

LibreOffice aplikazioak erabilgarri dituen ikono guztiak erabili daitezke, ikono-fitxategiak instalazio-karpetako zein tokitan dauden zehazten bada beren bide-izen erlatiboaren bidez. Ikonoak honako karpetan daude:

INSTALLDIR/share/config

tip

Erabili FileSystem zerbitzuaren InstallFolder propietatea LibreOffice sistemako zein tokitan dagoen instalatuta zehazteko.


Karpeta horrek ikono multzo erabilgarri bakoitzaren irudi-fitxategiak dituzten ZIP fitxategien serieak ditu. ZIP fitxategien barruko irudiak karpetatan daude antolatuta. Ikono bat erabiltzeko, zehaztu ikono-fitxategiak ZIP fitxategiaren barruan duen kokagunearen bide-izena.

Beheko adibidean, "cmd" karpetaren barruan dagoen "sc_newdoc.svg" ikonoa erabiltzen da. Barraren karakterea, "/", bide-izenaren bereizle gisa erabiltzen da, berdin dio sistema eragilea zein den.

Basic lengoaian

      myMenu.AddItem("Item A", Icon := "cmd/sc_newdoc.svg")
    
Python lengoaian

      myMenu.AddItem("Item A", icon="cmd/sc_newdoc.svg")
    
note

Ikono multzo guztiek barneko egitura bera dute. Bistaratuko den ikonoa unean erabiltzen ari den ikono multzoaren araberakoa izango da.


Methods

List of Methods in the Menu Service

AddCheckBox

AddItem

AddRadioButton


AddCheckBox

Inserts a check box in the menu. Returns an integer value that identifies the inserted item.

Sintaxia:

svc.AddCheckBox(menuitem: str, opt name: str, opt status: bool, opt icon: str, opt tooltip: str, opt command: str, opt script: str): int

Parametroak:

menuitem: Defines the text to be displayed in the menu. This argument also defines the hierarchy of the item inside the menu by using the submenu character.

name: String value used to identify the menu item. By default, the last component of the menu hierarchy is used.

status: Defines whether the item is selected when the menu is created (Default = False).

icon: Path and name of the icon to be displayed without the leading path separator. The actual icon shown depends on the icon set being used.

tooltip: Text to be displayed as tooltip.

command: The name of a UNO command without the .uno: prefix. If the command name does not exist, nothing happens.

script: The URI for a Basic or Python script that will be executed when the item is clicked.

note

The arguments command and script are mutually exclusive, hence only one of them can be set for each menu item.


tip

Read Scripting Framework URI Specification to learn more about the URI syntax used in the script argument.


Adibidea:

Basic lengoaian

      ' Menu entry associated with the .uno:Paste command
      oMenu.AddCheckBox("Item A", Status := True, ToolTip := "Paste values", Command := "Paste")
      ' Runs the Basic script Standard.Module1.MyListener stored in the document
      oMenu.AddCheckBox("Item B", Status := False, Script := "vnd.sun.star.script:Standard.Module1.MyListener?language=Basic&location=document")
      ' Runs the Python script MyListener located in file myScripts.py in the user scripts folder
      oMenu.AddCheckBox("Item C", Status := True, Script := "vnd.sun.star.script:myScripts.py$MyListener?language=Python&location=user")
    
Python lengoaian

      oMenu.AddCheckBox("Item A", status=True, tooltip="Paste values", command="Paste")
      oMenu.AddCheckBox("Item B", status=False, script="vnd.sun.star.script:Standard.Module1.MyListener?language=Basic&location=document")
      oMenu.AddCheckBox("Item C", Status=True, Script="vnd.sun.star.script:myScripts.py$MyListener?language=Python&location=user")
    

AddItem

Inserts a label entry in the menu. Returns an integer value that identifies the inserted item.

Sintaxia:

svc.AddItem(menuitem: str, opt name: str, opt icon: str, opt tooltip: str, opt command: str, opt script: str): int

Parametroak:

menuitem: Defines the text to be displayed in the menu. This argument also defines the hierarchy of the item inside the menu by using the submenu character.

name: String value to be returned when the item is clicked. By default, the last component of the menu hierarchy is used.

icon: Path and name of the icon to be displayed without the leading path separator. The actual icon shown depends on the icon set being used.

tooltip: Text to be displayed as tooltip.

command: The name of a UNO command without the .uno: prefix. If the command name does not exist, nothing happens.

script: The URI for a Basic or Python script that will be executed when the item is clicked.

note

The arguments command and script are mutually exclusive, hence only one of them can be set for each menu item.


tip

Read Scripting Framework URI Specification to learn more about the URI syntax used in the script argument.


Adibidea:

Basic lengoaian

      oMenu.AddItem("Item A", Tooltip := "A descriptive message")
    
Python lengoaian

      oMenu.AddItem("Item A", tooltip = "A descriptive message")
    

AddRadioButton

Inserts a radio button entry in the menu. Returns an integer value that identifies the inserted item.

Sintaxia:

svc.AddRadioButton(menuitem: str, opt name: str, opt status: str, opt icon: str, opt tooltip: str, opt command: str, opt script: str): int

Parametroak:

menuitem: Defines the text to be displayed in the menu. This argument also defines the hierarchy of the item inside the menu by using the submenu character.

name: String value to be returned when the item is clicked. By default, the last component of the menu hierarchy is used.

status: Defines whether the item is selected when the menu is created (Default = False).

icon: Path and name of the icon to be displayed without the leading path separator. The actual icon shown depends on the icon set being used.

tooltip: Text to be displayed as tooltip.

command: The name of a UNO command without the .uno: prefix. If the command name does not exist, nothing happens.

script: The URI for a Basic or Python script that will be executed when the item is clicked.

note

The arguments command and script are mutually exclusive, hence only one of them can be set for each menu item.


tip

Read Scripting Framework URI Specification to learn more about the URI syntax used in the script argument.


Adibidea:

Basic lengoaian

      oMenu.AddRadioButton("Item A", Name := "A", Status := True)
    
Python lengoaian

      oMenu.AddRadioButton("Item A", name="A", status=True)
    
warning

Azpimarraren karaktere bat, "_", aurrizki gisa duten ScriptForge Basic errutina edo identifikatzaile guztiak barneko erabilerarako erreserbatuta daude. Ez dira Basic makroetan edo Python scriptetan erabili behar.