Home

Welcome to your wiki!

This is the default page, edit it as you see fit. To add a page simply reference it within brackets, e.g.: [SamplePage].

The wiki uses Markdown syntax.

[Martin Doucha]

Adding support for other comicbook file formats

• Adding support for other comicbook file formats
  • Your format's public interface and its registration
    • CSBRoot *load(const QString &basedir, QIODevice *device) throw(CSBException)
    • void save(const QString &basedir, QIODevice &device, const CSBRoot &data) throw(CSBException)
    • bool isLoadable(const QString &filename) const
    • bool readonly(void) const;
    • QString getFilter(void) const
  • Data provider
    • int addExternalPage(const QString &filename)
    • int insertExternalPage(unsigned pos, const QString &filename)
    • void removePage(unsigned id)
    • QImage loadPage(unsigned page)
    • QString externalPageFile(unsigned page)
  • CSBRoot content specification
    • Entry class style
    • Entry class page
    • Entry class rectangle
    • Entry class ellipse

Your format's public interface and its registration

The format interface is defined by the FileFormat abstract class in common/comicdata.h. When you implement a new format for ComicSub, you have to derive your main class from FileFormat, create a global instance of the class and then register it in FormatRegister::registerFormats() in common/comicdata.cpp. Your main class must implement the following methods:

CSBRoot *load(const QString &basedir, QIODevice *device) throw(CSBException)

Method for loading a whole comicbook. The first argument, basedir, will contain a path from which to load external files. The second argument, device, will contain pointer to a valid QIODevice instance containing raw data for loading. Your format takes ownership of this device and it is your responsibility to close and delete it when you're done. You must also open the device yourself with the appropriate settings. You may keep it open as long as needed for your data provider.

You must return a valid non-NULL pointer to CSBRoot instance the contents of which must follow the data specification below. On error throw CSBException with information about the error (line number is optional, negative value means it is not applicable).

void save(const QString &basedir, QIODevice &device, const CSBRoot &data) throw(CSBException)

This method is optional. It will not be called when readonly() returns true. The first argument, basedir, will contain a path on which you can base relative paths to any external files you need to record. The second argument, device, will contain QIODevice instance to which you will save the data in your format. You must open the device yourself with the appropriate settings and close it before save() terminates. The last argument, data, will contain comicbook data following the specification below. On error throw CSBException with information about the error and negative line number.

bool isLoadable(const QString &filename) const

Return true if your format can load the file specified by the argument. Just checking filename extension is enough, you do not have to guarantee that load() will return successfully.

bool readonly(void) const;

This method is optional. Return true if your format does not implement save() (default behavior).

QString getFilter(void) const

Return single localized filter string for file dialogs.

Data provider

Data provider is an object which takes care of loading additional data (for now only page images). The base class DataProvider in common/comicdata.h provides basic implementation which only supports external files. Extend this class if you need to load data bundled in an archive.

Page images are assigned consecutive integer IDs starting with 0. Keeping all pages loaded is allowed but not recommended. Your data provider must implement the following methods:

int addExternalPage(const QString &filename)

External page support is mandatory. Check that the file specified by the argument can be successfully loaded and add it to the end of image list. Return its ID. On error return negative value.

int insertExternalPage(unsigned pos, const QString &filename)

External page support is mandatory. This method will behave the same as above except the file specified by the second argument will be inserted on the position specified by the first argument. Pages on position pos and greater will be moved to the next position. If pos is greater than the total number of pages, behave exactly as addExternalPage().

void removePage(unsigned id)

Remove page specified by the argument and move any pages after the removed page to their preceding position.

QImage loadPage(unsigned page)

Load and return page image specified by the argument. On error return null QImage.

QString externalPageFile(unsigned page)

Return absolute path to external file corresponding to page specified by the argument. If there is no such external file (for example because the page is loaded from an archive), return null QString.

CSBRoot content specification

Any CSBRoot instance passed between the application core and instances of classes derived from FileFormat will adhere to the following rules:

• The saveFormat member will be either NULL or it will contain a valid pointer to FileFormat instance whose readonly() method returns false. When the CSBRoot instance is returned from implementation of FileFormat::load(), it will contain NULL or pointer to object whose save() method outputs data in the same format as the file that was loaded. It may be a different object than the one which performed loading.
• The provider member will contain a valid pointer to data provider object. Page images recorded in the provider object will correspond to each page entry in children member. If there are no page entries in children member, the provider may be NULL.
• The children member will contain a tree of CSBEntry instances. The top level of the tree will contain entries of class style and page. All entries of class style must come before the first entry of class page. Entries of class page will correspond to page images recorded in provider member in the order in which they're listed, starting from page image 0.

Entry class style

Description of style for overlay.

Parameter	Permitted types	Description
name	String	Name of the style. The name must be unique within the comicbook. Only ASCII alphanumeric characters, dash and underscore are permitted. The name must be non-empty.
font-color	String	Color in the hexadecimal format #RRGGBB
background-color	String	Color in the hexadecimal format #RRGGBB
font-family	String	Name of font family.
font-size	Number	Size of the font. Minimum value is 1.
font-size-unit	Word	Unit for font-size parameter. Permitted values are pt (size in points) and px (size in pixels).
font-style	Word	Style of the font. Permitted values are normal, italic and oblique.
font-bold	Number	1 if the font is bold, 0 otherwise.
font-italic	Number	1 if the font is italic, 0 otherwise.
font-strikeout	Number	1 if font strikeout is enabled, 0 otherwise.
font-underline	Number	1 if the font is underlined, 0 otherwise.
horizontal-align	Word	Horizontal alignment of text. Permitted values are left, center, right and justify.
vertical-align	Word	Vertical alignment of text. Permitted values are top, center and bottom.

This class has no children.

Entry class page

Description of single page in the comicbook.

This class has no parameters.

This class may contain any number of children of class rectangle or ellipse. These entries may be freely mixed. They will be rendered as overlays in the order in which they're listed, the last on top.

Entry class rectangle

Rectangular overlay.

Parameter	Permitted types	Description
style	Word or String	If the type is string, this parameter contains name of existing style. If the type is word, its value will be none and the overlay will have the default style
text	String	Text rendered on the overlay.
text-rotation	Number	Angle of rotation for text on the overlay. Permitted values are between 0 and 359. 0 means normal horizontal text. The direction of rotation is not yet decided.
x	Number	Horizontal position of the top left corner.
y	Number	Vertical position of the top left corner.
width	Number	Width of the overlay.
height	Number	Height of the overlay.

This class has no children.

Entry class ellipse

Elliptical overlay.

Parameter	Permitted types	Description
style	Word or String	If the type is string, this parameter contains name of existing style. If the type is word, its value will be none and the overlay will have the default style
text	String	Text rendered on the overlay.
text-rotation	Number	Angle of rotation for text on the overlay. Permitted values are between 0 and 359. 0 means normal horizontal text. The direction of rotation is not yet decided.
x	Number	Horizontal position of the top left corner of bounding rectangle.
y	Number	Vertical position of the top left corner of bounding rectangle.
width	Number	Width of the overlay.
height	Number	Height of the overlay.

This class has no children.