Gallery theme - creating
Creating a Gallery Theme Packaged in an Extension
How to Create an Extension
[6/22/2014]
Keywords: LibreOffice, OpenOffice, gallery, extension, custom, theme,
THIS PAGE IS A WORK IN PROGRESS
Overview
This page describes how to create a custom Gallery theme (similar to Visio shapes or stencils, or CAD blocks). The procedure described uses the example of creating a "Machining" theme which includes shapes for various screw types, fasteners, etc. The process described was tested with LibreOffice Version: 4.2.5.2, but should also work with other versions of LibreOffice or OpenOffice.
Gallery images may be image files such as PNG, JPEG, GIF, BMP, TIFF, etc., or they may be vector images (shapes) created in LibreOffice itself. Vector images (in my opinion) offer more power and flexibility, and will be used in this example.
Note: I will use the word "shape" in this document to refer to a vector image created in LibreOffice Draw. For example, a drawing of a screw (which may be composed of more elemental "basic shapes" such as lines, squares, circles, etc.) will be referred to as a "shape."
Procedure
- Download sample extension (see below) sample.zip and extract the files
- Prepare images
- Create theme
- Copy theme files to appropriate directory
- Edit and rename sample.str file
- Create an icon image and copy to appropriate directory
- [optional] Change license file
- Edit pkg-desc files
- Edit description.xml file
Sample Extension
The easiest way to create the extension for a new Gallery theme is to modify a working example. For this purpose I downloaded a simple gallery extension of puzzle shapes and modified the files in it to create a basic sample "template". The result is an extension called sample.oxt. This is saved as sample.zip so that it can be un-zipped and modified (in the final step, the files must be re-zipped, and the .zip extension renamed to .oxt). All further discussion on this page will refer to the use of the sample.zip archive and the files in it.
The sample extension may be downloaded from here: PATH GOES HERE
The contents of sample.zip are as follows:
- [Directory] gallery
- [file] sample.sdg
- [file] sample.sdv
- [file] sample.str
- [file] sample.thm
- [Directory] icon
- [file] icon.png
- [Directory] license
- [file] lgpl-3.0.txt
- [Directory] META-INF
- [file] manifest.xml
- [Directory] pkg-desc
- [file] pkg-description.fr
- [file] pkq-description.txt
- [file] description.xml
- [file] mimetype
- [file] paths.xcu
Step 1 - Prepare Sample Extension files
Download the sample extension from the location above, and extract the files to a working directory. In your working directory, you should see the five directories listed above, and the various files as shown. The files shown in purple will need to be replaced, the files shown in red need to be edited, and the file shown in blue need to be re-created and renamed.
Step 2 - Prepare Images
Broadly speaking, images in a Gallery theme may be of two types:
- Image files such as PNG, JPEG, GIF, BMP, TIFF, etc.
- Vector images created in LibreOffice itself
When creating the vector images (shapes) in LibreOffice, all of the related shapes may be collected in a single Draw document. When creating the shapes, keep in mind how the shapes will ultimately be used. In general, her are some considerations:
- Add glue points to a shape if this will facilitate its use
- Make all related shapes in the same scale, keeping in mind that in actual use Gallery shapes can be re-sized, rotated, and otherwise modified
- In general, keep all line widths at 0.00 (line widths can be changed later when using the shapes)
Step 3 - Create Theme
Once you have all of your shapes or image files created, it is now time to create a custom theme. In LibreOffice, open the Gallery and select the New Theme option; you should see the dialog box below.
The dialog box opens with "New Theme" as the default name, but you may change this to anything you choose; in this case I have changed the name to "Sample".
Note the location of the files for your theme, shown to the right of "Location:" in the dialog box. You will need to locate and copy your theme files from this location later.
Under the "Files" tab in the dialog box, you will see an option for adding image files. Do not use the Add option to add your images to the theme. If you are using actual image files, the Add option only links to the image files, which will be useless for our purposes. If you are using the vector shapes, the Add option is of no use in any case.
To add image files to your theme:
Use the Insert > Image > From file option on the main LibreOffice menu to add your images to a blank Draw document. Then, from the Draw document place the mouse pointer over the image until the pointer changes to a "hand" image, hold down the left mouse button for a second or two until the "hand" changes to a arrow/box image. Continue to hold down the mouse button as you drag and drop the image onto your new theme.
You may now right-click on the image in your theme and select the Title option to give your image a name. This is not required, but may be useful in some cases.
To add vector images to your theme:
In a Draw document, create the shapes you want to place in your Gallery theme. In general, if a shape is made up of multiple components, you will want to "Group" the components to create a single entity. Once a shape has been created, select the shape with the mouse pointer (if the shape has not been "grouped", be sure to select all of the related components). Then, hold down the left mouse button for a second or two until the "hand" changes to a arrow/box image. Continue to hold down the mouse button as you drag and drop the shape onto your new theme.
You may now right-click on the image in your theme and select the Title option to give your shape a name. This is not required, but may be useful in some cases.
Step 4 - Copy Theme Files
First, locate the files related to your theme by looking at the file location found in Step 3 (you can always get this information by opening the Gallery in LibreOffice, right-clicking on your theme name, and selecting "Properties.") You should find three files following this general naming pattern:
- xxxxxx.sdg
- xxxxxx.sdv
- xxxxxx.thm
Where xxxxxx is a system created name (in my case it followed the pattern "new theme.sdg"). If necessay, check the file modification date to make sure you have the right set of files. Copy the three files into the gallery sub-directory in the working directory created in Step 1, and delete the "place holder" files ( sample. sdg, sample.sdv, sample.thm). You may rename your three theme files if you wish, replacing the xxxxxxx portion with any name you desire.
Step 5 - the .str file
The .str file is a localization file with the name of your theme in as many different languages as you prefer. Optionally, you may just delete this file. In my case, I edited the file to replace all of the existing names with names created using Google translate for each of the relevant languages.
As a final step, rename sample.str to match the naming pattern you used in Step 4.
Step 6 - the icon image
The icon image is displayed when the extension is loaded. The icon image must be 42 x 42 pixels. Replace the icon.png file with the image file of your choice; you may give it any name you choose.
Step 7 - [optional] Change License File
The existing license file is for the GNU Lesser General Public License - Version 3. You may replace with any license you desire. However, note that if you plan to publish the extension, you must use one of the licenses approved for use as shown in the Publishing Extensions for LibreOffice reference given below. You may also have more than one license, subject to the previous note.
Step 8 - Edit pkg-desc Files
The pkg-description.txt file is a simple text file containing a description of your theme; this is also the default description that is used if there is not an alternate language file for your particular localization. In the example shown, there is a French description file included (the text for this particular file was created by using Google Translate to translate the English description to French). You may include description files for as many different languages as you wish.
Edit the pkg-description.txt file with a description of your theme.
Delete or edit the pkg-description.fr file with a description of your theme in the relevant language. Add description files for as many other languages as you wish.
Step 9 - Edit description.xml File
References
The following references were consulted in developing this procedure:
- Checklist for Writing Extensions
- Development/Extension Development
- Clarifications and additions relevant to LibreOffice (ass opposed to OpenOffice)
- https://wiki.documentfoundation.org/Development/Extension_Development
- Extensions development
- References for general extensions development
- https://wiki.openoffice.org/wiki/Extensions_development
- FR / Documentation / How Tos / Installation / CreerExtension (Google translation):
- How to create an extension using the example of creating a theme for the Gallery.
- http://www.google.com/translate?hl=en&ie=UTF8&sl=fr&tl=en&u=http%3A%2F%2Fwiki.openoffice.org%2Fwiki%2FFR%2FDocumentation%2FHow_Tos%2FInstallation%2FCreerExtension
- Original web page : https://wiki.openoffice.org/wiki/FR/Documentation/How_Tos/Installation/CreerExtension
- Language codes (for localization)
- http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
- Note that not all of the languages listed in this reference are necessarily supported by LibreOffice.
- LibreOffice Extension Center
- MediaWiki:Collections/Developer's Guide - Extensions
- Publishing Extensions for LibreOffice
- https://wiki.documentfoundation.org/images/1/14/Publishing_extensions.pdf
- Be sure to read this first if you plan to publish your extension on the LibreOffice Extensions site.
- Translations
- https://translate.google.com/
- All language translations for the purposes of localization were done using Google Translate.