How to write a Scribus Plugin

From 4669bb25fc218ac581eb9708e478cd40d3840a9b Mon Sep 17 00:00:00 2001 From: craig Date: Wed, 25 Apr 2012 20:57:24 +0000 Subject: Update Italian documentation git-svn-id: svn://scribus.net/branches/Version14x/Scribus@17472 11d20701-8431-0410-a711-e3c959e3b870 --- scribus/doc/it/plugin_howto.html | 322 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 322 insertions(+) create mode 100644 scribus/doc/it/plugin_howto.html (limited to 'scribus/doc/it/plugin_howto.html') diff --git a/scribus/doc/it/plugin_howto.html b/scribus/doc/it/plugin_howto.html new file mode 100644 index 0000000..a619d9d --- /dev/null +++ b/scribus/doc/it/plugin_howto.html @@ -0,0 +1,322 @@ + + + + How to write a Scribus Plugin + + +

How to write a Scribus Plugin

+ +

Preface

+ +

This article shows you how to write plugins for Scribus. Plugins are +libraries that are loaded into the main application at run-time. Plugins can +extend and to an extent modify the behavior of the application without having +to edit and recompile the core application. They are useful for adding extra tools, +extra import and export functions, and for various more advanced uses.

+ +

This document assumes some basic knowledge of C++. You're assumed to know +what a header file is, how include files work, know about classes an +inheritance, and have some general familiarity with the language. Some +familiarity with Qt - mainly QString and QObject - will also help. Issues like +virtual and pure virtual functions, "extern C" declarations, the details of +memory management, etc are glossed over and avoided in this document. You don't +have to know about them, but it'll help you follow what's going on better if +you do.

+ +

We're not going to try to explain the details of how the Scribus plugin +system works here. This is just about how to write a plugin. The documentation +in the scplugin.h and pluginmanager.h help explain +how the system works.

+ +

For any reasonable plugin idea, you will receive encouragement and assistance from the Scribus Team. +As rule, we do not do a lot of planning or development discussion by e-mail, but by IRC. Probably 99% of +the planning and project discussions take place there. You will find #scribus usually lively during parts of each day. The team is mostly resident in Europe, so Central European Time evenings is when it is busiest.

+ +

Where do I find Scribus Plugins?

+ +

Scribus ships with a number of standard plug-ins. These will be installed +along with the Scribus program and its other files. On UNIX, plug-ins will be +installed in the same prefix as the main app. In Mac OS X they're included in +the .app bundle. If you want to know what these plug-ins do, the easiest way to +find out is to to fire up Scribus and go into Edit->Preferences +and click on the "plugins" icon. From there you will see a list of what +plug-ins are installed, what type of plug-in they are, and where the files +are.

+ +

In addition to the plug-ins shipped as standard with Scribus, it is possible +to build and install plug-ins you obtain from elsewhere, or to write and add +your own.

+ +

Before you start coding

+ +

Let's suppose you've got a great idea to improve Scribus and you cannot wait +to start writing some excellent C++ code. Hold on for just a few minutes +and read this section; you might save yourself some time and trouble.

+ +

Important

+ +

Maybe you are at the edge of "reinventing the wheel" - that is, writing + something you don't have to because someone else has already done it. You + should probably join the mailing-list and post about your idea, or join the + #scribus channel on irc.freenode.net. Your topic will + be discussed and you will probably get some help and ideas from the developers + and from other users. As Scribus is freely licensed, you're welcome to work + on your own, but at least an introductory chat on IRC, or a mail to the + mailing list may save hours of work and head banging. We want to make + writing plug-ins as painless as possible for those who're interested. + +

Compatability

+ +

Scribus does not have a fixed C++ API for plugins to use. Releases are not + binary compatible, and unstable versions frequently break source compatibility. + Source compatibility is not currently guaranteed even across stable releases + if changes are required to fix a problem. We hope to improve this so we can + provide a stable C++ API for external code in the future. For now, if possible + you should try to bundle the core of your plugin's functionality into a + separate module that knows as little about the innards of Scribus as + possible.

+ +

This document covers implementing a plugin for Scribus 1.3.x. It is + dramatically different to what was required for the 1.2.x series. Future + changes should be smaller.

+ + +

