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

  1. Download sample extension (see below) sample.zip and extract the files
  2. Prepare images
  3. Create theme
  4. Copy theme files to appropriate directory
  5. Edit and rename sample.str file
  6. Create an icon image and copy to appropriate directory
  7. [optional] Change license file
  8. Edit pkg-desc files
  9. 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:

  1. Image files such as PNG, JPEG, GIF, BMP, TIFF, etc.
  2. 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:

  1. Add glue points to a shape if this will facilitate its use
  2. 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
  3. 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.

New theme dialog box

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: