[KLF Backend][KLF Tools][KLF Home]
KLatexFormula Project
Classes | Static Public Member Functions | List of all members
KLFBackend Class Reference

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. More...
 
static QStringList availableSaveFormats (const klfOutput *output=NULL)
 Get a list of available output formats. More...
 
static QStringList availableSaveFormats (const klfOutput &output)
 Get a list of available output formats for saveOutputToDevice() More...
 
static bool saveOutputToFile (const klfOutput &output, const QString &fileName, const QString &format=QString(), QString *errorString=NULL)
 Save the output to image file. More...
 
static bool saveOutputToDevice (const klfOutput &output, QIODevice *device, const QString &format=QString("PNG"), QString *errorString=NULL)
 Saves the given output into the given device. More...
 
static bool detectSettings (klfSettings *settings, const QString &extraPath=QString(), bool isMainThread=true)
 Detects the system settings and stores the guessed values in settings. More...
 
static bool detectOptionSettings (klfSettings *settings, bool isMainThread=true)
 Detects additional options (e.g. klfSettings::wantSVG) that depend on specific program versions. More...
 
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 <phili.nosp@m.ppe..nosp@m.faist.nosp@m.@blu.nosp@m.ewin..nosp@m.ch>

Definition at line 206 of file klfbackend.h.

Member Function Documentation

◆ availableSaveFormats() [1/2]

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 1631 of file klfbackend.cpp.

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

◆ availableSaveFormats() [2/2]

QStringList KLFBackend::availableSaveFormats ( const klfOutput output)
static

◆ detectOptionSettings()

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 1831 of file klfbackend.cpp.

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

◆ 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 1766 of file klfbackend.cpp.

References QList::append(), KLFBackend::klfSettings::bborderoffset, KLFBackend::klfSettings::dvipsexec, KLFBackend::klfSettings::epstopdfexec, QDir::fromNativeSeparators(), KLFBackend::klfSettings::gsexec, QString::isEmpty(), QStringList::join(), KLF_DEBUG_TIME_BLOCK, KLF_FUNC_NAME, KLF_PATH_SEP, klfDbg, klfFmtCC, klfSearchPath(), KLFBackend::klfSettings::latexexec, KLFBackend::klfSettings::lborderoffset, KLFBackend::klfSettings::rborderoffset, QString::replace(), KLFBackend::klfSettings::tborderoffset, KLFBackend::klfSettings::tempdir, QDir::tempPath(), KLFBackend::klfSettings::wantPDF, and KLFBackend::klfSettings::wantSVG.

◆ getLatexFormula()

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;
}
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;
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 487 of file klfbackend.cpp.

References QString::arg(), KLFBackend::klfInput::bg_color, KLFBackend::klfInput::bypassTemplate, KLFBackend::klfSettings::calcEpsBoundingBox, QString::contains(), QMap::contains(), KLFBackend::klfOutput::dvidata, KLFBackend::klfOutput::epsdata, KLFBackend::klfOutput::epsdata_raw, KLFBackend::klfOutput::errorstr, KLFBackend::klfSettings::execenv, KLFBackend::klfSettings::gsexec, KLFBackend::klfOutput::input, QString::isEmpty(), QTemporaryDir::isValid(), KLF_ASSERT_NOT_NULL, KLF_DEBUG_TIME_BLOCK, KLF_FUNC_NAME, klfCurrentEnvironment(), klfDbg, klfDebugf, KlfEnvMergeExpandVars, KlfEnvPathPrepend, KLFERR_MISSINGLATEXFORMULA, KLFERR_MISSINGMATHMODETHREEDOTS, KLFERR_NOERROR, KLFERR_NOGSVERSION, KLFERR_TEMPDIR_FAIL, KLFERR_TEXWRITEFAIL, klfMergeEnvironment(), klfVersionCompare(), KLFBackend::klfInput::latex, KLFBackend::klfInput::mathmode, QFile::open(), QTemporaryDir::path(), KLFBackend::klfOutput::pdfdata, KLFBackend::klfOutput::pngdata, KLFBackend::klfOutput::pngdata_raw, QString::replace(), KLFBackend::klfOutput::result, KLFBackend::klfOutput::settings, KLFBackend::klfOutput::status, KLFBackend::klfOutput::svgdata, KLFBackend::klfSettings::tempdir, KLFBackend::klfSettings::templateGenerator, QObject::tr(), QString::trimmed(), KLFBackend::klfInput::userScript, and QMap::value().

Referenced by KLFLatexPreviewHandler::latexPreviewError().

◆ saveOutputToDevice()

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 1678 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().

◆ 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
outputthe data to save (e.g. as returned by getLatexFormula() )
fileNamethe file name to save to. If empty or equal to "-" then standard output is used.
formatthe format to use to save to fileName
errorStringif 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 1725 of file klfbackend.cpp.

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

◆ userScriptSettingsToEnvironment()

static QStringList KLFBackend::userScriptSettingsToEnvironment ( const QMap< QString, QString > &  userScriptSettings)
static
Bug:
........documentation ........

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

Generated by doxygen 1.8.13