This window will be used as parent for the component window and to support some UI relevant features of the frame service. Note: Re-parenting mustn't supported by a real frame implementation! It's designed for initializing - not for setting.

This frame will take over ownership of the window refered from xWindow. Thus, the previous owner is not allowed to dispose this window anymore.

Normally this is used as the parent window of the component window.

Only the creator is allowed to call this method. But creator doesn't mean the implementation which creates this instance ... it means the parent frame of the frame hierarchy. Because; normaly a frame should be created by using the api and is neccessary for searches inside the tree (e.g. XFrame::findFrame())

Normally the name of the frame is set initially (e.g. by the creator). The name of a frame will be used for identifying it if a frame search was started. These searches can be forced by:

• XFrame::findFrame()
• XDispatchProvider::queryDispatch()
• XComponentLoader::loadComponentFromURL()

Frames may contain other frames (e.g., a frameset) and may be contained in other frames. This hierarchy is searched with this method. First some special names are taken into account, i.e. "", "_self", "_top", "_blank" etc. SearchFlags is ignored when comparing these names with TargetFrameName; further steps are controlled by SearchFlags. If allowed, the name of the frame itself is compared with the desired one, and then ( again if allowed ) the method is called for all children of the frame. Finally may be called for the siblings and then for parent frame (if allowed).

List of special target names:

If no frame with the given name is found, a new top frame is created; if this is allowed by a special flag FrameSearchFlag::CREATE. The new frame also gets the desired name.

• (a) a special target ("_blank","_self" ...) or
• (b) any well known frame
to search it inside the current hierarchy

In general a top frame is the frame which is a direct child of a task frame or which does not have a parent. Possible frame searches must stop the search at such a frame unless the flag FrameSearchFlag::TASKS is set.

At first the frame sets itself as the active frame of its creator by calling XFramesSupplier::setActiveFrame(), then it broadcasts an FrameActionEvent with FrameAction::FRAME_ACTIVATED. The component within this frame may listen to this event to grab the focus on activation; for simple components this can be done by the FrameLoader.

Finally, most frames may grab the focus to one of its windows or forward the activation to a sub-frame.

At first the frame deactivates its active sub-frame, if any. Then broadcasts a FrameActionEvent with FrameAction::FRAME_DEACTIVATING.

A valid component window should be a child of the frame container window.

Simple components may implement a ::com::sun::star::awt::XWindow only. In this case no controller must be given here.

Note: Don't dispose this window - the frame is the owner of it.

Note: Don't dispose it - the frame is the owner of it. Use XController::getFrame() to dispose the frame after you the controller agreed with a XController::suspend() call.

According to a call to this interface, the frame calls XFrameEventListener::frameAction with FrameAction::CONTEXT_CHANGED to all listeners which are registered using XFrame::addFrameActionListener. For external controllers this event can be used to requery dispatches.

E.g., it is possible to determine instantiation/destruction and activation/deactivation of components.