+@section overview_richtextctrl_nested_object Nested Objects
+
+wxRichTextCtrl supports nested objects such as text boxes and tables. To
+achieve compatibility with the existing API, there is the concept of @e object
+@e focus. When the user clicks on a nested text box, the object focus is set to
+that container object so all keyboard input and API functions apply to that
+container. The application can change the focus using
+wxRichTextCtrl::SetObjectFocus. Call this function with a @c null parameter to
+set the focus back to the top-level object.
+
+An event will be sent to the control when the focus changes.
+
+When the user clicks on the control, wxRichTextCtrl determines which container
+to set as the current object focus by calling the found container's overrided
+wxRichTextObject::AcceptsFocus function. For example, although a table is a
+container, it must not itself be the object focus because there is no text
+editing at the table level. Instead, a cell within the table must accept the
+focus.
+
+Since with nested objects it is not possible to represent a section with merely
+a start position and an end position, the class wxRichTextSelection is provided
+which stores multiple ranges (for non-contiguous selections such as table
+cells) and a pointer to the container object in question. You can pass
+wxRichTextSelection to wxRichTextCtrl::SetSelection or get an instance of it
+from wxRichTextCtrl::GetSelection.
+
+When selecting multiple objects, such as cell tables, the wxRichTextCtrl
+dragging handler code calls the function
+wxRichTextObject::HandlesChildSelections to determine whether the children can
+be individual selections. Currently only table cells can be multiply-selected
+in this way.
+
+
+@section overview_richtextctrl_context_menus Context Menus and Property Dialogs
+
+There are three ways you can make use of context menus: you can let
+wxRichTextCtrl handle everything and provide a basic menu; you can set your own
+context menu using wxRichTextCtrl::SetContextMenu but let wxRichTextCtrl handle
+showing it and adding property items; or you can override the default context
+menu behaviour by adding a context menu event handler to your class in the
+normal way.
+
+If you right-click over a text box in cell in a table, you may want to edit the
+properties of one of these objects - but which properties will you be editing?
+
+Well, the default behaviour allows up to three property-editing menu items
+simultaneously - for the object clicked on, the container of that object, and
+the container's parent (depending on whether any of these objects return @true
+from their wxRichTextObject::CanEditProperties functions). If you supply a
+context menu, add a property command item using the wxID_RICHTEXT_PROPERTIES1
+identifier, so that wxRichTextCtrl can find the position to add command items.
+The object should tell the control what label to use by returning a string from
+wxRichTextObject::GetPropertiesMenuLabel.
+
+Since there may be several property-editing commands showing, it is recommended
+that you don't include the word Properties - just the name of the object, such
+as Text Box or Table.
+
+
projects / wxWidgets.git / blobdiff