Difference between revisions of "Documentation/DevGuide/WritingUNO/AddOns/Toolbars"
m |
|||
Line 10: | Line 10: | ||
{{DISPLAYTITLE:Toolbars}} | {{DISPLAYTITLE:Toolbars}} | ||
− | '''Add-on toolbar, before version 2.0.3 of {{ | + | '''Add-on toolbar, before version 2.0.3 of {{PRODUCTNAME}}''' |
− | :An add-on can also be integrated into the Function Bar of {{ | + | :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 {{PRODUCTNAME}} 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 {{ | + | :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 {{ | + | '''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 {{ | + | |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 {{ | + | |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> | ||
|{{Warn|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 {{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]].}} | ||
− | string. Defines an optional image URL that could address an internal {{ | + | 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 {{ | + | 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 {{ | + | 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. |
− | {{ | + | {{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 {{ | + | 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 {{ | + | |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, | + | 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 {{ | + | 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"> | <source lang="xml"> | ||
<?xml version='1.0' encoding='UTF-8'?> | <?xml version='1.0' encoding='UTF-8'?> |
Revision as of 11:49, 14 December 2020
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 calledToolbarItems
, which is used by OpenOffice.org 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
|
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 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
_parent
_self
_blank
| ||
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:
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 |
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 Apache OpenOffice 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). |