The main engine for KLatexFormula. More...

#include <klfbackend.h>

Classes
class	DefaultTemplateGenerator
struct	klfInput
	Specific input to KLFBackend::getLatexFormula() More...
struct	klfOutput
	KLFBackend::getLatexFormula() result. More...
struct	klfSettings
	General settings for KLFBackend::getLatexFormula() More...
class	TemplateGenerator
Static Public Member Functions
static klfOutput	getLatexFormula (const klfInput &in, const klfSettings &settings, bool isMainThread=true)
	The function that processes everything.
static QStringList	availableSaveFormats (const klfOutput *output=NULL)
	Get a list of available output formats.
static QStringList	availableSaveFormats (const klfOutput &output)
	Get a list of available output formats for saveOutputToDevice()
static bool	saveOutputToFile (const klfOutput &output, const QString &fileName, const QString &format=QString(), QString *errorString=NULL)
	Save the output to image file.
static bool	saveOutputToDevice (const klfOutput &output, QIODevice device, const QString &format=QString("PNG"), QString errorString=NULL)
	Saves the given output into the given device.
static bool	detectSettings (klfSettings *settings, const QString &extraPath=QString(), bool isMainThread=true)
	Detects the system settings and stores the guessed values in `settings`.
static bool	detectOptionSettings (klfSettings *settings, bool isMainThread=true)
	Detects additional options (e.g. klfSettings::wantSVG) that depend on specific program versions.
static QStringList	userScriptSettingsToEnvironment (const QMap< QString, QString > &userScriptSettings)

Detailed Description

The main engine for KLatexFormula.

The main engine for KLatexFormula, providing core functionality of transforming LaTeX code into graphics.

Don't instanciate this class, use the static function KLFBackend::getLatexFormula() to do all the processing.

Author:: Philippe Faist <philippe.faist@bluewin.ch>

Definition at line 206 of file klfbackend.h.

Member Function Documentation

QStringList KLFBackend::availableSaveFormats ( const klfOutput * output = NULL ) [static]

Get a list of available output formats.

If output is non-NULL, then this function is an alias for availableSaveFormats(const klfOutput&).

If output is NULL, then a list of in principle availble output formats is returned, such as

 QStringList() << "PNG" << "PS" << "EPS" << "DVI" << "PDF" << "SVG" << (qt-image-formats);

In this case, not all the given formats are garanteed to be availble; there may be some klfOutput objects where for example a user script has not provided a way to generate some optional formats like PDF or SVG. Provide a valid pointer to output to get an exact list of available formats.

Note:: If Jpeg format is available, only "JPEG" will be reported and not "JPG".

Definition at line 1644 of file klfbackend.cpp.

References QStringList::contains(), QString::fromLatin1(), QImageWriter::supportedImageFormats(), QByteArray::toUpper(), and QByteArray::trimmed().

QStringList KLFBackend::availableSaveFormats ( const klfOutput & output ) [static]

Get a list of available output formats for saveOutputToDevice()

Note:: If Jpeg format is available, only "JPEG" will be reported and not "JPG".

Definition at line 1664 of file klfbackend.cpp.

References QStringList::contains(), KLFBackend::klfOutput::dvidata, KLFBackend::klfOutput::epsdata, QString::fromLatin1(), QByteArray::isEmpty(), KLFBackend::klfOutput::pdfdata, KLFBackend::klfOutput::pngdata, QImageWriter::supportedImageFormats(), KLFBackend::klfOutput::svgdata, QByteArray::toUpper(), and QByteArray::trimmed().

KLF_EXPORT bool KLFBackend::detectOptionSettings	(	klfSettings *	settings,
		bool	isMainThread = `true`
	)		`[static]`

Detects additional options (e.g. klfSettings::wantSVG) that depend on specific program versions.

settings is assumed to be a valid settings object with paths set. This function:

queries gs for whether it has an SVG device and sets klfSettings::wantSVG accordingly;

sees if additional environment variables are needed to run the given programs (in particular for mgs.exe ghostscript in MikTeX) and stores those into klfSettings::execenv. Note that the environment settings already existing in settings->execenv are kept; only those variables for which new values are detected are updated, or if new declarations are needed they are appended.

Possibly in the future it might fill in further optional fields in klfSettings that rely on specific features or versions of the installed programs.

Note:: detectSettings() already calls this function. You do not need to call it again if you're using detectSettings().

Returns TRUE or FALSE to indicate success or failure.

Definition at line 1844 of file klfbackend.cpp.

References QMap::contains(), KLFBackend::klfSettings::gsexec, KLF_DEBUG_TIME_BLOCK, KLF_FUNC_NAME, klfWarning, QString::length(), and KLFBackend::klfSettings::wantSVG.

Referenced by detectSettings().

bool KLFBackend::detectSettings	(	klfSettings *	settings,
		const QString &	extraPath = `QString()`,
		bool	isMainThread = `true`
	)		`[static]`

Detects the system settings and stores the guessed values in settings.

This function tries to find the latex, dvips, gs, and epstopdf in standard locations on the current platform.

Detects gs version to see if SVG is supported, saved in wantSVG setting.

The temporary directory is set to the system temporary directory.

If isMainThread is set to TRUE (the default), then we assume that we're called by the main application thread, and will call QApplication::processEvents() regularly during process executions to prevent the GUI from freezing. Make sure you set FALSE here if you're not in the GUI thread.

Definition at line 1779 of file klfbackend.cpp.

