Software Público Brasileiro

/*
This file is a part of the NVDA project.
URL: http://www.nvda-project.org/
Copyright 2006-2010 NVDA contributers.
    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License version 2.0, as published by
    the Free Software Foundation.
    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
This license can be found at:
http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
*/

cpp_quote("/*")
cpp_quote("This file is a part of the NVDA project.")
cpp_quote("URL: http://www.nvda-project.org/")
cpp_quote("Copyright 2006-2010 NVDA contributers.")
cpp_quote("This program is free software: you can redistribute it and/or modify")
cpp_quote("it under the terms of the GNU General Public License version 2.0, as published by")
cpp_quote("the Free Software Foundation.")
cpp_quote("This program is distributed in the hope that it will be useful,")
cpp_quote("but WITHOUT ANY WARRANTY; without even the implied warranty of")
cpp_quote("MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.")
cpp_quote("This license can be found at:")
cpp_quote("http://www.gnu.org/licenses/old-licenses/gpl-2.0.html")
cpp_quote("*/")

import "wtypes.idl";

/**
 * Renders content in to a virtual buffer
 */
[
uuid(28efdf2b-039b-48ec-b4d5-230eee90d186),
version(2.0)
]
interface VBuf {

	typedef [context_handle] void* VBufRemote_bufferHandle_t;
	typedef unsigned hyper VBufRemote_nodeHandle_t;

/**
 * Creates a new virtualBuffer
 * @param bindingHandle the binding handle for the inproc worker's rpc server
 * @param docHandle uniquely identifies the document or window being virtualized
 * @param ID uniquely identifies the object with in the document or window where rendering should start from
 * @param backendName The name of the backend (the path to the correct dll will be calculated automatically)
 * @return a handle identifying the new virtual buffer.
 */
	VBufRemote_bufferHandle_t createBuffer([in] handle_t bindingHandle, [in] int docHandle, [in] int ID, [in,string] const wchar_t* backendName);

/**
 * Destroies a virtual buffer
 * @param buffer a pointer to the virtual buffer you want to destroy
 */
	void destroyBuffer([in,out] VBufRemote_bufferHandle_t* buffer);

/**
 * Calculates the start and end character offsets of the given node in the buffer.
 * @param buffer the virtual buffer to use
 * @param node the node you want the offsets of.
 * @param startOffset memory where this method can place the found start offset.
 * @param endOffset memory where this method can place the found end offset.
 * @return true if successful, false otherwize.
 */
	int getFieldNodeOffsets([in] VBufRemote_bufferHandle_t buffer, [in] VBufRemote_nodeHandle_t node, [out] int *startOffset, [out] int *endOffset);

/**
 * finds out if a given field is positioned at a given character offset in this buffer.
 * @param buffer the virtual buffer you are interested in
 * @param node the field you are interested in.
 * @param offset the character offset you are interested in.
 * @return true if the field is at the offset, false otherwise.
 */
	int isFieldNodeAtOffset([in] VBufRemote_bufferHandle_t buffer, [in] VBufRemote_nodeHandle_t node, [in] int offset);

/**
 * locates the text field node at the given offset
 * @param buffer the virtual buffer to use
 * @param offset the offset to use
 * @param nodeStartOffset memory where the found text field's start offset will be placed.
 * @param nodeEndOffset memory where the found text field's end offset will be placed.
 * @param foundNode the located text field node.
 * @return non-zero if the node is found.
 */
	int locateTextFieldNodeAtOffset([in] VBufRemote_bufferHandle_t buffer, [in] int offset, [out] int *nodeStartOffset, [out] int *nodeEndOffset, [out] VBufRemote_nodeHandle_t* foundNode);

/**
 * locates the deepest control field node at the given offset
 * @param buffer the virtual buffer to use
 * @param offset the offset to use
 * @param startOffset memory where the found text field's start offset will be placed.
 * @param endOffset memory where the found text field's end offset will be placed.
 * @param docHandle memory where the docHandle of the found control field node will be placed.
 * @param ID memory where the ID of the found control field node will be placed.
 * @param foundNode the located control field node.
 * @return non-zero if the node is found.
 */
	 int locateControlFieldNodeAtOffset([in] VBufRemote_bufferHandle_t buffer, [in] int offset, [out] int *startOffset, [out] int *endOffset, [out] int* docHandle, [out] int* ID, [out] VBufRemote_nodeHandle_t* foundNode);

/**
 * locates the controlFieldNode with the given identifier
 * @param buffer the virtual buffer to use
 * @param docHandle the docHandle of the control field node you wish to find
 * @param ID the ID of the control field node you wish to find
 * @param foundNode the  controlFieldNode with the given identifier
 * @return non-zero if the node is found.
 */
	int getControlFieldNodeWithIdentifier([in] VBufRemote_bufferHandle_t buffer, [in] int docHandle, [in] int ID, [out] VBufRemote_nodeHandle_t* foundNode);

/**
 * Retreaves the identifier for the given controlFieldNode.
 * @param buffer the virtual buffer to use
 * @param node the controlFieldNode who's identifier should be retreaved.
 * @param docHandle a memory address where the docHandle should be placed.
 * @param ID a memory address where the ID should be placed.
 * @return non-0 if successfull.
 */
	int getIdentifierFromControlFieldNode([in] VBufRemote_bufferHandle_t buffer, [in] VBufRemote_nodeHandle_t node, [out] int* docHandle, [out] int* ID);

/**
 * Finds a field node that contains particular attributes.
 * @param buffer the virtual buffer to use
 * @param offset offset in the buffer to start searching from
 * @param direction which direction to search
 * @param attribs the attributes to search
 * @param regexp regular expression the requested attributes must match
 * @param startOffset memory where the start offset of the found node can be placed
 * @param endOffset memory where the end offset of the found node will be placed
 * @param foundNode the found field node
 * @return non-zero if the node is found.
 */
	int findNodeByAttributes([in] VBufRemote_bufferHandle_t buffer, [in] int offset, [in] int direction, [in,string] const wchar_t* attribs, [in,string] const wchar_t* regexp, [out] int *startOffset, [out] int *endOffset, [out] VBufRemote_nodeHandle_t* foundNode);

/**
 * Retreaves the current selection offsets for the buffer
 * @param buffer the virtual buffer to use
 * @param startOffset memory where the start offset of the selection will be placed
 * @param endOffset memory where the end offset of the selection will be placed
 * @return true if successfull, false otherwize.
 */
	int getSelectionOffsets([in] VBufRemote_bufferHandle_t buffer, [out] int* startOffset, [out] int *endOffset);

/**
 * sets the selection offsets for the buffer.
 * @param buffer the virtual buffer to use
 * @param startOffset the offset the start of the selection should be set to.
 * @param endOffset the offset the end of the selection should be set to.
 * @return true if successfull, false otherwize.
 */
	int setSelectionOffsets([in] VBufRemote_bufferHandle_t buffer, [in] int startOffset, [in] int endOffset);
 
/**
 * retreaves the length of all the text in the buffer.
 * @param buffer the virtual buffer to use
 * @return the length in characters of the text
 */
	int getTextLength([in] VBufRemote_bufferHandle_t buffer) const;

/**
 * Retreaves the text in the buffer between given offsets, optionally containing markup.
 * @param buffer the virtual buffer to use
 * @param startOffset the offset to start from
 * @param endOffset the offset to end at. Use -1 to mean end of buffer.
 * @param text: receives a pointer to the text in the given range
 * @param useMarkup if true then markup is included in the text denoting field starts and ends.
 * @return the text.
 */
	int getTextInRange([in] VBufRemote_bufferHandle_t buffer, [in] int startOffset, [in] int endOffset, [out,string] BSTR* text, [in] boolean useMarkup);

/**
 * Expands the given offset to the start and end offsets of the containing line.
 * @param buffer the virtual buffer to use
 * @param offset the offset to expand.
 * @param maxLineLength the maximum length of a line.
 * @param useScreenLayout if true then lines will only break on block controls or line feed characters, if false then lines will break on all field nodes.
 * @param startOffset memory to place the calculated line start offset
 * @param endOffset memory to place the calculated line end offset
  * @return true if successfull, false otherwize.
 */ 
	int getLineOffsets([in] VBufRemote_bufferHandle_t buffer, [in] int offset, [in] int maxLineLength, [in] boolean useScreenLayout, [out] int *startOffset, [out] int *endOffset);

/**
 * Retrieve the native handle for the object underlying a node.
 * This handle is used to retrieve the object out-of-process.
 * The way in which it is used is implementation specific.
 * @param buffer the virtual buffer to use
 * @param node the node in question.
 * @return the handle or 0 on error.
 */
	int getNativeHandleForNode([in] VBufRemote_bufferHandle_t buffer, [in] VBufRemote_nodeHandle_t node);

/**
 * Retrieve a node given the native handle for its underlying object.
 * This handle identifies the object out-of-process.
 * The way in which it is used is implementation specific.
 * @param buffer the virtual buffer to use
 * @param handle the handle in question.
 * @param node the node
 * @return non-zero if a node could be found.
 */
	int getNodeForNativeHandle([in] VBufRemote_bufferHandle_t buffer, [in] int handle, [out] VBufRemote_nodeHandle_t* node);

}