Difference between revisions of "Documentation/DevGuide/WritingUNO/AddOns/Toolbars"

From Apache OpenOffice Wiki
Jump to: navigation, search
(Context : c.s.s.chart.ChartDocument obsolete, replaced by c.s.s.chart2.ChartDocument)
m
 
(3 intermediate revisions by 2 users not shown)
Line 10: Line 10:
 
{{DISPLAYTITLE:Toolbars}}
 
{{DISPLAYTITLE:Toolbars}}
  
−
'''Add-on toolbar, before version 2.0.3 of {{OOo}}'''
+
'''Add-on toolbar, before version 2.0.3 of {{PRODUCTNAME}}'''
  
−
:An add-on can also be integrated into the Function Bar of {{PRODUCTNAME}}. The ''org.openoffice.Office.Addons'' configuration branch has a set called <code>OfficeToolBar</code> where you can add toolbar items for an add-on. The toolbar structure uses an embedded set called <code>ToolbarItems</code>, which is used by {{PRODUCTNAME}} to group toolbar items from different add-ons. {{PRODUCTNAME}} automatically inserts a separator between different add-ons toolbar items.  
+
:An add-on can also be integrated into the Function Bar of {{AOo}}. The ''org.openoffice.Office.Addons'' configuration branch has a set called <code>OfficeToolBar</code> where you can add toolbar items for an add-on. The toolbar structure uses an embedded set called <code>ToolbarItems</code>, which is used by {{AOo}} to group toolbar items from different add-ons. {{AOo}} automatically inserts a separator between different add-ons toolbar items.  
−
:The space of the Function Bar is limited, so only the most used/important functions should be added to the <tt>OfficeToolBar</tt> set. Otherwise {{PRODUCTNAME}} will add scroll-up/down buttons at the end of the Function Bar and the user has to scroll the toolbar to have access to all toolbar buttons.
+
:The space of the Function Bar is limited, so only the most used/important functions should be added to the <tt>OfficeToolBar</tt> set. Otherwise {{AOo}} will add scroll-up/down buttons at the end of the Function Bar and the user has to scroll the toolbar to have access to all toolbar buttons.
  
−
'''Extension toolbar, since version 2.0.3 of {{OOo}}'''
+
'''Extension toolbar, since version 2.0.3 of {{PRODUCTNAME}}'''
  
 
:Each extension may have its own toolbar. The toolbar may have a specific title.
 
:Each extension may have its own toolbar. The toolbar may have a specific title.
Line 25: Line 25:
 
|-
 
|-
 
|<code>oor:name</code>  
 
|<code>oor:name</code>  
−
|string. The name of the configuration node. The name must begin with an ASCII letter character. It must be unique within the OfficeMenuBar set. Therefore it is mandatory to use a schema such as <code>org.openoffice.<developer>.<product>.<addon name></code> or <code>com.<company>.<product>.<addon name></code> to avoid name conflicts. Please keep in mind that your configuration file will be merged into the {{PRODUCTNAME}} configuration branch. You do not know what add-ons, or how many add-ons, are currently installed.  
+
|string. The name of the configuration node. The name must begin with an ASCII letter character. It must be unique within the OfficeMenuBar set. Therefore it is mandatory to use a schema such as <code>org.openoffice.<developer>.<product>.<addon name></code> or <code>com.<company>.<product>.<addon name></code> to avoid name conflicts. Please keep in mind that your configuration file will be merged into the {{AOo}} configuration branch. You do not know what add-ons, or how many add-ons, are currently installed.  
 
|}
 
|}
  
Line 41: Line 41:
 
|-
 
|-
 
|<code>Title</code>  
 
|<code>Title</code>  
−
|string. Contains the title of a top-level menu item. This property supports localization: The default string, which is used when {{PRODUCTNAME}} cannot find a string definition for its current language, uses the value element without an attribute. You define a string for a certain language with the <code>xml:lang</code> attribute. Assign the language/locale to the attribute, for example <code><nowiki><value xml:lang="en-US">string</value></nowiki></code>.  
+
|string. Contains the title of a top-level menu item. This property supports localization: The default string, which is used when {{AOo}} cannot find a string definition for its current language, uses the value element without an attribute. You define a string for a certain language with the <code>xml:lang</code> attribute. Assign the language/locale to the attribute, for example <code><nowiki><value xml:lang="en-US">string</value></nowiki></code>.  
 
