How to Create Highlighted text through the API

Question

I am trying to create a script that goes through a document and cut/pastes specific elements to another document in FrameMaker 7.1.
So far, I can open a document and if an element is already highlighted/selected, i can cut the whole element using F_ApiCut().
I am having problems programatically trying to highlight the element that I want to copy.
So far, I have tried using the exampe from the FDKRef:
        //grab the selected element and set it to the elementRange
        er = F_ApiGetElementRange(FV_SessionId, docId, FP_ElementSelection);
        parentId = F_ApiGetId(docId, er.beg.childId, FP_ParentElement);
        er.end.parentId = er.beg.parentId = F_ApiGetId(docId, parentId, FP_ParentElement);
        // if the selected element is a child of the highest level element, the client returns here
        if(!er.end.parentId) return;
        er.beg.childId = parentId;
        er.beg.offset = er.end.offset = 0;
        er.end.childId = F_ApiGetId(docId, parentId, FP_NextSiblingElement);
        F_ApiSetElementRange(0, docId, FP_ElementSelection, &er);
        F_ApiCut(docId, 0);
but this only grabs an element that is already selected. Is there a way to select an element through the API?
Thanks for any help!

Answer 1

TrainingDeveloper,
There most certainly is a way. You can set up any kind of selection that you want, although it is definately a tricky process that can throw off even an experienced FDK developer. Here are my observations based on the code you pasted...
If you want to select an element, the first thing is that you need to have the ID of that element. I don't see anywhere in your code where an element ID is retrieved. All I see is the F_ApiGetElementRange which is getting the current selection, which in turn is likely why you just keep cutting the currently-selected element. If you want to get a specific element, that function call is not applicable. You only need to set up the element range structure to reflect the proper selection and then cut.
With that, assume that "elemId" is the ID of the element you want to cut. To select an entire element, you would do this:
F_ObjHandleT elemId, docId;
F_ElementRangeT er;
/* . . .   code here to get elemId, docId, etc. . . .  */
//set up the element range structure for whole-element selection
er.beg.childId = elemId;
er.beg.parentId = er.end.parentId =  F_ApiGetId(docId, elemId, FP_ParentElement);
er.end.childId = F_ApiGetId(docId, elemId,  FP_NextSiblingElement);
er.beg.offset = er.end.offset =  0;
//set the element selection in preparation for the cut
F_ApiSetElementRange(FV_SessionId, docId,  FP_ElementSelection, &er);
//... and cut
F_ApiCut(docId, 0);
I'm not sure what the sample you pasted is meant to accomplish. It is somewhere along the right track but it won't get you exactly what you want.
Now, I should say that the process of retrieving the desired element ID is a whole different challenge. I'm not sure if you know how to do that or not so I'll defer any discussion on that until you ask.
Russ