KLFBackend::klfOutput KLFBackend::getLatexFormula	(	const klfInput &	in,
		const klfSettings &	settings,
		bool	isMainThread = `true`
	)		`[static]`

The function that processes everything.

Pass on a valid klfInput input object, as well as a klfSettings object filled with your input and settings, and you will get output in klfOutput.

If isMainThread is set to TRUE (the default), then we assume that we're called by the main application thread, and will call QApplication::processEvents() regularly during process executions to prevent the GUI from freezing. Make sure you set FALSE here if you're not in the GUI thread.

If an error occurs, klfOutput::status is non-zero and klfOutput::errorstr contains an explicit error in human-readable form. The latter is Qt-Translated with QObject::tr() with "KLFBackend" comment.

Usage example:

   ...
   // this could have been declared at some more global scope
   KLFBackend::klfSettings settings;
   bool ok = KLFBackend::detectSettings(&settings);
   if (!ok) {
     // vital program not found
     raise_error("error in your system: are latex,dvips and gs installed?");
     return;
   }

   KLFBackend::klfInput input;
   input.latex = "\\int_{\\Sigma}\\!(\\vec{\\nabla}\\times\\vec u)\\,d\\vec S ="
     " \\oint_C \\vec{u}\\cdot d\\vec r";
   input.mathmode = "\\[ ... \\]";
   input.preamble = "\\usepackage{somerequiredpackage}\n";
   input.fg_color = qRgb(255, 168, 88); // beige
   input.bg_color = qRgba(0, 64, 64, 255); // dark turquoise
   input.dpi = 300;

   KLFBackend::klfOutput out = KLFBackend::getLatexFormula(input, settings);

   if (out.status != 0) {
     // an error occurred. an appropriate error string is in out.errorstr
     display_error_to_user(out.errorstr);
     return;
   }

   myLabel->setPixmap(QPixmap(out.result));

   // write contents of 'out.pdfdata' to a file to get a PDF file (for example)
   {
     QFile fpdf(fname);
     fpdf.open(IO_WriteOnly | IO_Raw);
     fpdf.writeBlock(out.pdfdata);
   }
   ...

Note:: This function is safe for threads; it locks a mutex at the beginning and unlocks it at the end; so if a call to this function is issued while a first call is already being processed in another thread, the second waits for the first call to finish. However, if you are not running this from the main thread, you should be sure to pass FALSE to isMainThread, in order to prevent this function from allowing the application to process events during process executions.

Bug:: .... CORRECT DPI FOR Vector Scale SETTING !!!!!!!!!!!!............. but do that cleverly; ie. make sure that the EPS was indeed vector-scaled up. Possibly run the EPS generator twice, once to scale it up, the other for PNG conversion reference.

Definition at line 488 of file klfbackend.cpp.

bool KLFBackend::saveOutputToDevice	(	const klfOutput &	output,
		QIODevice *	device,
		const QString &	format = `QString("PNG")`,
		QString *	errorString = `NULL`
	)		`[static]`

Saves the given output into the given device.

Overloaded function, provided for convenience. Behaves very much like saveOutputToFile(), except that the format cannot be guessed.

Definition at line 1691 of file klfbackend.cpp.

References QString::arg(), KLFBackend::klfOutput::dvidata, KLFBackend::klfOutput::epsdata, QByteArray::isEmpty(), KLFBackend::klfOutput::pdfdata, KLFBackend::klfOutput::pngdata, KLFBackend::klfOutput::result, QImage::save(), KLFBackend::klfOutput::svgdata, QString::toLatin1(), QString::toUpper(), QObject::tr(), QString::trimmed(), and QIODevice::write().

Referenced by saveOutputToFile().

bool KLFBackend::saveOutputToFile	(	const klfOutput &	output,
		const QString &	fileName,
		const QString &	format = `QString()`,
		QString *	errorString = `NULL`
	)		`[static]`

Save the output to image file.

This function can be used to write output obtained with the getLatexFormula() function, to a file named fileName with format format.

Parameters:

output	the data to save (e.g. as returned by getLatexFormula() )
fileName	the file name to save to. If empty or equal to `"-"` then standard output is used.
format	the format to use to save to fileName
errorString	if a valid pointer, then when an error occurs this string is set to a text describing the error.

If format is an empty string, then format is guessed from filename extension; if no extension is found then format defaults to PNG.

fileName 's extension is NOT adjusted if it does not match an explicitely given format, for example

 saveOutputToFile(output, "myfile.jpg", "PDF");

will output PDF data to the file "myfile.jpg".

If errorString is non-NULL, then it is set to a human-readable description of the error that occurred if this function returns FALSE. It is left untouched if success.

Returns:: TRUE if success or FALSE if failure.

qWarning()s are emitted in case of failure.

Definition at line 1738 of file klfbackend.cpp.

References QString::arg(), QFileDevice::error(), QString::isEmpty(), QFile::open(), saveOutputToDevice(), QFile::setFileName(), QFileInfo::suffix(), QString::toUpper(), QObject::tr(), and QString::trimmed().

static QStringList KLFBackend::userScriptSettingsToEnvironment ( const QMap< QString, QString > & userScriptSettings ) [static]

Bug:: ........documentation ........

The documentation for this class was generated from the following files:

src/klfbackend/klfbackend.h
src/klfbackend/klfbackend.cpp

Classes

Static Public Member Functions

Detailed Description

Member Function Documentation