|-
 
|-
 
|<code>ImageIdentifier</code>  
 
|<code>ImageIdentifier</code>  
−
|{{Documentation/Caution|Since version 2.0.3 of {{OOo}} ImageIdentifier property has become obsolete. Images should now be in png format, which supports transparency. Png images can only be declared in an [[Documentation/DevGuide/WritingUNO/AddOns/Images_for_Toolbars_and_Menus|Images configuration branch]].}}
+
|{{Warn|Since version 2.0.3 of {{PRODUCTNAME}} ImageIdentifier property has become obsolete. Images should now be in png format, which supports transparency. Png images can only be declared in an [[Documentation/DevGuide/WritingUNO/AddOns/Images_for_Toolbars_and_Menus|Images configuration branch]].}}
  
−
string. Defines an optional image URL that could address an internal {{PRODUCTNAME}} image or an external user-defined image. The syntax of an internal image URL is: ''private:image/<number>'' where number specifies the image.  
+
string. Defines an optional image URL that could address an internal {{AOo}} image or an external user-defined image. The syntax of an internal image URL is: ''private:image/<number>'' where number specifies the image.  
  
−
External user-defined images are supported using the placeholder variable ''%origin%'', representing the folder where the component will be installed. The term %origin% will be exchanged with another placeholder, which is substituted during runtime by {{PRODUCTNAME}} to the real installation folder. Since {{PRODUCTNAME}} supports two different configuration folders ( ''user'' and ''share'' ) this mechanism is necessary to determine the installation folder of a component.  
+
External user-defined images are supported using the placeholder variable ''%origin%'', representing the folder where the component will be installed. The term %origin% will be exchanged with another placeholder, which is substituted during runtime by {{AOo}} to the real installation folder. Since {{AOo}} supports two different configuration folders ( ''user'' and ''share'' ) this mechanism is necessary to determine the installation folder of a component.  
  
 
For example the URL ''%origin%/image'' will be substituted with something like  
 
For example the URL ''%origin%/image'' will be substituted with something like  
Line 57: Line 57:
 
The placeholder ''vnd.sun.star.expand:$UNO_USER_PACKAGES_CACHE'' is then substituted during runtime with the real path.
 
The placeholder ''vnd.sun.star.expand:$UNO_USER_PACKAGES_CACHE'' is then substituted during runtime with the real path.
  
−
Since the <code>ImageIdentifier</code> property can only hold one URL but {{PRODUCTNAME}} supports four different images (small/large image, and both as high contrast), a naming schema is used to address them. {{PRODUCTNAME}} adds ''_16.bmp'' and ''_26.bmp'' to the provided URL to address the small and large image. ''_16h.bmp'' and ''_26h.bmp'' is added to address the high contrast images. If the high contrast images are omitted, the normal images are used instead.
+
Since the <code>ImageIdentifier</code> property can only hold one URL but {{AOo}} supports four different images (small/large image, and both as high contrast), a naming schema is used to address them. {{AOo}} adds ''_16.bmp'' and ''_26.bmp'' to the provided URL to address the small and large image. ''_16h.bmp'' and ''_26h.bmp'' is added to address the high contrast images. If the high contrast images are omitted, the normal images are used instead.
  
−
{{PRODUCTNAME}} supports bitmaps with 1, 4, 8, 16, 24 bit color depth. Magenta (color value red=0xffff, green=0x0000, blue=0xffff) is used as the transparent color, which means that the background color of the display is used instead of the image pixel color when the image is drawn.
+
{{AOo}} supports bitmaps with 1, 4, 8, 16, 24 bit color depth. Magenta (color value red=0xffff, green=0x0000, blue=0xffff) is used as the transparent color, which means that the background color of the display is used instead of the image pixel color when the image is drawn.
  
−
For optimal results, the size of small images should be 16x16 pixel, and for big images 26x26 pixel. Other image sizes are scaled automatically by {{PRODUCTNAME}}.If no high contrast image is provided, {{PRODUCTNAME}} uses the normal image for high contrast environments. Images that are not valid are ignored.This property has a higher priority than the Images set when {{PRODUCTNAME}} searches for images.   
+
For optimal results, the size of small images should be 16x16 pixel, and for big images 26x26 pixel. Other image sizes are scaled automatically by {{AOo}}.If no high contrast image is provided, {{AOo}} uses the normal image for high contrast environments. Images that are not valid are ignored.This property has a higher priority than the Images set when {{AOo}} searches for images.   
 