Quick Start

+ +

It's not too hard to jump in and start writing a plugin. The documentation +below describes the implementation of a plugin in some detail, with references +to places where you can find out more if you need it. A "plugin template" is +provided for your use, so if you like you can get started by making a copy of +that and getting hacking. Some basic instructions are included in the file, and +if you get confused you can refer back to this document.

+ +

We'll build the plugin as a part of Scribus. That's the easiest way to get +started, though you'll probably want to start distributing it separately later +on (see later). To start work on an Action plugin:

+ +

We use CMake, as support for autotools has been +deprecated and moving forward it will be the only one used in 1.3.5+

+ +

Copy scribus/plugins/myplugin + to scribus/plugins/pluginname + (where "pluginname" is what you want to call your plugin). + pluginname must be a valid C identifier - I suggest + sticking to nothing but lower case characters.
Edit scribus/plugins/CmakeLists.txt and add + "pluginname" to it by adding the subdirectory to the others. This tells Scribus's build + system to compile your plugin.
rename all the files in scribus/plugins/pluginname/ + from myplugin to pluginname, eg + myplugin.h to pluginname.h. +
rename myplugin wherever it appears in the files to + pluginname, e.g. myplugin_getPluginAPIVersion() + to pluginname_getPluginAPIVersion(). Do the same for + MyPlugin and MYPLUGIN. On UNIX, you can use this + command:
+ sed -i -e "s/myplugin/pluginname/g" -e "s/MyPlugin/PluginName/g" -e "s/MYPLUGIN/PLUGINNAME/g" myplugin*
+ (all on one line, run from scribus/plugins/pluginname/). +

+ +

You're now ready to start work on your plug-in. First, you need to fill +out some information about your plug-in in pluginname.cpp:

+ +

In PluginName::languageChange(): +
- Change m_actionInfo.text to the text of the menu item + you want to trigger your plugin.
- Change m_actionInfo.menu to the name of the menu you + want the menu item to go in. See FIXME where???? + FIXME for a list of menu names.
- If you want your plugin to have a keyboard shortcut, uncomment + m_actionInfo.keySequence and set it to your preferred + shortcut. The example there should show you how that works.
+
Change the name in PluginName::fullTrName() + to the name of your plugin as you want it to appear in the Help->About Plugins dialog + box and in the Plugin Manager pane in the preferences.
If you want your plugin to have information such as author info and a + description when the user looks at it in Help->About Plugins, fill out + as much as you want of the about info by assigning members of + about. You can see what information can be provided by looking + at the definition of AboutData in + scplugin.h.

+ +

You've finished setting up the plugin, and can now start programming. Your +code should go in pluginnameimpl.cpp and +pluginnameimpl.h. The existing code should display a message +dialog box.

+ +

To compile the plugin, you can simply re-run cmake with your usual options. , +and make in the top-level Scribus directory. You may need to remove CmakeCache.txt, +but this is becoming a rarer necessity in newer versions of CMake. +When the compile completes, run make install and fire up Scribus. +Your plugin should now appear in the plugin manager (in the preferences), and +should have a menu item. If you press the menu item, a dialog box should appear.

+ +

Building plugins outside the Scribus tree

+ +

Quick and dirty using QMake

+ +

Warning

+ +

Beware - a qmake project easy to use but isn't necessarily the most standard + way to distribute software on the Linux platform. Scribus runs natively on Linux/Unix, MacOSX, OS/2 and + Windows. This process is an example + only for development. When you create your bug-free functional package then + make time to prepare a full featured distributon as described in the next section.

+ +

Let's compile it, but it isn't so easy as typing in

gcc
+		myplugin.cpp

