Examples

Some examples may help you to understand how to use the scripting API. These examples and some more are found in the scripting directory of Kile: KILE_APP_DIR/scripts/. Each script contains a short description.

Example 1: replace environment name

Replace a surrounding LATEX environment with another, where the relative cursor position will not be changed. \begin{abc}...\end{abc} for example can be changed to \begin{xyz}...\end{xyz}.

var range = document.environmentRange(false);
if ( range.isValid() ) {
	var envname = kile.input.getLatexCommand("Enter Environment","New environment name:");
	if ( envname != '' ) {
		replaceEnvCommand(envname,range);
	}
}
else {
	kile.alert.sorry("No surrounding LaTeX environment found.");
}

function replaceEnvCommand(newEnv,r)
{
	var c = view.cursorPosition();

	var envname = document.environmentName();

	if ( envname != "" ) {
		var beginRange = new Range(r.start,new Cursor(r.start.line,r.start.column+8+envname.length));
		var endRange = new Range(new Cursor(r.end.line,r.end.column-6-envname.length),r.end);

		document.editBegin();
		document.replaceText(endRange,"\\end{"+newEnv+"}");
		document.replaceText(beginRange,"\\begin{"+newEnv+"}");
		document.editEnd();
	}
}

Example 2: replace a LATEX font command

Replace a surrounding LATEX font command with another font command, when the cursor is placed inside the texgroup. The relative cursor position will not be changed. \textbf{abc} for example can be changed to \textit{abc}.

var fontCommands = new Array("\\textbf","\\textit","\\textsl","\\texttt",
                             "\\textsc","\\textrm","\\textsf","\\emph");

var range = document.texgroupRange(false);
if ( range.isValid() ) {
	replaceFontCommand(range);
}
else {
	kile.alert.sorry("No surrounding TeX group found.");
}

function replaceFontCommand(r)
{
	var c = view.cursorPosition();

	document.editBegin();
	view.setCursorPosition(r.start);
	var cmd = document.latexCommand();
	var index = fontCommands.indexOf(cmd);
	if ( index >= 0 ) {
		var cmdRange = document.latexCommandRange();
		if ( cmdRange.isValid() ) {
			var newcommand = kile.input.getListboxItem("Choose",
			                            "Choose font command:",buildCmdList(cmd));
			if ( newcommand != "" ) {
				document.replaceText(cmdRange,newcommand);
				c.column = c.column - (cmd.length - newcommand.length);
			}
		}
/		view.setCursorPosition(c);
	}
	else {
		kile.alert.sorry("No surrounding font command found.");
	}
	document.editEnd();
}

function buildCmdList(current)
{
	var result = new Array();
	for ( i=0; i<fontCommands.length; ++i ) {
		if ( fontCommands[i] != current ) {
			result.push(fontCommands[i]);
		}
	}
	return result;
}

Example 3: surround selected text

Surround selected text with a TeX command, where the relative cursor position will not be changed. abc for example can be changed to \texcommand{abc}.

var range = view.selectionRange();

if ( range.isValid() ) {
	var cmd = kile.input.getLatexCommand("Choose","Choose surrounding LaTeX command:");
	if ( cmd != "" ) {
		surroundTexCommand("\\"+cmd,range);
	}
}
else {
	kile.alert.sorry("No selection found.");
}

function surroundTexCommand(cmd,r)
{
	var c = view.cursorPosition();

	document.editBegin();
	view.clearSelection();
	document.insertText(r.end,"}");
	document.insertText(r.start,cmd+"{");

	c.column = c.column + cmd.length + 2;
	view.setCursorPosition(c);
	document.editEnd();
}