|-
 
|-
 
|<code>Target</code>  
 
|<code>Target</code>  
Line 79: Line 79:
 
|-
 
|-
 
|<code>Context</code>  
 
|<code>Context</code>  
−
|string. A list of service names, separated by a comma, that specifies in which context the add-on menu should be visible. An empty context means that the function should be visible in all contexts. The {{PRODUCTNAME}} application modules use the following services names:
+
|string. A list of service names, separated by a comma, that specifies in which context the add-on menu should be visible. An empty context means that the function should be visible in all contexts. The {{AOo}} application modules use the following services names:
  
 
* Writer: com.sun.star.text.TextDocument
 
* Writer: com.sun.star.text.TextDocument
Line 89: Line 89:
 
* Bibliography: com.sun.star.frame.Bibliography
 
* Bibliography: com.sun.star.frame.Bibliography
  
−
The context service name for add-ons is determined by the service name of the model that is bound to the frame, which is associated with an UI element (toolbar, menu bar, ...). Thus the service name of the Writer model is <code>com.sun.star.text.TextDocument</code>. That means, the context name is bound to the model of an application module. If you implement a new desktop component that has a model, it is possible to use its service name as a context for add-on UI items.  
+
The context service name for add-ons is determined by the service name of the model that is bound to the frame, which is associated with an UI element (toolbar, menu bar, …). Thus the service name of the Writer model is <code>com.sun.star.text.TextDocument</code>. That means, the context name is bound to the model of an application module. If you implement a new desktop component that has a model, it is possible to use its service name as a context for add-on UI items.  
 
|}
 
|}
  
−
The following example defines one toolbar button for the function called <code>org.openoffice.Office.addon.example:Function1</code>. The toolbar button is only visible when using the {{PRODUCTNAME}} Writer module.  
+
The following example defines one toolbar button for the function called <code>org.openoffice.Office.addon.example:Function1</code>. The toolbar button is only visible when using the {{AOo}} Writer module.  
−
<source lang="xml">
+
<syntaxhighlight lang="xml">
 
   <?xml version='1.0' encoding='UTF-8'?>
 
   <?xml version='1.0' encoding='UTF-8'?>
 
   <oor:component-data xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" oor:name="Addons" oor:package="org.openoffice.Office">
 
   <oor:component-data xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" oor:name="Addons" oor:package="org.openoffice.Office">
Line 119: Line 119:
 
       </node>
 
       </node>
 
   </oor:component-data>
 
   </oor:component-data>
−
</source>
+
</syntaxhighlight>
  
 
=== Toolbar title ===
 
=== Toolbar title ===
−
Since version 2.0.3 of {{OOo}} an extension toolbar may have a specific title.
+
Since version 2.0.3 of OpenOffice.org an extension toolbar may have a specific title.
  
 
The framework based layout manager uses a modified resource URL schema to address add-on toolbars:
 
The framework based layout manager uses a modified resource URL schema to address add-on toolbars:
Line 133: Line 133:
  
 
An extension can define the toolbar title with ''<Module>WindowState.xcu'' files. The title of the toolbar must be set for each module where the toolbar will appear. One such file is necessary for each module. Continuing the example, the toolbar title for Writer module will be specified in a ''WriterWindowState.xcu'' file:
 
An extension can define the toolbar title with ''<Module>WindowState.xcu'' files. The title of the toolbar must be set for each module where the toolbar will appear. One such file is necessary for each module. Continuing the example, the toolbar title for Writer module will be specified in a ''WriterWindowState.xcu'' file:
−
<source lang="xml">
+
<syntaxhighlight lang="xml">
 
<?xml version="1.0" encoding="UTF-8"?>
 
<?xml version="1.0" encoding="UTF-8"?>
 
<oor:component-data xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" oor:name="WriterWindowState" oor:package="org.openoffice.Office.UI">
 
<oor:component-data xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" oor:name="WriterWindowState" oor:package="org.openoffice.Office.UI">
Line 146: Line 146:
 
   </node>
 
   </node>
 
</oor:component-data>
 
</oor:component-data>
−
</source>
+
</syntaxhighlight>
 