;). One easy way to build it - Qt qmake (because some + people really really hate autoconf and automake in their complexity. We've been know to +call it worse things more than once. ). Note: you + will need to create an empty config.h file before running these + steps

On Linux or OSX systems where Qt3 and Qt4 are installed parallel, you may need to +provide the full path: e.g. /usr/lib/Qt4/qmake

+ +

+$qmake -project
+

+ +

Now the project file is created and we'll make just a few changes into it.

+######################################################################
+# Automatically generated by qmake (1.06c) Sun Dec 14 13:32:11 2003
+######################################################################
+
+#change TEMPLATE = app. We aren't working on application just plugin
+TEMPLATE = lib
+INCLUDEPATH += .
+#As working with Scribus, we need Scribus includes too.
+INCLUDEPATH += /home/subzero/devel/Scribus/include/Scribus/
+#And Scribus have to use freetype2.
+#So we should link it too. Use paths returned from
+##freetype-config --cflags and --libs
+INCLUDEPATH += /usr/include/freetype2
+LIBS += -lfreetype -lz
+
+# Input
+#create empty config.h file
+HEADERS += myplugin.h config.h
+SOURCES += myplugin.cpp
+

+ +

After these changes you're ready to compile

+ +

+$qmake
+$make
+

+ +

Running Qmake creates the Makefile and by running make you compile your + plugin.

+ +

Then just copy *so* files into Scribus plugin directory and run Scribus. + You'll see "Do Nothing Plugin" in the Extras menu.

+ +

It is clear that you have to use some other way to distribute your + source code to others - some use autogenerated qmake pro files, other use + the autoconf/automake combination.

+ +

Distribute it! (a.k.a. Compile it! 2nd edition)

+ +

Qmake is user frendly and useful for rapid development, but traditionally there has been + one standard way to compile/distribute software for Linux, *BSD etc. - autoconf + and automake. Lets call these two programs by the automagic acronym in the + following text.

+ +

To use automagic successfully you'll need chalk drawn to the north + oriented pentagram on the floor (Carrefour, 2€), red-black daemonic + dress (Hugo Boss, 2000€) and a sacrificed penguin on the home altar + (one hour of fear in your local zoo). Err, only joking.. dont harm any + nice little penguins, you wont need to. We strongly prefer the simpler and +easier to use CMake build system.

+ +

Download the donothingplugin-1.0.tar.gz example from + http://docs.scribus.net, unpack it and browse it.

+ + +

Learning More

+ +

To go on from here, you should probably read scplugin.h and ensure +you understand that. There is an explanation of the way the plugin system works +in more detail here. Above all else, though, you'll learn how +to get things done by reading the other plugins and the core Scribus code.

+ +

Storing your plugin's preferences:

+ +

Scribus provides a preferences api for plugin writers to store data between + Scribus launches. There are two types of storage formats available: key-value + pairs and tables.

+ +

First you will need to get the PrefsContext object for your + plugin. Then you can query PrefsContext to get the value for a + specific key or you can ask for a PrefsTable by it's name. Here is + a short example using key-value pairs.

+ +

+#include <prefsfile.h>
+#include <prefscontext.h>
+
+extern PrefsFile* prefsFile;
+
+PrefsContext *myPluginPrefs = prefsFile->getPluginContext("MyPlugin");
+
+// default value -1 will be used if "i" doesn't already exist
+int i = myPluginPrefs->getInt("i");
+
+// default value "dog" will be used if "s" doesn't already exist
+QString s = myPluginPrefs->get("s", "dog");
+
+myPluginPrefs->set("i", 221);
+myPluginPrefs->set("s", "cat");
+

+ +

Scribus Object Model

+ +

Scribus's source code is lightly documented. There is a significant + effort to correct this, but given the size of the codebase it's taking + quite some time. Please do try to follow what's going on based on the + header files and the code. If you're unable to sort it out, feel free to + drop in on IRC or ask on the mailing list, and someone may well be able to + help you. Try to be patient - we're not always on IRC or available, and it + can take time to answer a message if everybody's busy.

+ +

If you feel like improving the documentation or fixing the doxygen api + docs generation, the praise will be endless.

+ +

One important thing to understand is that the core Scribus application + can be accessed via the static global pointer ScApp, declared + in scribus.h. Confusingly, this is a QMainWindow subclass. + You can also get to the QApplication subclass used as ScQApp + from scribusapp.h.

+ +

Some major subsystems are singleton classes that are accessible via + ClassName::instance() . Examples include PluginManager, + ScPaths, and growing numbers of others. The advantage + of this is that you can interact with these classes without having to + delve into the guts of ScApp.

+ +

Plugin related links

+Qt documentation from Trolltech
+QMake documentation from Trolltech
+
+ + \ No newline at end of file -- cgit