The <tt>UIName</tt> property supports localization.
 
The <tt>UIName</tt> property supports localization.
  

Latest revision as of 15:49, 15 February 2021



Add-on toolbar, before version 2.0.3 of OpenOffice.org

An add-on can also be integrated into the Function Bar of Apache OpenOffice. The org.openoffice.Office.Addons configuration branch has a set called OfficeToolBar where you can add toolbar items for an add-on. The toolbar structure uses an embedded set called ToolbarItems, which is used by Apache OpenOffice to group toolbar items from different add-ons. Apache OpenOffice automatically inserts a separator between different add-ons toolbar items.
The space of the Function Bar is limited, so only the most used/important functions should be added to the OfficeToolBar set. Otherwise Apache OpenOffice will add scroll-up/down buttons at the end of the Function Bar and the user has to scroll the toolbar to have access to all toolbar buttons.

Extension toolbar, since version 2.0.3 of OpenOffice.org

Each extension may have its own toolbar. The toolbar may have a specific title.


Properties of template ToolBarItems
oor:name string. The name of the configuration node. The name must begin with an ASCII letter character. It must be unique within the OfficeMenuBar set. Therefore it is mandatory to use a schema such as org.openoffice.<developer>.<product>.<addon name> or com.<company>.<product>.<addon name> to avoid name conflicts. Please keep in mind that your configuration file will be merged into the Apache OpenOffice configuration branch. You do not know what add-ons, or how many add-ons, are currently installed.

The ToolBarItems set is a container for the ToolBarItem nodes.

Properties of template ToolBarItem
oor:name string. The name of the configuration node. It must be unique inside your own ToolBarItems set. A configuration set cannot guarantee the order of its entries, therefore use a schema such as string + number, for example "m1", as the name is used to sort the entries. Please be aware that the name must begin with an ASCII letter character.
URL string. Specifies the command URL that should be dispatched when the user activates the menu entry. To define a separator you can use the special command URL "private:separator". A separator ignores all other properties.
Title string. Contains the title of a top-level menu item. This property supports localization: The default string, which is used when Apache OpenOffice cannot find a string definition for its current language, uses the value element without an attribute. You define a string for a certain language with the xml:lang attribute. Assign the language/locale to the attribute, for example <value xml:lang="en-US">string</value>.
ImageIdentifier
Documentation caution.png Since version 2.0.3 of OpenOffice.org ImageIdentifier property has become obsolete. Images should now be in png format, which supports transparency. Png images can only be declared in an Images configuration branch.

string. Defines an optional image URL that could address an internal Apache OpenOffice image or an external user-defined image. The syntax of an internal image URL is: private:image/<number> where number specifies the image.

External user-defined images are supported using the placeholder variable %origin%, representing the folder where the component will be installed. The term %origin% will be exchanged with another placeholder, which is substituted during runtime by Apache OpenOffice to the real installation folder. Since Apache OpenOffice supports two different configuration folders ( user and share ) this mechanism is necessary to determine the installation folder of a component.

For example the URL %origin%/image will be substituted with something like 

 vnd.sun.star.expand:$UNO_USER_PACKAGES_CACHE/uno_packages/component.zip.1051610942/image 
 .

The placeholder vnd.sun.star.expand:$UNO_USER_PACKAGES_CACHE is then substituted during runtime with the real path.

Since the ImageIdentifier property can only hold one URL but Apache OpenOffice supports four different images (small/large image, and both as high contrast), a naming schema is used to address them. Apache OpenOffice adds _16.bmp and _26.bmp to the provided URL to address the small and large image. _16h.bmp and _26h.bmp is added to address the high contrast images. If the high contrast images are omitted, the normal images are used instead.

Apache OpenOffice supports bitmaps with 1, 4, 8, 16, 24 bit color depth. Magenta (color value red=0xffff, green=0x0000, blue=0xffff) is used as the transparent color, which means that the background color of the display is used instead of the image pixel color when the image is drawn.

For optimal results, the size of small images should be 16x16 pixel, and for big images 26x26 pixel. Other image sizes are scaled automatically by Apache OpenOffice.If no high contrast image is provided, Apache OpenOffice uses the normal image for high contrast environments. Images that are not valid are ignored.This property has a higher priority than the Images set when Apache OpenOffice searches for images.

Target string. Specifies the target frame for the command URL. Normally an add-on will use one of the predefined target names:

_top

Returns the top frame of the called frame, which is the first frame where isTop() returns true when traversing up the hierarchy.

_parent

Returns the next frame above in the frame hierarchy.

_self

Returns the frame itself, same as an empty target frame name. This means you are searching for a frame you already have, but it is legal to do so.

_blank

Creates a new top-level frame whose parent is the desktop frame.
Context string. A list of service names, separated by a comma, that specifies in which context the add-on menu should be visible. An empty context means that the function should be visible in all contexts. The Apache OpenOffice application modules use the following services names:
  • Writer: com.sun.star.text.TextDocument
  • Spreadsheet: com.sun.star.sheet.SpreadsheetDocument
  • Presentation: com.sun.star.presentation.PresentationDocument
  • Draw: com.sun.star.drawing.DrawingDocument
  • Formula:com.sun.star.formula.FormulaProperties
  • Chart: com.sun.star.chart2.ChartDocument
  • Bibliography: com.sun.star.frame.Bibliography

The context service name for add-ons is determined by the service name of the model that is bound to the frame, which is associated with an UI element (toolbar, menu bar, …). Thus the service name of the Writer model is com.sun.star.text.TextDocument. That means, the context name is bound to the model of an application module. If you implement a new desktop component that has a model, it is possible to use its service name as a context for add-on UI items.

The following example defines one toolbar button for the function called org.openoffice.Office.addon.example:Function1. The toolbar button is only visible when using the Apache OpenOffice Writer module. 

  <?xml version='1.0' encoding='UTF-8'?>
  <oor:component-data xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" oor:name="Addons" oor:package="org.openoffice.Office">
      <node oor:name="AddonUI">
          <node oor:name="OfficeToolBar">
              <node oor:name="org.openoffice.Office.addon.example" oor:op="replace">
                  <node oor:name=”m1”>
                      <prop oor:name="URL" oor:type="xs:string">
                          <value>org.openoffice.Office.addon.example:Function1</value>
                      </prop>
                      <prop oor:name="Title" oor:type="xs:string">
                          <value/>
                          <value xml:lang=”en-US”>Function 1</value>
                          <value xml:lang="de">Funktion 1</value>
                      </prop>
                      <prop oor:name="Target" oor:type="xs:string">
                          <value>_self</value>
                      </prop>
                      <prop oor:name="Context" oor:type="xs:string">
                          <value>com.sun.star.text.TextDocument</value>
                      </prop>
                  </node>
              </node>
          </node>
      </node>
  </oor:component-data>

Toolbar title

Since version 2.0.3 of OpenOffice.org an extension toolbar may have a specific title.

The framework based layout manager uses a modified resource URL schema to address add-on toolbars:

private:resource/toolbar/addon_<name of the toolbar set node>

As the new schema uses a unique name which is known at installation time, the toolbar name can be associated to this resource URL.

In the above example of Addons.xcu file defining a toolbar, the name of the toolbar set node is org.openoffice.Office.addon.example. Therefore the resource URL will be

private:resource/toolbar/addon_org.openoffice.Office.addon.example

An extension can define the toolbar title with <Module>WindowState.xcu files. The title of the toolbar must be set for each module where the toolbar will appear. One such file is necessary for each module. Continuing the example, the toolbar title for Writer module will be specified in a WriterWindowState.xcu file: 

<?xml version="1.0" encoding="UTF-8"?>
<oor:component-data xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" oor:name="WriterWindowState" oor:package="org.openoffice.Office.UI">
  <node oor:name="UIElements">
    <node oor:name="States">
      <node oor:name="private:resource/toolbar/addon_org.openoffice.Office.addon.example" oor:op="replace">
        <prop oor:name="UIName" oor:type="xs:string">
          <value xml:lang="en-US">My pretty bar</value>
        </prop>
      </node>
    </node>
  </node>
</oor:component-data>

The UIName property supports localization.

Each <Module>WindowState.xcu file must be declared as a configuration data file in the manifest.xml file.

Content on this page is licensed under the Public Documentation License (PDL).
Retrieved from "https://wiki.openoffice.org/w/index.php?title=Documentation/DevGuide/WritingUNO/AddOns/Toolbars&oldid=247982"
Personal tools
In other languages